MCP Integration 用于让 Claude Code 插件通过 Model Context Protocol 集成外部服务与 API，将外部服务能力以工具形式暴露在 Claude Code 中。
用途 适用于需要连接外部服务（数据库、API、文件系统）的插件；可从单个服务提供 10 个以上相关工具；可处理 OAuth 与复杂认证流程；也可把 MCP 服务器与插件打包以便自动安装配置。当用户要求“添加 MCP 服务器”“集成 MCP”“在插件中配置 MCP”“使用 .mcp.json”“设置 Model Context Protocol”时使用本技能。
MCP 服务器配置方式 方式一：专用 .mcp.json（推荐）。在插件根目录创建 .mcp.json，示例如数据库工具配置，使用 command、args、env 字段，并可用 ${CLAUDE_PLUGIN_ROOT} 引用插件目录。优点是关注点分离清晰、易维护、适合多服务器。 方式二：在 plugin.json 中内联。添加 mcpServers 字段，配置 name、version 与 mcpServers 内容。优点是单一配置文件，适合简单的单服务器插件。
MCP 服务器类型 stdio（本地进程）：以子进程方式执行本地 MCP 服务器，配置 command、args、env，例如通过 npx 运行 @modelcontextprotocol/server-filesystem。适用于文件系统访问、本地数据库连接、自定义 MCP 服务器、NPM 打包的 MCP 服务器。Claude Code 负责启动和管理进程，经 stdin/stdout 通信，并在 Claude Code 退出时终止。 SSE（Server-Sent Events）：连接托管 MCP 服务器并支持 OAuth，配置 type 为 sse 与 url。适用于官方托管 MCP 服务器（如 Asana、GitHub）、带 MCP 端点的云服务、基于 OAuth 的认证，无需本地安装。认证由 Claude Code 自动处理 OAuth 流程，首次使用时提示用户，令牌由 Claude Code 管理。 HTTP（REST API）：连接 RESTful MCP 服务器并使用令牌认证，配置 type 为 http、url 与 headers（如 Authorization、X-Custom-Header）。适用于基于 REST API 的 MCP 服务器、令牌认证、自定义 API 后端、无状态交互。 WebSocket（实时）：连接 WebSocket MCP 服务器进行实时双向通信，配置 type 为 ws、url 与 headers。适用于实时数据流、持久连接、服务器推送通知、低延迟需求。
环境变量展开 所有 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。可在命令 frontmatter 中通过 allowed-tools 预允许特定 MCP 工具，也可使用通配符（应谨慎），最佳实践是预允许具体工具而非通配符，以保障安全。
生命周期管理 MCP 服务器在插件启用时启动，首次使用工具前建立连接，配置更改后需重启。生命周期：插件加载、解析 MCP 配置、启动服务器进程（stdio）或建立连接（SSE/HTTP/WS）、发现并注册工具、工具以 mcp__plugin_...__... 形式可用。可使用 /mcp 命令查看包括插件提供的服务器在内的所有服务器。
认证模式 OAuth（SSE/HTTP）：由 Claude Code 自动处理，用户首次使用时在浏览器中认证，无需额外配置。令牌方式（Headers）：使用静态或环境变量令牌，需在 README 中记录必需环境变量。环境变量（stdio）：向 MCP 服务器传递配置，如 DATABASE_URL、API_KEY、LOG_LEVEL。
集成模式 模式一：简单工具包装。命令结合用户交互使用 MCP 工具，适合在 MCP 调用前添加校验或预处理。模式二：自主智能体。智能体自主使用 MCP 工具，适合无需用户交互的多步 MCP 工作流。模式三：多服务器插件。集成多个 MCP 服务器，适合跨多个服务的工作流。
安全最佳实践 始终使用 HTTPS/WSS 安全连接。令牌管理：使用环境变量存储令牌、在 README 记录必需环境变量、让 OAuth 流程处理认证；不要硬编码令牌、不要将令牌提交到 git、不要在文档中分享令牌。权限范围：仅预允许必要的 MCP 工具，避免通配符。
错误处理 连接失败：在命令中提供回退行为、告知用户连接问题、检查服务器 URL 与配置。工具调用错误：调用前校验输入、提供清晰错误消息、检查速率限制与配额。配置错误：开发期间测试服务器连通性、校验 JSON 语法、检查必需环境变量。
性能考虑 懒加载：MCP 服务器按需连接，并非所有服务器在启动时连接，首次使用工具时触发连接，连接池自动管理。批处理：尽可能批量处理相似请求，例如用带过滤条件的单次查询替代循环逐个查询。
测试 MCP 集成 本地测试步骤：在 .mcp.json 中配置 MCP 服务器；本地安装插件（.claude-plugin/）；运行 /mcp 验证服务器出现；在命令中测试工具调用；用 claude --debug 查看连接问题。验证清单包括配置为有效 JSON、服务器 URL 正确可访问、必需环境变量已记录、工具出现在 /mcp 输出、认证正常、命令中工具调用成功、错误情况处理妥当。
调试 启用 claude --debug，关注 MCP 服务器连接尝试、工具发现日志、认证流程、工具调用错误。常见问题：服务器未连接（检查 URL、服务器是否运行、网络连通性、认证配置）；工具不可用（确认服务器连接成功、工具名完全匹配、运行 /mcp 查看、配置更改后重启 Claude Code）；认证失败（清除缓存令牌、重新认证、检查令牌范围与权限、确认环境变量已设置）。
快速参考 MCP 服务器类型对照：stdio 使用进程传输，适合本地工具与自定义服务器，认证方式为环境变量；SSE 使用 HTTP，适合托管服务与云 API，认证为 OAuth；HTTP 基于 REST，适合 API 后端与令牌认证；ws 使用 WebSocket，适合实时与流式场景，认证为令牌。配置清单：指定服务器类型、填写类型特定字段（command 或 url）、配置认证、记录环境变量、使用 HTTPS/WSS、路径使用 ${CLAUDE_PLUGIN_ROOT}。
最佳实践与禁止事项 应做：使用 ${CLAUDE_PLUGIN_ROOT} 保证路径可移植；记录必需环境变量；使用安全连接；在命令中预允许具体 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 服务器类型；在插件根目录创建 .mcp.json；所有文件引用使用 ${CLAUDE_PLUGIN_ROOT}；在 README 记录必需环境变量；用 /mcp 本地测试；在相关命令中预允许 MCP 工具；处理认证；测试错误情况；在插件 README 中记录 MCP 集成。自定义/本地服务器优先使用 stdio，带 OAuth 的托管服务优先使用 SSE。