npx skills add ...
npx skills add sanity-io/claude-plugins-official --skill mcp-integration
npx skills add sanity-io/claude-plugins-official --skill mcp-integration
This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
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:
Plugins can bundle MCP servers in two ways:
Create .mcp.json at plugin root:
Benefits:
Add mcpServers field to plugin.json:
Benefits:
Execute local MCP servers as child processes. Best for local tools and custom servers.
Configuration:
Use cases:
Process management:
Connect to hosted MCP servers with OAuth support. Best for cloud services.
Configuration:
Use cases:
Authentication:
Connect to RESTful MCP servers with token authentication.
Configuration:
Use cases:
Connect to WebSocket MCP servers for real-time bidirectional communication.
Configuration:
Use cases:
All MCP configurations support environment variable substitution:
${CLAUDE_PLUGIN_ROOT} - Plugin directory (always use for portability):
User environment variables - From user's shell:
Best practice: Document all required environment variables in plugin README.
When MCP servers provide tools, they're automatically prefixed:
Format: mcp__plugin_<plugin-name>_<server-name>__<tool-name>
Example:
asanaasanacreate_taskmcp__plugin_asana_asana__asana_create_taskPre-allow specific MCP tools in command frontmatter:
Wildcard (use sparingly):
Best practice: Pre-allow specific tools, not wildcards, for security.
Automatic startup:
Lifecycle:
mcp__plugin_...__...Viewing servers:
Use /mcp command to see all servers including plugin-provided ones.
OAuth handled automatically by Claude Code:
User authenticates in browser on first use. No additional configuration needed.
Static or environment variable tokens:
Document required environment variables in README.
Pass configuration to MCP server:
Commands use MCP tools with user interaction:
Use for: Adding validation or preprocessing before MCP calls.
Agents use MCP tools autonomously:
Use for: Multi-step MCP workflows without user interaction.
Integrate multiple MCP servers:
Use for: Workflows spanning multiple services.
Always use secure connections:
DO:
DON'T:
Pre-allow only necessary MCP tools:
Handle MCP server unavailability:
Handle failed MCP operations:
Validate MCP configuration:
MCP servers connect on-demand:
Batch similar requests when possible:
.mcp.json.claude-plugin/)/mcp to verify server appearsclaude --debug logs for connection issues/mcp outputLook for:
Server not connecting:
Tools not available:
/mcp to see available toolsAuthentication failing:
| Type | Transport | Best For | Auth |
|---|---|---|---|
| stdio | Process | Local tools, custom servers | Env vars |
| SSE | HTTP | Hosted services, cloud APIs | OAuth |
| HTTP | REST | API backends, token auth | Tokens |
| ws | WebSocket | Real-time, streaming | Tokens |
DO:
DON'T:
For detailed information, consult:
references/server-types.md - Deep dive on each server typereferences/authentication.md - Authentication patterns and OAuthreferences/tool-usage.md - Using MCP tools in commands and agentsWorking examples in examples/:
stdio-server.json - Local stdio MCP serversse-server.json - Hosted SSE server with OAuthhttp-server.json - REST API with token authclaude --debug and /mcp commandTo add MCP integration to a plugin:
.mcp.json at plugin root with configuration/mcp commandFocus on stdio for custom/local servers, SSE for hosted services with OAuth.
{
"name": "my-plugin",
"version": "1.0.0",
"mcpServers": {
"plugin-api": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
"args": ["--port", "8080"]
}
}
}{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
"env": {
"LOG_LEVEL": "debug"
}
}
}{
"asana": {
"type": "sse",
"url": "https://mcp.asana.com/sse"
}
}{
"api-service": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Custom-Header": "value"
}
}
}{
"realtime-service": {
"type": "ws",
"url": "wss://mcp.example.com/ws",
"headers": {
"Authorization": "Bearer ${TOKEN}"
}
}
}{
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}{
"env": {
"API_KEY": "${MY_API_KEY}",
"DATABASE_URL": "${DB_URL}"
}
}---
allowed-tools: [
"mcp__plugin_asana_asana__asana_create_task",
"mcp__plugin_asana_asana__asana_search_tasks"
]
------
allowed-tools: ["mcp__plugin_asana_asana__*"]
---{
"type": "sse",
"url": "https://mcp.example.com/sse"
}{
"type": "http",
"url": "https://api.example.com",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}{
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": {
"DATABASE_URL": "${DB_URL}",
"API_KEY": "${API_KEY}",
"LOG_LEVEL": "info"
}
}# 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# Agent: data-analyzer.md
Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report{
"github": {
"type": "sse",
"url": "https://mcp.github.com/sse"
},
"jira": {
"type": "sse",
"url": "https://mcp.jira.com/sse"
}
}✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"✅ allowed-tools: [
"mcp__plugin_api_server__read_data",
"mcp__plugin_api_server__create_item"
]
❌ allowed-tools: ["mcp__plugin_api_server__*"]# 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)claude --debug