Setting the chapter. One moment.
Also bundled
HTTP Server10 chapters · 49 min
Plugin Dev
Chapter 7 of 10
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…
5 minutes · 1,112 words · 48 sections
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:
Install this repository
npx skills add anthropics/claude-code/plugin marketplace add anthropics/claude-codeSkills install per repository, not per chapter — the CLI has no documented per-skill form, so we do not print one.
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 verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
main, last pushed 8 August 2026.SKILL.md, not by matching a directory convention. 4 distinct layouts observed: plugins/claude-opus-4-5-migration/skills/*/SKILL.md, plugins/frontend-design/skills/*/SKILL.md, plugins/hookify/skills/*/SKILL.md, plugins/plugin-dev/skills/*/SKILL.md.h1 and no skipped levels: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 creationUse 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 reportUse 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 --debugLook 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.
.claude-plugin/marketplace.json by Anthropic, declaring 13 plugins. It is read for editorial metadata only — never as the skill index, which is always the repository tree./anthropics/claude-code.md, and each chapter at its own .md URL.6 files · 33 KB
Everything this skill ships beside its prose. All of it is set here, as subchapters of chapter 7.
Documentation the agent loads on demand, rather than up front.
Everything else published alongside the skill.