SuperAPI AI 工具集

mcp-integration

编程与开发

查看项目

更新于 11-12 06:46

技能介绍

MCP Integration 是一个技能,说明如何在 Claude Code 插件中集成 Model Context Protocol(MCP),让插件通过结构化工具访问外部服务与 API。该技能适用于用户提出添加 MCP 服务器、集成 MCP、在插件中配置 MCP、使用 .mcp.json 或设置 Model Context Protocol 等需求时。

主要能力

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

配置方式

  1. 独立 .mcp.json(推荐):在插件根目录创建 .mcp.json。示例中通过 command、args、env 配置数据库工具服务器,并用 ${CLAUDE_PLUGIN_ROOT} 指向插件内路径,用 ${DB_URL} 读取环境变量。优点是职责分离清晰、易维护、适合多个服务器。
  2. 在 plugin.json 中内联:在 plugin.json 增加 mcpServers 字段,适合简单的单服务器插件。

服务器类型

  • stdio(本地进程):以子进程方式执行本地 MCP 服务器,通过 stdin/stdout 通信,随 Claude Code 退出而终止。适合文件系统访问、本地数据库、自定义或 NPM 打包的 MCP 服务器。示例使用 npx -y @modelcontextprotocol/server-filesystem 并传入允许路径。
  • SSE(Server-Sent Events):连接托管 MCP 服务器,支持 OAuth,首次使用时在浏览器认证,令牌由 Claude Code 管理,无需本地安装。适合 Asana、GitHub 等官方托管服务器及云端 MCP 端点。
  • HTTP(REST API):连接 RESTful MCP 服务器,使用 headers 传递令牌,适合基于 REST API 的后端与无状态交互。
  • WebSocket(ws):连接 WebSocket MCP 服务器,支持实时双向通信、持久连接、服务器推送与低延迟场景。

环境变量展开 所有配置支持环境变量替换:${CLAUDE_PLUGIN_ROOT} 表示插件目录,应始终用于可移植路径;用户 shell 环境变量可用于 env 中的 API_KEY、DATABASE_URL 等。最佳实践是在插件 README 中记录所有必需环境变量。

工具命名与授权 MCP 工具自动加前缀,格式为 mcp__plugin_<plugin-name>_<server-name>__<tool-name>。可在命令 frontmatter 的 allowed-tools 中预先允许特定工具;通配符应谨慎使用,安全上建议预先允许具体工具而非通配符。

生命周期 插件启用时 MCP 服务器启动,首次使用工具前建立连接,配置变更需重启;流程为插件加载、解析配置、启动进程或建立连接、发现并注册工具、以带前缀名称提供工具。可用 /mcp 命令查看包括插件提供的所有服务器。

认证模式

  • OAuth(SSE/HTTP):由 Claude Code 自动处理,首次使用浏览器认证,无需额外配置。
  • 基于令牌(Headers):静态或环境变量令牌,需在 README 记录所需变量。
  • 环境变量(stdio):向 MCP 服务器传递 DATABASE_URL、API_KEY、LOG_LEVEL 等配置。

集成模式

  • 简单工具包装:命令中结合用户交互调用 MCP 工具,适合在调用前做校验或预处理。
  • 自主智能体:智能体自主调用 MCP 工具完成多步工作流,无需用户交互。
  • 多服务器插件:同时集成多个 MCP 服务器,适合跨服务工作流。

安全最佳实践 始终使用 HTTPS/WSS;令牌通过环境变量管理并在 README 记录;让 OAuth 流程处理认证;不要硬编码令牌、不要提交令牌到 git、不要在文档中分享令牌;只预先允许必要的 MCP 工具;不要使用通配符开放全部工具。

错误处理 连接失败时提供回退行为并告知用户,检查 URL 与配置;工具调用失败时先验证输入、给出清晰错误信息并检查限流与配额;配置错误时测试连通性、校验 JSON 语法并检查必需环境变量。

性能考虑 MCP 服务器按需连接,并非全部在启动时连接,首次使用工具时触发连接,连接池自动管理;应尽量批量相似请求,例如用带过滤条件的单次查询替代多次单独查询。

测试与调试 本地测试步骤:在 .mcp.json 配置服务器、本地安装插件、运行 /mcp 确认服务器出现、在命令中测试工具调用、用 claude --debug 查看连接问题。验证清单包括配置为有效 JSON、URL 正确可访问、环境变量已记录、工具出现在 /mcp 输出、认证正常、工具调用成功、错误被妥善处理。调试时启用 claude --debug,查看连接尝试、工具发现、认证流程与调用错误。常见问题包括服务器未连接、工具不可用(需检查连接、名称是否精确、重启 Claude Code)、认证失败(清除缓存令牌、重新认证、检查令牌范围与权限、确认环境变量)。

参考与资源 技能附带 references/server-types.md、authentication.md、tool-usage.md 以及 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.json、所有文件引用使用 ${CLAUDE_PLUGIN_ROOT}、在 README 记录必需环境变量、用 /mcp 本地测试、在相关命令中预先允许 MCP 工具、处理认证、测试错误场景、在插件 README 记录 MCP 集成。自定义或本地服务器优先使用 stdio,带 OAuth 的托管服务优先使用 SSE。