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

> Easily integrate MCP servers with Claude Code plugins. This guide details how to expose external services as native Claude tools using various transport methods.

- Repository: [Anthropic/claude-code](https://github.com/anthropics/claude-code)
- Tags: how-to-guide
- Published: 2026-04-02

---

**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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/.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.

```json
{
  "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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/plugin.json) under the `mcpServers` field. This approach works well for simple plugins with minimal configuration.

```json
{
  "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`](https://github.com/anthropics/claude-code/blob/main/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.

```json
{
  "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.

```json
{
  "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.

```markdown
---
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:

```markdown

# 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`](https://github.com/anthropics/claude-code/blob/main/.mcp.json) (recommended) or inline in [`plugin.json`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/.mcp.json) file in the plugin root directory, or an inline `mcpServers` object within the main [`plugin.json`](https://github.com/anthropics/claude-code/blob/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`](https://github.com/anthropics/claude-code/blob/main/.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.