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

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, 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 file in the plugin root, or reads the mcpServers field from the plugin’s plugin.json manifest located at .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_<plugin-name>_<server-name>__<tool-name>

This naming convention, documented in 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 <tool> 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 file in your plugin root to declare stdio servers. This file maps server names to execution details:

{
  "filesystem": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/servers/filesystem-server.js"],
    "env": {
      "LOG_LEVEL": "info"
    }
  }
}

File: 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, the mcpServers field points to the JSON file:

{
  "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, 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_<plugin-name>_<server-name>__<tool-name>. 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:

---
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}}

<tool name="mcp__plugin_example-plugin_filesystem__read_file" args="{{file_path}}"/>

The allowed-tools array grants permission for specific tool instances, while the <tool> 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:

{
  "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. This example from plugins/plugin-dev/skills/mcp-integration/examples/http-server.json connects to a GitHub MCP endpoint:

{
  "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 or the mcpServers field of 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_<plugin>_<server>__<tool>.
• Invocation requires pre‑authorization via allowed-tools front‑matter and uses the standard <tool> 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 file in the plugin root, or the mcpServers field within the plugin’s 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_<plugin-name>_<server-name>__<tool-name>. 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, 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.

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