SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mcp integration

mcp integration

智能体与模型

查看项目

更新于 10-16 20:43

技能介绍

MCP Integration 用于在 Claude Code 插件中集成模型上下文协议（Model Context Protocol，MCP），使插件能够通过结构化工具访问外部服务与 API，把外部服务能力暴露为 Claude Code 内的工具。

主要能力

  • 连接外部服务，如数据库、API、文件系统。
  • 从单一服务提供 10 个以上相关工具。
  • 处理 OAuth 与复杂认证流程。
  • 将 MCP 服务器与插件打包，实现自动安装配置。

MCP 服务器配置方式

方式一：专用 .mcp.json（推荐）。在插件根目录创建 .mcp.json，配置示例包含 command、args 与 env 字段，命令与参数路径使用 ${CLAUDE_PLUGIN_ROOT}。优点是关注点清晰、易维护，适合多个服务器。

方式二：在 plugin.json 内联。在 plugin.json 中添加 mcpServers 字段，适合简单的单服务器插件，只需一个配置文件。

MCP 服务器类型

  • stdio（本地进程）：以子进程方式执行本地 MCP 服务器，适合本地工具与自定义服务器，如文件系统访问、本地数据库连接、NPM 打包的 MCP 服务器。Claude Code 负责启动和管理进程，通过 stdin/stdout 通信，退出时终止进程。
  • SSE（Server-Sent Events）：连接支持 OAuth 的托管 MCP 服务器，适合云服务与官方托管服务器（如 Asana、GitHub 等）。OAuth 流程自动处理，首次使用时提示用户在浏览器认证，令牌由 Claude Code 管理，无需本地安装。
  • HTTP（REST API）：连接基于 REST 的 MCP 服务器，使用令牌认证，适合 REST API 后端、自定义 API 与无状态交互。
  • WebSocket（实时）：连接 WebSocket MCP 服务器进行实时双向通信，适合实时数据流、持久连接、服务端推送通知和低延迟需求。

环境变量替换

所有 MCP 配置支持环境变量替换：${CLAUDE_PLUGIN_ROOT} 表示插件目录（应始终用于路径以保证可移植性），也可引用用户 shell 中的环境变量，如 API_KEY、DATABASE_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 工具，也可使用通配符，但建议谨慎使用。出于安全考虑，最佳实践是预授权具体工具而非通配符。

生命周期管理

MCP 服务器在插件启用时启动，首次使用工具前建立连接，配置变更后需重启。生命周期为：插件加载 → 解析 MCP 配置 → 启动服务器进程（stdio）或建立连接（SSE/HTTP/WS）→ 发现并注册工具 → 工具以 mcp__plugin_...__... 形式可用。使用 /mcp 命令可查看所有服务器，包括插件提供的服务器。

认证模式

  • OAuth（SSE/HTTP）：由 Claude Code 自动处理，用户首次使用时在浏览器认证，无需额外配置。
  • 令牌（Headers）：使用静态或环境变量令牌，需在 README 中记录必需的环境变量。
  • 环境变量（stdio）：通过 env 向 MCP 服务器传递配置，如 DATABASE_URL、API_KEY、LOG_LEVEL。

集成模式

  • 模式一：简单工具包装。命令与用户交互后调用 MCP 工具，适合在 MCP 调用前增加校验或预处理。
  • 模式二：自主智能体。智能体自主使用 MCP 工具完成多步流程，无需用户交互。
  • 模式三：多服务器插件。集成多个 MCP 服务器，适合跨多个服务的工作流。

安全最佳实践

  • 始终使用 HTTPS/WSS 安全连接，不要使用 HTTP/WS。
  • 令牌管理：使用环境变量存放令牌、在 README 记录必需变量、让 OAuth 流程处理认证；不要硬编码令牌、不要把令牌提交到 git、不要在文档中分享令牌。
  • 权限范围：只预授权必要的 MCP 工具，避免使用通配符预授权全部工具。

错误处理

  • 连接失败：在命令中提供回退行为，告知用户连接问题，检查服务器 URL 与配置。
  • 工具调用错误：调用前校验输入，提供清晰错误信息，检查速率限制与配额。
  • 配置错误：开发期间测试服务器连通性，校验 JSON 语法，检查必需的环境变量。

性能考虑

  • 懒加载：MCP 服务器按需连接，并非所有服务器都在启动时连接，首次使用工具触发连接，连接池自动管理。
  • 批处理：尽可能批量处理相似请求，例如用带过滤条件的单次查询代替多次单独查询。

测试 MCP 集成

本地测试步骤：在 .mcp.json 中配置 MCP 服务器；在本地安装插件（.claude-plugin/）；运行 /mcp 验证服务器出现；在命令中测试工具调用；使用 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（在命令与智能体中使用 MCP 工具）。示例配置位于 examples/：stdio-server.json、sse-server.json、http-server.json。

外部资源：官方 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。