# How MCP Servers Integrate with Claude Code Plugins: A Complete Integration Guide > Learn how MCP servers integrate with Claude Code plugins. This guide details registering MCP servers to expose JSON tools for Claude Code to discover and invoke. - Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official) - Tags: how-to-guide - Published: 2026-03-13 --- **Claude Code plugins extend the LLM’s native tool set by registering Model Context Protocol (MCP) servers, which expose JSON‑based tools that Claude Code discovers, registers under deterministic names, and invokes like built‑in functions.** The **anthropics/claude-plugins-official** repository demonstrates how MCP servers bridge external services with Claude Code’s tool ecosystem. When you configure MCP servers in your plugin, Claude Code automatically manages the server lifecycle, negotiates capabilities, and makes those tools available to commands, agents, and skills without requiring additional code. ## What Is the Model Context Protocol (MCP)? The **Model Context Protocol (MCP)** is a standardized JSON‑based protocol that allows Claude Code to communicate with lightweight external services. An MCP server is a tiny service—running locally via `stdio` or remotely via `http`, `sse`, or `ws`—that exposes a schema‑defined set of tools. According to [`plugins/plugin-dev/skills/mcp-integration/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md), these servers act as extension points that let plugins add capabilities like filesystem access, API integrations, or custom business logic without modifying Claude Code’s core. ## The 6-Step MCP Integration Pipeline Claude Code follows a deterministic pipeline to integrate MCP servers, as implemented in the core plugin loader and tool registry: ### 1. Configuration Loading Claude Code first locates MCP server definitions. It searches for a top‑level [`.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.mcp.json) file in the plugin root, or reads the `mcpServers` field from the plugin’s [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/plugin.json). ### 2. Server Startup The core plugin loader spawns or connects to the server based on its type: - **stdio**: Spawns a child process with the specified command and arguments - **http/sse/ws**: Opens the network connection to the provided URL ### 3. Protocol Handshake Claude Code negotiates the MCP handshake over the established transport (stdin/stdout for `stdio`, or the network socket for others). The server returns a JSON schema describing each available tool, including parameter types and descriptions. ### 4. Tool Registration The core tool registry ingests the schema and registers each tool under a deterministic, collision‑resistant name: ``` mcp__plugin____ ``` This naming convention, documented in [`plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md), ensures that tools from different plugins remain isolated while remaining callable from any permitted context. ### 5. Tool Invocation Commands, agents, and skills invoke MCP tools using the standard `` tag syntax. Claude Code serializes arguments according to the server’s JSON schema, transmits the request via the active transport, and returns the JSON result to the calling component. ### 6. Lifecycle Management The plugin manager monitors server health and automatically stops servers when the plugin is disabled or Claude Code exits, preventing resource leaks. ## Configuring MCP Servers in Your Plugin ### Using .mcp.json Create a [`.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.mcp.json) file in your plugin root to declare stdio servers. This file maps server names to execution details: ```json { "filesystem": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/servers/filesystem-server.js"], "env": { "LOG_LEVEL": "info" } } } ``` *File:* [`plugins/example-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/example-plugin/.mcp.json) illustrates this pattern for a Node.js‑based filesystem server. ### Using plugin.json Alternatively, reference the configuration from your manifest. In [`plugins/example-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/example-plugin/.claude-plugin/plugin.json), the `mcpServers` field points to the JSON file: ```json { "name": "example-plugin", "version": "0.1.0", "mcpServers": "./.mcp.json" } ``` ### Supported Server Types As detailed in [`plugins/plugin-dev/skills/mcp-integration/references/server-types.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md), Claude Code supports four transport types: - **stdio**: Local subprocess communication via stdin/stdout - **sse**: Server‑Sent Events for unidirectional streaming - **http**: Standard HTTP POST requests for stateless tools - **ws**: WebSocket for bidirectional, persistent connections ## Invoking MCP Tools from Commands and Agents ### Tool Naming Convention Every registered MCP tool follows the strict format `mcp__plugin____`. For example, a tool named `read_file` from a server named `filesystem` in a plugin named `example-plugin` becomes: ``` mcp__plugin_example-plugin_filesystem__read_file ``` ### Pre-allowing Tools with allowed-tools For security, Claude Code requires explicit permission before invoking MCP tools. In any Markdown command or agent file, include the `allowed-tools` front‑matter: ```markdown --- name: read-file description: Read a file from the workspace using the filesystem MCP server allowed-tools: - "mcp__plugin_example-plugin_filesystem__read_file" --- Enter the path of the file you want to read (relative to the workspace): {{user_input:file_path}} ``` The `allowed-tools` array grants permission for specific tool instances, while the `` tag executes the call with the provided arguments. ### The Tool Schema During the handshake, the server transmits a JSON schema for each tool. A typical schema for a `read_file` tool looks like: ```json { "name": "read_file", "description": "Read a text file and return its contents", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Workspace‑relative path to the file" } }, "required": ["path"] } } ``` Claude Code validates invocations against this schema before transmitting requests to the server. ## HTTP-Based MCP Servers For remote APIs, configure an HTTP‑based server in [`.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.mcp.json). This example from [`plugins/plugin-dev/skills/mcp-integration/examples/http-server.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/examples/http-server.json) connects to a GitHub MCP endpoint: ```json { "github": { "type": "http", "url": "https://mcp.github.com/api", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } } } ``` HTTP servers follow the same registration and invocation patterns as stdio servers, but communicate over the network rather than local subprocess pipes. ## Summary - **MCP servers** extend Claude Code via a standardized JSON protocol, exposing tools through `stdio`, `http`, `sse`, or `ws` transports. - Configuration resides in [`.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.mcp.json) or the `mcpServers` field of [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json), located in the plugin root or `.claude-plugin/` directory. - Claude Code automatically handles server startup, handshake negotiation, and tool registration under the deterministic pattern `mcp__plugin____`. - Invocation requires pre‑authorization via `allowed-tools` front‑matter and uses the standard `` tag syntax in Markdown components. - The plugin manager controls server lifecycle, ensuring processes terminate cleanly when plugins unload. ## Frequently Asked Questions ### What file formats does Claude Code use to configure MCP servers? Claude Code recognizes two configuration sources: a standalone [`.mcp.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.mcp.json) file in the plugin root, or the `mcpServers` field within the plugin’s [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest. Both use the same JSON schema to define server types, commands, arguments, environment variables, and URLs. ### How does Claude Code prevent naming collisions between MCP tools from different plugins? The tool registry enforces a strict naming convention: `mcp__plugin____`. This prefixes every tool with the plugin and server identifiers, ensuring unique identifiers even when multiple plugins expose tools with identical base names. ### Do I need to write code to register MCP tools with Claude Code? No. The integration is completely declarative. You only need to provide the JSON configuration and optionally list tool names in the `allowed-tools` front‑matter of your Markdown commands. Claude Code handles server startup, handshake negotiation, schema discovery, and registration automatically. ### Which transport protocols are supported for MCP servers? According to [`plugins/plugin-dev/skills/mcp-integration/references/server-types.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md), Claude Code supports four transports: `stdio` for local subprocesses, `http` for REST endpoints, `sse` for Server‑Sent Events, and `ws` for WebSocket connections. Each type requires corresponding configuration fields such as `command` and `args` for stdio, or `url` and `headers` for HTTP.