MCP Integration

Add MCP servers and integrate Model Context Protocol into Claude Code plugins.

Category: Development

About this skill

Configure and integrate MCP (Model Context Protocol) servers into Claude Code plugins. Handles .mcp.json configuration, external service connections, and protocol setup.

Source and installation instructions

Installation

  1. Add to Claude Code plugins

Documentation

MCP Integration for Claude Code Plugins

Overview

Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.

Key capabilities:

MCP Server Configuration Methods

Plugins can bundle MCP servers in two ways:

Method 1: Dedicated .mcp.json (Recommended)

Create .mcp.json at plugin root:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Benefits:

Method 2: Inline in plugin.json

Add mcpServers field to plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Benefits:

MCP Server Types

stdio (Local Process)

Execute local MCP servers as child processes. Best for local tools and custom servers.

Configuration:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

Use cases:

Process management:

SSE (Server-Sent Events)

Connect to hosted MCP servers with OAuth support. Best for cloud services.

Configuration:

{
  "asana": {
    "type": "sse",
    "url": "https://mcp.asana.com/sse"
  }
}

Use cases:

Authentication:

HTTP (REST API)

Connect to RESTful MCP servers with token authentication.

Configuration:

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

Use cases:

WebSocket (Real-time)

Connect to WebSocket MCP servers for real-time bidirectional communication.

Configuration:

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Use cases:

Environment Variable Expansion

All MCP configurations support environment variable substitution:

${CLAUDE_PLUGIN_ROOT} - Plugin directory (always use for portability):

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

User environment variables - From user's shell:

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

Best practice: Document all required environment variables in plugin README.

MCP Tool Naming

When MCP servers provide tools, they're automatically prefixed:

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

Example:

Using MCP Tools in Commands

Pre-allow specific MCP tools in command frontmatter:

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

Wildcard (use sparingly):

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

Best practice: Pre-allow specific tools, not wildcards, for security.

Lifecycle Management

Automatic startup:

Lifecycle:

  1. Plugin loads
  2. MCP configuration parsed
  3. Server process started (stdio) or connection established (SSE/HTTP/WS)
  4. Tools discovered and registered
  5. Tools available as mcp__plugin_...__...

Viewing servers: Use /mcp command to see all servers including plugin-provided ones.

Authentication Patterns

OAuth (SSE/HTTP)

OAuth handled automatically by Claude Code:

{
  "type": "sse",
  "url": "https://mcp.example.com/sse"
}

User authenticates in browser on first use. No additional configuration needed.

Token-Based (Headers)

Static or environment variable tokens:

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

Document required environment variables in README.

Environment Variables (stdio)

Pass configuration to MCP server:

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

Integration Patterns

Pattern 1: Simple Tool Wrapper

Commands use MCP tools with user interaction:

# Command: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

Steps:
1. Gather item details from user
2. Use mcp__plugin_name_server__create_item
3. Confirm creation

Use for: Adding validation or preprocessing before MCP calls.

Pattern 2: Autonomous Agent

Agents use MCP tools autonomously:

# Agent: data-analyzer.md

Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report

Use for: Multi-step MCP workflows without user interaction.

Pattern 3: Multi-Server Plugin

Integrate multiple MCP servers:

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "jira": {
    "type": "sse",
    "url": "https://mcp.jira.com/sse"
  }
}

Use for: Workflows spanning multiple services.

Security Best Practices

Use HTTPS/WSS

Always use secure connections:

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

Token Management

DO:

DON'T:

Permission Scoping

Pre-allow only necessary MCP tools:

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

Error Handling

Connection Failures

Handle MCP server unavailability:

Tool Call Errors

Handle failed MCP operations:

Configuration Errors

Validate MCP configuration:

Performance Considerations

Lazy Loading

MCP servers connect on-demand:

Batching

Batch similar requests when possible:

# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)

# Avoid: Many individual queries
for id in task_ids:
    task = get_task(id)

Testing MCP Integration

Local Testing

  1. Configure MCP server in .mcp.json
  2. Install plugin locally (.claude-plugin/)
  3. Run /mcp to verify server appears
  4. Test tool calls in commands
  5. Check claude --debug logs for connection issues

Validation Checklist

Debugging

Enable Debug Logging

claude --debug

Look for:

Common Issues

Server not connecting:

Tools not available:

Authentication failing:

Quick Reference

MCP Server Types

TypeTransportBest ForAuth
stdioProcessLocal tools, custom serversEnv vars
SSEHTTPHosted services, cloud APIsOAuth
HTTPRESTAPI backends, token authTokens
wsWebSocketReal-time, streamingTokens

Configuration Checklist

Best Practices

DO:

DON'T:

Additional Resources

Reference Files

For detailed information, consult:

Example Configurations

Working examples in examples/:

External Resources

Implementation Workflow

To add MCP integration to a plugin:

  1. Choose MCP server type (stdio, SSE, HTTP, ws)
  2. Create .mcp.json at plugin root with configuration
  3. Use ${CLAUDE_PLUGIN_ROOT} for all file references
  4. Document required environment variables in README
  5. Test locally with /mcp command
  6. Pre-allow MCP tools in relevant commands
  7. Handle authentication (OAuth or tokens)
  8. Test error cases (connection failures, auth errors)
  9. Document MCP integration in plugin README

Focus on stdio for custom/local servers, SSE for hosted services with OAuth.