Create a Bridge (橋 - Hashi) Plugin

Create a Bridge (橋 - Hashi) Plugin

Create a new bridge plugin for: $ARGUMENTS

What is a Bridge Plugin?

Bridge plugins provide access to external knowledge and capabilities through MCP servers. A bridge connects Claude Code to external services, APIs, databases, or specialized tools that extend Claude's capabilities.

Plugin Structure

Create the following directory structure:

plugins/​services/​{service-name}/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (ONLY plugin.json goes here)
├── han-plugin.yml           # MCP server config + hooks + memory (at plugin root)
└── README.md               # Plugin documentation

Categories

IMPORTANT:

• Only plugin.json goes inside .claude-plugin/ (NO mcpServers here)
• MCP server config goes in han-plugin.yml at plugin root
• han-plugin.yml is the single source of truth for MCP config
• Bridge plugins typically don't include skills or agents

Step 1: Create plugin.json

Create .claude-plugin/​plugin.json (metadata only, NO mcpServers):

{
  "name": "{service-name}",
  "version": "1.0.0",
  "description": "MCP server configuration for {Service Name} integration providing {key capabilities}.",
  "author": {
    "name": "The Bushido Collective",
    "url": "https://thebushido.co"
  },
  "homepage": "https://github.com/​thebushidocollective/​han",
  "repository": "https://github.com/​thebushidocollective/​han",
  "license": "MIT",
  "keywords": [
    "mcp",
    "{service-type}",
    "{capability}",
    "server"
  ]
}

Step 2: Create han-plugin.yml

Create han-plugin.yml at the plugin root with the MCP server configuration.

Preferred: HTTP Transport

mcp:
  name: {server-name}
  description: {Brief description of capabilities}
  type: http
  url: https://mcp.service.com/​mcp

Alternative: NPX Package

mcp:
  name: {server-name}
  description: {Brief description of capabilities}
  command: npx
  args:
    - -y
    - "@scope/​package-name"

With Environment Variables

mcp:
  name: {server-name}
  description: {Brief description of capabilities}
  command: npx
  args:
    - -y
    - "@scope/​package"
  env:
    API_KEY: ${SERVICE_API_KEY}

Step 3: Write README.md

# {Service Name}

{Description of what this MCP server provides}

## What This Plugin Provides

### MCP Server: {server-name}

- **{Capability 1}**: {Description}
- **{Capability 2}**: {Description}

## Installation

\`\`\`bash
han plugin install {service-name}
\`\`\`

## Configuration

Set required environment variables:

\`\`\`bash
export {ENV_VAR}="your-value-here"
\`\`\`

Step 4: Register in Marketplace

Add your plugin to .claude-plugin/​marketplace.json:

{
  "name": "{service-name}",
  "description": "MCP server for {Service Name} integration providing {key capabilities}.",
  "source": "./​plugins/​services/​{service-name}",
  "category": "Bridge",
  "keywords": [
    "mcp",
    "{keyword1}",
    "{keyword2}",
    "server"
  ]
}

Best Practices

DO

• Put MCP config in han-plugin.yml, NOT in plugin.json
• Prefer HTTP transport over stdio when available
• Use well-maintained MCP server packages
• Document all environment variables clearly

DON'T

• Don't put mcpServers in plugin.json (use han-plugin.yml)
• Don't hardcode API keys or secrets
• Don't use Docker unless no HTTP or npx option exists

Examples of Well-Structured Bridge Plugins

• github: HTTP transport with OAuth
• sentry: HTTP-based MCP server
• reddit: Simple uvx-based MCP server

Questions?

See the Han documentation or ask in GitHub Discussions.