Guides MCP server integration into Claude Code plugins via .mcp.json or plugin.json, covering stdio, SSE, HTTP for external tools like filesystems and APIs.
From claude-scholarnpx claudepluginhub galaxy-dawn/claude-scholar --plugin claude-scholarThis skill uses the workspace's default tool permissions.
examples/http-server.jsonexamples/sse-server.jsonexamples/stdio-server.jsonreferences/authentication.mdreferences/server-types.mdreferences/tool-usage.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
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.