mcp-integration

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

优点：

• 单个配置文件
• 适用于简单的单服务插件

MCP 服务类型

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 管理令牌

HTTP（REST API）

连接使用令牌身份验证的 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 服务提供工具时，系统会自动添加前缀：

格式： mcp__plugin_<plugin-name>_<server-name>__<tool-name>

示例：

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

在命令中使用 MCP 工具

在命令 frontmatter 中预先允许特定的 MCP 工具：

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

通配符（谨慎使用）：

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

最佳实践： 为确保安全，应预先允许特定工具，而非使用通配符。

生命周期管理

自动启动：

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

生命周期：

1. 加载插件
2. 解析 MCP 配置
3. 启动服务进程（stdio）或建立连接（SSE/HTTP/WS）
4. 发现并注册工具
5. 工具可通过 mcp__plugin_...__... 使用

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

身份验证模式

OAuth（SSE/HTTP）

OAuth 由 Claude Code 自动处理：

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

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

基于令牌（标头）

静态令牌或环境变量令牌：

{
  "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 工具：

# 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

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

模式 2：自主 Agent

Agent 自主使用 MCP 工具：

# Agent: data-analyzer.md

Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report

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

模式 3：多服务插件

集成多个 MCP 服务：

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

适用场景： 跨多个服务的工作流。

安全最佳实践

使用 HTTPS/WSS

始终使用安全连接：

✅ "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 服务按需连接：

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

批处理

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

# 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)

测试 MCP 集成

本地测试

1. 在 .mcp.json 中配置 MCP 服务
2. 在本地安装插件（.claude-plugin/）
3. 运行 /mcp，确认服务已显示
4. 在命令中测试工具调用
5. 检查 claude --debug 日志中的连接问题

验证清单

• MCP 配置是有效的 JSON
• 服务 URL 正确且可访问
• 已记录所需的环境变量
• 工具显示在 /mcp 输出中
• 身份验证正常（OAuth 或令牌）
• 命令中的工具调用成功
• 能妥善处理错误情况

调试

启用调试日志

claude --debug

请留意：

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

常见问题

服务无法连接：

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

工具不可用：

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

身份验证失败：

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

快速参考

MCP 服务类型

类型	传输方式	适用场景	身份验证
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 - 在命令和 Agent 中使用 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 集成：

1. 选择 MCP 服务类型（stdio、SSE、HTTP、ws）
2. 在插件根目录创建 .mcp.json 并添加配置
3. 所有文件引用均使用 ${CLAUDE_PLUGIN_ROOT}
4. 在 README 中记录必需的环境变量
5. 使用 /mcp 命令进行本地测试
6. 在相关命令中预先允许 MCP 工具
7. 处理身份验证（OAuth 或令牌）
8. 测试错误场景（连接失败、身份验证错误）
9. 在插件 README 中记录 MCP 集成

自定义或本地服务优先使用 stdio；使用 OAuth 的托管服务优先使用 SSE。