Claude Code MCP 集成指南：连接外部服务与 API 的完整教程

mcp-integration by anthropics/claude-plugins-official

674 周安装量

14,600 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/anthropics/claude-plugins-official --skill mcp-integration

AI/机器学习开发 API

🇨🇳中文介绍

Claude Code 插件的 MCP 集成

概述

模型上下文协议（MCP）通过提供结构化的工具访问，使 Claude Code 插件能够与外部服务和 API 集成。使用 MCP 集成，可以将外部服务功能作为工具暴露在 Claude Code 内部。

核心功能：

连接到外部服务（数据库、API、文件系统）
从单个服务提供 10 多个相关工具
处理 OAuth 和复杂的身份验证流程
将 MCP 服务器与插件捆绑，实现自动设置

MCP 服务器配置方法

插件可以通过两种方式捆绑 MCP 服务器：

方法 1：专用的 .mcp.json（推荐）

在插件根目录创建 .mcp.json：

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

优点：

关注点分离清晰
更易于维护
更适合多个服务器

方法 2：内联在 plugin.json 中

在 plugin.json 中添加 mcpServers 字段：

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

stdio（本地进程）

将本地 MCP 服务器作为子进程执行。最适合本地工具和自定义服务器。

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

文件系统访问
本地数据库连接
自定义 MCP 服务器
NPM 打包的 MCP 服务器

Claude Code 生成并管理进程
通过 stdin/stdout 通信
当 Claude Code 退出时终止

SSE（服务器发送事件）

连接到支持 OAuth 的托管 MCP 服务器。最适合云服务。

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

官方托管的 MCP 服务器（Asana、GitHub 等）
具有 MCP 端点的云服务
基于 OAuth 的身份验证
无需本地安装

OAuth 流程自动处理
首次使用时提示用户
令牌由 Claude Code 管理

连接到使用令牌身份验证的 RESTful MCP 服务器。

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

基于 REST API 的 MCP 服务器
基于令牌的身份验证
自定义 API 后端
无状态交互

WebSocket（实时）

连接到 WebSocket MCP 服务器，实现实时双向通信。

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

实时数据流
持久连接
服务器推送通知
低延迟要求

所有 MCP 配置都支持环境变量替换：

${CLAUDE_PLUGIN_ROOT} - 插件目录（始终使用以确保可移植性）：

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

用户环境变量 - 来自用户的 shell：

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

最佳实践： 在插件 README 中记录所有必需的环境变量。

当 MCP 服务器提供工具时，它们会自动添加前缀：

格式： mcp__plugin_<插件名称>_<服务器名称>__<工具名称>

插件：asana
服务器：asana
工具：create_task
完整名称： mcp__plugin_asana_asana__asana_create_task

在命令中使用 MCP 工具

在命令前置元数据中预先允许特定的 MCP 工具：

---
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

通配符（谨慎使用）：

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

最佳实践： 出于安全考虑，预先允许特定工具，而不是使用通配符。

MCP 服务器在插件启用时启动
在首次使用工具之前建立连接
配置更改需要重启

插件加载
解析 MCP 配置
启动服务器进程（stdio）或建立连接（SSE/HTTP/WS）
发现并注册工具
工具以 mcp__plugin_...__... 形式可用

查看服务器： 使用 /mcp 命令查看所有服务器，包括插件提供的服务器。

OAuth 由 Claude Code 自动处理：

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

用户首次使用时在浏览器中进行身份验证。无需额外配置。

基于令牌（Headers）

静态或环境变量令牌：

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

在 README 中记录所需的环境变量。

环境变量（stdio）

将配置传递给 MCP 服务器：

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

模式 1：简单工具包装器

命令使用 MCP 工具并与用户交互：

# 命令：create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

步骤：
1. 从用户处收集项目详情
2. 使用 mcp__plugin_name_server__create_item
3. 确认创建

适用于： 在调用 MCP 之前添加验证或预处理。

模式 2：自主代理

代理自主使用 MCP 工具：

# 代理：data-analyzer.md

分析过程：
1. 通过 mcp__plugin_db_server__query 查询数据
2. 处理并分析结果
3. 生成洞察报告

适用于： 无需用户交互的多步骤 MCP 工作流。

模式 3：多服务器插件

集成多个 MCP 服务器：

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

适用于： 跨越多个服务的工作流。

始终使用安全连接：

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

✅ 使用环境变量存储令牌
✅ 在 README 中记录所需的环境变量
✅ 让 OAuth 流程处理身份验证

❌ 在配置中硬编码令牌
❌ 将令牌提交到 git
❌ 在文档中共享令牌

仅预先允许必要的 MCP 工具：

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

处理 MCP 服务器不可用的情况：

在命令中提供回退行为
通知用户连接问题
检查服务器 URL 和配置

处理失败的 MCP 操作：

在调用 MCP 工具之前验证输入
提供清晰的错误消息
检查速率限制和配额

验证 MCP 配置：

在开发期间测试服务器连接性
验证 JSON 语法
检查必需的环境变量

MCP 服务器按需连接：

并非所有服务器在启动时都连接
首次使用工具触发连接
连接池自动管理

尽可能批量处理类似请求：

# 良好：使用过滤器的单个查询
tasks = search_tasks(project="X", assignee="me", limit=50)

# 避免：许多单独的查询
for id in task_ids:
    task = get_task(id)

在 .mcp.json 中配置 MCP 服务器
本地安装插件（.claude-plugin/）
运行 /mcp 以验证服务器出现
在命令中测试工具调用
检查 claude --debug 日志中的连接问题

MCP 配置是有效的 JSON
服务器 URL 正确且可访问
记录了必需的环境变量
工具出现在 /mcp 输出中
身份验证有效（OAuth 或令牌）
从命令中成功调用工具
优雅地处理错误情况

MCP 服务器连接尝试
工具发现日志
身份验证流程
工具调用错误

服务器未连接：

检查 URL 是否正确
验证服务器是否正在运行（stdio）
检查网络连接性
查看身份验证配置

工具不可用：

验证服务器是否成功连接
检查工具名称是否完全匹配
运行 /mcp 查看可用工具
配置更改后重启 Claude Code

身份验证失败：

清除缓存的认证令牌
重新进行身份验证
检查令牌范围和权限
验证环境变量是否已设置

类型	传输方式	最适合	身份验证
stdio	进程	本地工具，自定义服务器	环境变量
SSE	HTTP	托管服务，云 API	OAuth
HTTP	REST	API 后端，令牌认证	令牌
ws	WebSocket	实时，流式传输	令牌

指定了服务器类型（stdio/SSE/HTTP/ws）
特定类型的字段完整（command 或 url）
配置了身份验证
记录了环境变量
使用了 HTTPS/WSS（而不是 HTTP/WS）
路径使用了 ${CLAUDE_PLUGIN_ROOT}

✅ 使用 ${CLAUDE_PLUGIN_ROOT} 确保路径可移植
✅ 记录必需的环境变量
✅ 使用安全连接（HTTPS/WSS）
✅ 在命令中预先允许特定的 MCP 工具
✅ 发布前测试 MCP 集成
✅ 优雅地处理连接和工具错误

❌ 硬编码绝对路径
❌ 将凭据提交到 git
❌ 使用 HTTP 而不是 HTTPS
❌ 使用通配符预先允许所有工具
❌ 跳过错误处理
❌ 忘记记录设置步骤

有关详细信息，请查阅：

references/server-types.md - 每种服务器类型的深入探讨
references/authentication.md - 身份验证模式和 OAuth
references/tool-usage.md - 在命令和代理中使用 MCP 工具

examples/ 中的工作示例：

stdio-server.json - 本地 stdio MCP 服务器
sse-server.json - 带有 OAuth 的托管 SSE 服务器
http-server.json - 带有令牌认证的 REST API

官方 MCP 文档：https://modelcontextprotocol.io/
Claude Code MCP 文档：https://docs.claude.com/en/docs/claude-code/mcp
MCP SDK：@modelcontextprotocol/sdk
测试：使用 claude --debug 和 /mcp 命令

为插件添加 MCP 集成：

选择 MCP 服务器类型（stdio、SSE、HTTP、ws）
在插件根目录创建带有配置的 .mcp.json
所有文件引用都使用 ${CLAUDE_PLUGIN_ROOT}
在 README 中记录必需的环境变量
使用 /mcp 命令在本地测试
在相关命令中预先允许 MCP 工具
处理身份验证（OAuth 或令牌）
测试错误情况（连接失败、身份验证错误）
在插件 README 中记录 MCP 集成

对于自定义/本地服务器，重点关注 stdio；对于带有 OAuth 的托管服务，重点关注 SSE。

🇺🇸English

MCP Integration for Claude Code Plugins

Overview

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:

Connect to external services (databases, APIs, file systems)
Provide 10+ related tools from a single service
Handle OAuth and complex authentication flows
Bundle MCP servers with plugins for automatic setup

MCP Server Configuration Methods

Plugins can bundle MCP servers in two ways:

Method 1: Dedicated .mcp.json (Recommended)

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:

Clear separation of concerns
Easier to maintain
Better for multiple servers

Method 2: Inline in plugin.json

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:

Single configuration file
Good for simple single-server plugins

MCP Server Types

stdio (Local Process)

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:

File system access
Local database connections
Custom MCP servers
NPM-packaged MCP servers

Process management:

Claude Code spawns and manages the process
Communicates via stdin/stdout
Terminates when Claude Code exits

SSE (Server-Sent Events)

Connect to hosted MCP servers with OAuth support. Best for cloud services.

Configuration:

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

Use cases:

Official hosted MCP servers (Asana, GitHub, etc.)
Cloud services with MCP endpoints
OAuth-based authentication
No local installation needed

Authentication:

OAuth flows handled automatically
User prompted on first use
Tokens managed by Claude Code

HTTP (REST API)

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:

REST API-based MCP servers
Token-based authentication
Custom API backends
Stateless interactions

WebSocket (Real-time)

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:

Real-time data streaming
Persistent connections
Push notifications from server
Low-latency requirements

Environment Variable Expansion

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.

MCP Tool Naming

When MCP servers provide tools, they're automatically prefixed:

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

Example:

Plugin: asana
Server: asana
Tool: create_task
Full name: mcp__plugin_asana_asana__asana_create_task

Using MCP Tools in Commands

Pre-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.

Lifecycle Management

Automatic startup:

MCP servers start when plugin enables
Connection established before first tool use
Restart required for configuration changes

Lifecycle:

Plugin loads
MCP configuration parsed
Server process started (stdio) or connection established (SSE/HTTP/WS)
Tools discovered and registered
Tools available as mcp__plugin_...__...

Viewing servers: Use /mcp command to see all servers including plugin-provided ones.

Authentication Patterns

OAuth (SSE/HTTP)

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.

Token-Based (Headers)

Static or environment variable tokens:

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Document required environment variables in README.

Environment Variables (stdio)

Pass configuration to MCP server:

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

Integration Patterns

Pattern 1: Simple Tool Wrapper

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 creation

Use for: Adding validation or preprocessing before MCP calls.

Pattern 2: Autonomous Agent

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 report

Use for: Multi-step MCP workflows without user interaction.

Pattern 3: Multi-Server Plugin

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.

Security Best Practices

Use HTTPS/WSS

Always use secure connections:

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

Token Management

DO:

✅ Use environment variables for tokens
✅ Document required env vars in README
✅ Let OAuth flow handle authentication

DON'T:

❌ Hardcode tokens in configuration
❌ Commit tokens to git
❌ Share tokens in documentation

Permission Scoping

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__*"]

Error Handling

Connection Failures

Handle MCP server unavailability:

Provide fallback behavior in commands
Inform user of connection issues
Check server URL and configuration

Tool Call Errors

Handle failed MCP operations:

Validate inputs before calling MCP tools
Provide clear error messages
Check rate limiting and quotas

Configuration Errors

Validate MCP configuration:

Test server connectivity during development
Validate JSON syntax
Check required environment variables

Performance Considerations

Lazy Loading

MCP servers connect on-demand:

Not all servers connect at startup
First tool use triggers connection
Connection pooling managed automatically

Batching

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)

Testing MCP Integration

Local Testing

Configure MCP server in .mcp.json
Install plugin locally (.claude-plugin/)
Run /mcp to verify server appears
Test tool calls in commands
Check claude --debug logs for connection issues

Validation Checklist

MCP configuration is valid JSON
Server URL is correct and accessible
Required environment variables documented
Tools appear in /mcp output
Authentication works (OAuth or tokens)
Tool calls succeed from commands
Error cases handled gracefully

Debugging

Enable Debug Logging

claude --debug

Look for:

MCP server connection attempts
Tool discovery logs
Authentication flows
Tool call errors

Common Issues

Server not connecting:

Check URL is correct
Verify server is running (stdio)
Check network connectivity
Review authentication configuration

Tools not available:

Verify server connected successfully
Check tool names match exactly
Run /mcp to see available tools
Restart Claude Code after config changes

Authentication failing:

Clear cached auth tokens
Re-authenticate
Check token scopes and permissions
Verify environment variables set

Quick Reference

MCP Server Types

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

Configuration Checklist

Server type specified (stdio/SSE/HTTP/ws)
Type-specific fields complete (command or url)
Authentication configured
Environment variables documented
HTTPS/WSS used (not HTTP/WS)
${CLAUDE_PLUGIN_ROOT} used for paths

Best Practices

DO:

✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths
✅ Document required environment variables
✅ Use secure connections (HTTPS/WSS)
✅ Pre-allow specific MCP tools in commands
✅ Test MCP integration before publishing
✅ Handle connection and tool errors gracefully

DON'T:

❌ Hardcode absolute paths
❌ Commit credentials to git
❌ Use HTTP instead of HTTPS
❌ Pre-allow all tools with wildcards
❌ Skip error handling
❌ Forget to document setup

Additional Resources

Reference Files

For detailed information, consult:

references/server-types.md - Deep dive on each server type
references/authentication.md - Authentication patterns and OAuth
references/tool-usage.md - Using MCP tools in commands and agents

Example Configurations

Working examples in examples/:

stdio-server.json - Local stdio MCP server
sse-server.json - Hosted SSE server with OAuth
http-server.json - REST API with token auth

External Resources

Official MCP Docs : https://modelcontextprotocol.io/
Claude Code MCP Docs : https://docs.claude.com/en/docs/claude-code/mcp
MCP SDK : @modelcontextprotocol/sdk
Testing : Use claude --debug and /mcp command

Implementation Workflow

To add MCP integration to a plugin:

Choose MCP server type (stdio, SSE, HTTP, ws)
Create .mcp.json at plugin root with configuration
Use ${CLAUDE_PLUGIN_ROOT} for all file references
Document required environment variables in README
Test locally with /mcp command
Pre-allow MCP tools in relevant commands
Handle authentication (OAuth or tokens)
Test error cases (connection failures, auth errors)
Document MCP integration in plugin README

Focus on stdio for custom/local servers, SSE for hosted services with OAuth.

Weekly Installs

326

Repository

anthropics/clau…official

GitHub Stars

9.6K

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode281

codex280

gemini-cli278

github-copilot270

amp262

claude-code257

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装

Claude Code MCP 集成指南：连接外部服务与 API 的完整教程

🇨🇳中文介绍

Claude Code 插件的 MCP 集成

概述

MCP 服务器配置方法

方法 1：专用的 .mcp.json（推荐）

方法 2：内联在 plugin.json 中

相关 Skills

MCP 服务器类型

stdio（本地进程）

SSE（服务器发送事件）

HTTP（REST API）

WebSocket（实时）

环境变量扩展

MCP 工具命名

在命令中使用 MCP 工具

生命周期管理

身份验证模式

OAuth（SSE/HTTP）

基于令牌（Headers）

环境变量（stdio）

集成模式

模式 1：简单工具包装器

模式 2：自主代理

模式 3：多服务器插件

安全最佳实践

使用 HTTPS/WSS

令牌管理

权限范围

错误处理

连接失败

工具调用错误

配置错误

性能考虑

延迟加载

批处理

测试 MCP 集成

本地测试

验证清单

调试

启用调试日志

常见问题

快速参考

MCP 服务器类型

配置清单

最佳实践

其他资源

参考文件

配置示例

外部资源

实施工作流程

🇺🇸English

MCP Integration for Claude Code Plugins

Overview

MCP Server Configuration Methods

Method 1: Dedicated .mcp.json (Recommended)

Method 2: Inline in plugin.json

MCP Server Types

stdio (Local Process)

SSE (Server-Sent Events)

HTTP (REST API)

WebSocket (Real-time)

Environment Variable Expansion

MCP Tool Naming

Using MCP Tools in Commands

Lifecycle Management

Authentication Patterns

OAuth (SSE/HTTP)

Token-Based (Headers)

Environment Variables (stdio)

Integration Patterns

Pattern 1: Simple Tool Wrapper

Pattern 2: Autonomous Agent

Pattern 3: Multi-Server Plugin

Security Best Practices

Use HTTPS/WSS

Token Management

Permission Scoping

Error Handling

Connection Failures