How to Integrate MCP Servers with Claude Code Plugins: A Complete Guide

Claude Code plugins expose external services as native Claude tools by configuring Model Context Protocol (MCP) servers that communicate via stdio, SSE, HTTP, or WebSocket transports.

Claude Code, the AI coding assistant from Anthropic, extends its capabilities through a plugin system that supports the Model Context Protocol (MCP). According to the anthropics/claude-code source code in plugins/plugin-dev/skills/mcp-integration/SKILL.md, developers can integrate databases, APIs, and file systems as first-class tools by configuring MCP servers in their plugin manifests.

MCP Configuration Methods

Claude Code supports two primary methods for defining MCP server connections. Both approaches parse JSON configurations during plugin load to establish connections and discover available tools.

Using a Dedicated .mcp.json File (Recommended)

The preferred approach uses a separate .mcp.json file in the plugin root. As specified in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L23-L58, this file defines server connections independently of the main plugin manifest.

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR}"],
    "env": {
      "LOG_LEVEL": "info"
    }
  }
}

This example from plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json demonstrates a stdio server that launches a local filesystem MCP server using npx.

Inline Configuration in plugin.json

Alternatively, define servers directly within plugin.json under the mcpServers field. This approach works well for simple plugins with minimal configuration.

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

Supported MCP Server Transport Types

Claude Code supports four transport mechanisms, each suited to different deployment scenarios as documented in plugins/plugin-dev/skills/mcp-integration/SKILL.md.

stdio (Local Process)

The stdio transport launches a local subprocess and communicates via stdin/stdout. Ideal for local tools and development servers, this mode requires no network configuration.

According to plugins/plugin-dev/skills/mcp-integration/SKILL.md#L65-L82, Claude Code manages the process lifecycle, automatically restarting the server if it crashes. Environment variables like ${CLAUDE_PROJECT_DIR} resolve at runtime to provide context-aware paths.

SSE (Server-Sent Events)

For hosted services, SSE connects to remote servers using Server-Sent Events. As noted in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L95-L107, Claude Code handles OAuth authentication flows automatically, opening a browser window when users first invoke a tool.

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

HTTP (REST Endpoints)

The HTTP transport communicates with REST endpoints using token-based authentication. Configuration in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L119-L136 shows support for custom headers and environment variable substitution.

{
  "github": {
    "type": "http",
    "url": "https://api.github.com/mcp",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  }
}

WebSocket (Bi-directional Streaming)

For low-latency use cases requiring real-time communication, WebSocket provides bi-directional streaming capabilities. Referenced in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L144-L158, this transport maintains persistent connections suitable for interactive tools.

Tool Discovery and Naming Conventions

When a plugin loads, Claude Code follows a strict lifecycle: parse MCP configuration, establish connections, discover available tools, and register them with prefixed names. As implemented in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L124-L136, tools become available immediately after discovery.

Discovered tools receive automatically generated names following the pattern:

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

This prefixing scheme, detailed in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L90-L101, prevents naming collisions between plugins and built-in Claude Code tools. For example, a tool named create_resource from the api server in my-plugin becomes mcp__plugin_my-plugin_api__create_resource.

Authentication and Security

Claude Code implements distinct authentication flows depending on transport type, with security requirements specified in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L242-L268.

OAuth Flow for Hosted Servers

SSE and HTTP servers requiring OAuth trigger an automatic browser flow. As described in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L141-L158, Claude Code manages token storage and refresh, requesting user consent only on first use.

Token-Based Authentication

For API keys and static tokens, inject values via environment variables using ${VARIABLE_NAME} syntax. Reference plugins/plugin-dev/skills/mcp-integration/SKILL.md#L156-L166 for implementation patterns that avoid hardcoding credentials.

Security Best Practices

Production deployments require HTTPS/WSS encryption, environment variable isolation for secrets, and explicit tool allowlisting. Never use wildcard patterns in allowed-tools declarations; specify exact tool names such as mcp__plugin_my-plugin_api__create_resource to minimize attack surface.

Using MCP Tools in Commands and Agents

Reference MCP tools in command definitions using the prefixed name in the frontmatter allowed-tools array.

---
allowed-tools: [
  "mcp__plugin_my-plugin_api__create_resource"
]
---

# Command: create-resource.md

1. Ask the user for resource details  
2. Call `mcp__plugin_my-plugin_api__create_resource` with the collected data  
3. Return the created resource ID

For autonomous agents, chain multiple MCP tool calls with internal processing steps:

# Agent: data-insight.md

1. `mcp__plugin_db_server_query__run_query` → fetch raw data  
2. Process the data in Python or JavaScript inside the agent  
3. Summarize findings and present them to the user

Summary

• Configuration: Define MCP servers in .mcp.json (recommended) or inline in plugin.json under mcpServers
• Transports: Choose stdio for local processes, SSE for hosted OAuth services, HTTP for REST APIs, or WebSocket for real-time streaming
• Naming: Tools auto-prefix as mcp__plugin_<plugin-name>_<server-name>__<tool-name> to prevent collisions
• Security: Store tokens in environment variables, enforce HTTPS/WSS, and explicitly allowlist specific tools in command frontmatter
• Lifecycle: Claude Code manages server startup, connection handling, and tool discovery automatically during plugin initialization

Frequently Asked Questions

What file formats does Claude Code support for MCP configuration?

Claude Code supports two configuration methods as documented in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L23-L58: a dedicated .mcp.json file in the plugin root directory, or an inline mcpServers object within the main plugin.json manifest. The separate file approach is recommended for complex configurations with multiple servers.

How does Claude Code handle authentication for remote MCP servers?

Claude Code implements transport-specific authentication handlers. For SSE servers, it manages OAuth flows automatically by opening browser windows and caching tokens. For HTTP servers, it supports Bearer tokens via environment variables like ${GITHUB_TOKEN}. Local stdio servers inherit the plugin's environment and can access variables such as ${CLAUDE_PROJECT_DIR}.

Can I use multiple MCP servers in a single plugin?

Yes. Both .mcp.json and inline configurations support multiple server definitions. You can mix transport types—for example, combining a local stdio file server with a hosted SSE project management API. Each server's tools receive distinct prefixed names based on the server key defined in the configuration.

What is the naming convention for MCP tools in Claude Code?

Claude Code automatically prefixes discovered tools to ensure uniqueness. The format is mcp__plugin_<plugin-name>_<server-name>__<tool-name>, as implemented in plugins/plugin-dev/skills/mcp-integration/SKILL.md#L90-L101. A plugin named devtools with a server named github exposing a tool named list_repos becomes callable as mcp__plugin_devtools_github__list_repos in commands and agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}