MCP Integration

Overview

Connect Model Context Protocol servers to Claude Code plugins to expose external service capabilities as tools.

Configuration Methods

Dedicated .mcp.json (Recommended)

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Inline in plugin.json

{
  "name": "my-plugin",
  "mcpServers": {
    "my-server": { ... }
  }
}

Server Types

stdio (Local Process)

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server"]
}

HTTP (REST API)

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

SSE (Server-Sent Events)

{
  "type": "sse",
  "url": "https://mcp.example.com/sse",
  "headers": {
    "X-API-Key": "${API_KEY}"
  }
}

WebSocket

{
  "type": "websocket",
  "url": "wss://mcp.example.com/ws"
}

Environment Variables

Use ${VAR_NAME} for dynamic values:

{
  "env": {
    "DATABASE_URL": "${DATABASE_URL}",
    "API_KEY": "${API_KEY}"
  }
}

Plugin Portability

Use ${CLAUDE_PLUGIN_ROOT} for relative paths:

{
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/server/index.js"]
}

Security Best Practices

1. Use HTTPS/WSS - Never use HTTP for remote servers
2. Never hardcode tokens - Use environment variables
3. Pre-allow specific tools - Avoid wildcards in permissions
4. Document required variables - List in README

Testing

# Verify MCP configuration
/mcp

# Check server status
/mcp status

Workflow

1. Select server type based on deployment
2. Create .mcp.json configuration
3. Use ${CLAUDE_PLUGIN_ROOT} for portability
4. Document environment variables
5. Test locally via /mcp command
6. Configure tool permissions
7. Handle authentication and errors