MCP Integrations

Han provides an MCP server and integrates with external MCP servers.

Han uses the Model Context Protocol (MCP) to connect Claude Code to external services and provide built-in capabilities. MCP is an open standard for connecting AI assistants to data sources and tools.

Han's Built-in MCP Server

Han provides its own MCP server that runs via han mcp server and exposes powerful built-in capabilities. When you install the core plugin, Han registers as an MCP server in Claude Code's configuration.

How It Works

The Han MCP server is automatically configured:

{
  "mcpServers": {
    "han": {
      "command": "han",
      "args": ["mcp", "server"]
    }
  }
}

The server implements MCP protocol version 2024-11-05 and exposes tools in four categories:

1. Plugin Hook Tools (Dynamic)

Every hook defined in an installed plugin automatically becomes an MCP tool. When you install jutsu-typescript, Claude immediately gains access to a jutsu_typescript_typecheck tool.

Example from jutsu-bun/han-plugin.yml:

hooks:
  test:
    command: bun test --only-failures
    dirsWith: [bun.lock, bun.lockb]
    description: Run Bun tests

This becomes an MCP tool:

{
  name: "jutsu_bun_test",
  description: "Run Bun tests. Triggers: 'run the tests'...",
  inputSchema: {
    type: "object",
    properties: {
      cache: { type: "boolean" },
      directory: { type: "string" },
      verbose: { type: "boolean" }
    }
  }
}

All plugin hooks support three standard parameters:

ParameterDefaultPurpose
cachetrueSkip if files unchanged since last run
directoryallTarget specific directory
verbosefalseStream output in real-time

2. Memory Tools (Self-Learning)

Han's memory system lets Claude write to .claude/rules/ to capture project knowledge.

learn - Capture project knowledge:

learn({
  content: "# API Rules\n\n- Validate all inputs with zod",
  domain: "api",
  paths: ["src/api/**/*.ts"],  // Optional: path-specific rules
  scope: "project",  // or "user" for personal preferences
  append: true  // Add to existing file
})

memory_list - See existing domains:

memory_list({ scope: "project" })
// Returns: ["api", "testing", "commands"]

memory_read - Read domain content:

memory_read({ domain: "api", scope: "project" })

Memory scopes:

ScopeLocationPurpose
project.claude/rules/Team knowledge, git-tracked
user~/.claude/rules/Personal preferences

3. Metrics Tools (Self-Awareness)

Task tracking with confidence calibration. See Local Metrics for details.

start_task - Begin tracking:

start_task({
  description: "Fix authentication timeout bug",
  type: "fix",
  estimated_complexity: "moderate"
})

complete_task - Record outcome:

complete_task({
  task_id: "task_abc123",
  outcome: "success",
  confidence: 0.85,
  files_modified: ["src/auth/session.ts"]
})

query_metrics - Analyze performance:

query_metrics({
  period: "week",
  task_type: "fix"
})

4. Checkpoint Tools (Smart Caching)

Track file changes since last hook run for intelligent caching.

checkpoint_list - See existing checkpoints checkpoint_clean - Remove stale checkpoints

External MCP Servers (Hashi Plugins)

Han's "hashi" (bridge) plugins connect Claude to external services via MCP. Each hashi plugin is an MCP server that provides tools for interacting with a specific service.

Available Hashi Plugins

  • hashi-github - GitHub Issues, PRs, Actions, Code Search
  • hashi-jira - Jira tickets, sprints, workflows
  • hashi-playwright-mcp - Browser automation and testing
  • hashi-linear - Linear issues and project management
  • hashi-sentry - Error tracking and performance monitoring
  • hashi-figma - Design-to-code workflows
  • hashi-gitlab - GitLab integration
  • hashi-blueprints - Technical documentation management

Installing External MCP Servers

Install a hashi plugin to add its MCP server:

# Install GitHub integration
han plugin install hashi-github

This adds the MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

How MCP Tools Appear in Claude Code

Once installed, MCP tools are available to Claude automatically. You can simply ask Claude to use them:

Examples:

"Create an issue for the bug we just found"
"List all open PRs that need review"
"Search for usages of the deprecated function"
"Run the tests"
"Take a screenshot of the login page"

Claude will use the appropriate MCP tool (create_issue, list_pull_requests, search_code, jutsu_bun_test, browser_take_screenshot, etc.) based on your request.

Real Example: GitHub Integration

After installing hashi-github, Claude can:

Search code across repos:

const results = await mcp.tools.search_code({
  query: 'useDeprecatedAPI language:typescript',
  owner: 'myorg'
})

Create issues with context:

await mcp.tools.create_issue({
  owner: 'myorg',
  repo: 'myrepo',
  title: 'Memory leak in useEventListener hook',
  body: '## Description\nFound memory leak...',
  labels: ['bug', 'priority:high']
})

Review pull requests:

const diff = await mcp.tools.get_pull_request_diff({
  owner: 'myorg',
  repo: 'myrepo',
  pullNumber: 123
})

Security Considerations

MCP servers can access sensitive data. Han follows these principles:

  1. Token isolation - Environment variables, never hardcoded
  2. Least privilege - Only request necessary scopes
  3. Local execution - Servers run on your machine, not in the cloud
  4. Audit trail - All MCP calls are logged

Performance

MCP calls are asynchronous and don't block Claude's reasoning:

// Claude can make multiple MCP calls in parallel
const [issues, prs, actions] = await Promise.all([
  github.list_issues({ state: 'open' }),
  github.list_pull_requests({ state: 'open' }),
  github.get_workflow_runs({ branch: 'main' })
])

Getting Started

Start with GitHub integration:

# Set your token
export GITHUB_TOKEN=ghp_your_token_here

# Install the plugin
han plugin install hashi-github

# Ask Claude to help with GitHub tasks

Then try:

  • "Create an issue for the bug we just found"
  • "List all open PRs that need review"
  • "Search for usages of the deprecated function"

Claude handles the API calls, authentication, and data formatting. You just describe what you want.

Learn More