Stats
Actions
Tags
From plugin-dev
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
How this skill is triggered — by the user, by Claude, or both
Slash command
/plugin-dev:skills/mcp-integrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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:
{
"database-tools": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"DB_URL": "${DB_URL}"
}
}
}
Benefits:
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:
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:
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:
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:
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:
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.
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:
---
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.
Automatic startup:
Lifecycle:
mcp__plugin_...__...Viewing servers:
Use /mcp command to see all servers including plugin-provided ones.
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.
Static or environment variable tokens:
{
"type": "http",
"url": "https://api.example.com",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
Document required environment variables in README.
Pass configuration to MCP server:
{
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": {
"DATABASE_URL": "${DB_URL}",
"API_KEY": "${API_KEY}",
"LOG_LEVEL": "info"
}
}
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.
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.
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.
Always use secure connections:
✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"
DO:
DON'T:
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__*"]
Handle MCP server unavailability:
Handle failed MCP operations:
Validate MCP configuration:
MCP servers connect on-demand:
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)
.mcp.json.claude-plugin/)/mcp to verify server appearsclaude --debug logs for connection issues/mcp outputclaude --debug
Look 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.
npx claudepluginhub iButters/ClaudeCodePlugins --plugin plugin-devGuides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
Guides integration of Model Context Protocol (MCP) servers into Claude Code plugins via .mcp.json or plugin.json. Covers stdio, SSE, and HTTP server types.
Configures MCP servers in Claude Code plugins via .mcp.json or plugin.json, supports stdio/SSE/HTTP/WebSocket, env vars, tool naming, OAuth/token auth, security, and testing.