create-mcp-servers

<quick_start>

1. Choose server type: stdio (local), SSE (hosted/OAuth), HTTP (REST/token), WebSocket (real-time)
2. Create .mcp.json at plugin root (or add to plugin.json inline)
3. Configure command/URL, args, env vars using ${CLAUDE_PLUGIN_ROOT} for paths
4. Test with /mcp command and claude --debug </quick_start>

<essential_principles> <security_rules>

1. Never hardcode secrets -- use ${VAR} expansion in configs, environment variables in code
2. Use cwd property -- isolates dependencies (not --cwd in args)
3. Always absolute paths -- which uv to find paths, never relative
4. One server per directory -- ~/Developer/mcp/{server-name}/
5. Use uv for Python -- handles venvs automatically, better than pip </security_rules>

<architecture_decision> Operation count determines architecture:

• 1-2 operations: Traditional pattern -- each operation is a separate tool
• 3+ operations: On-demand discovery pattern -- 4 meta-tools (discover, get_schema, execute, continue) + operations.json

Traditional is simpler. On-demand scales better and reduces tool clutter. </architecture_decision> </essential_principles>

Type	Transport	Best For	Authentication
stdio	Local process	Custom servers, local tools, NPM packages	Environment vars
SSE	Server-Sent Events	Hosted services (Asana, GitHub), cloud APIs	OAuth (automatic)
HTTP	REST	API backends, token-based auth, stateless	Bearer tokens
WebSocket	ws/wss	Real-time streaming, persistent connections	Tokens/headers

See references/server-types.md for detailed configuration per type. </step_1_choose_type>

<step_2_configure> Method 1: Dedicated .mcp.json (recommended for plugins):

{
  "server-name": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "API_KEY": "${API_KEY}"
    }
  }
}

Method 2: Inline in plugin.json (simple single-server):

{
  "name": "my-plugin",
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"]
    }
  }
}

SSE example:

{
  "service-name": {
    "type": "sse",
    "url": "https://mcp.service.com/sse"
  }
}

HTTP example:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}

WebSocket example:

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws"
  }
}

Environment variables expand automatically: ${VAR_NAME} pulls from user's shell. Always use ${CLAUDE_PLUGIN_ROOT} for intra-plugin paths. </step_2_configure>

<step_3_tool_naming> MCP tools are auto-prefixed when registered:

Format: mcp__plugin_<plugin-name>_<server-name>__<tool-name>

Example for plugin asana, server asana, tool create_task: mcp__plugin_asana_asana__asana_create_task

Pre-allow specific tools in commands:

allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]

Avoid wildcards (mcp__plugin_asana_asana__*) -- pre-allow specific tools for security. </step_3_tool_naming>

<step_4_authentication> OAuth (SSE/HTTP): Handled automatically by Claude Code. User authenticates in browser on first use. No configuration needed beyond the URL.

Token-based: Use environment variables in headers:

{
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}