写过 Claude Code 插件的人大概率经历过同一件事：你花了两小时写好了插件的核心逻辑，然后发现卡在了“怎么让插件调用外部 API”这一步。不是代码写不出来，是不知道该把 MCP 配置塞到哪个文件里、该用哪种 server type、token 往哪放才不会泄露。
Anthropic 显然注意到了这个问题。他们在 Smithery 上发布的 mcp-integration Skill，做的事情就一个：把 Claude Code 插件的 MCP 集成流程标准化。从配置文件的写法、四种 server type 的选择决策、到认证方式的安全实践，全部整理成了可复现的步骤。
说真的，这个 Skill 的价值不在于它教了你什么新概念。MCP 协议本身并不新鲜。它的价值在于把你之前需要翻三份文档、看五个 GitHub issue 才能拼凑出来的“正确做法”，压缩成了一个结构化的操作清单。如果你正在开发或维护 Claude Code 插件，这篇文章会带你走一遍 MCP 集成的完整流程，以及背后那些你不一定注意到的设计决策。
环境准备
MCP Integration Skill 的使用场景比较特殊。它不是那种下载下来就能跑的工具，而是一份集成指南。你的前置条件取决于你想做什么。
如果你是在开发一个新的 Claude Code 插件，需要准备好一个插件项目骨架。插件可以放在 .claude-plugin/ 目录下本地测试，核心文件至少包含 plugin.json 或 .mcp.json。如果你用的是 Claude Code 的命令行版本，确保 claude --debug 能正常输出日志，调试 MCP 连接全靠它。
如果只是想理解 MCP 集成的整体设计，不需要任何环境。把这份 Skill 的 SKILL.md 通读一遍就行。但我的建议是边看边动手，因为 MCP 配置最坑的地方不是语法错误，是 server 连上了但 tool 不出现。这种事情光看文档看不出来，必须跑一遍。
一个常见卡点：很多人第一次配 MCP 会把 .mcp.json 放在项目根目录以外的位置，或者在 plugin.json 里写错了 mcpServers 的字段名。Skill 里的建议很明确，专用 .mcp.json 优于内联配置。这个建议背后有实际原因，后面关键设计章节会展开讲。
操作流程
整个 MCP 集成的操作链路可以分成五步，但真正花时间的只有中间两步。
第一步是选 server type。这个 Skill 把 MCP server 分成了四种，选哪种取决于你的服务跑在哪：
-
stdio：本地工具，以子进程方式启动。适合自定义脚本和 npm 包 -
SSE：云端 SaaS，走 OAuth 自动认证。Asana、GitHub 等官方 server 都用这种 -
HTTP：自建 REST API，手动配 token。适合你自己后端的 MCP 接口 -
WebSocket：实时推送场景，双向长连接。适合需要 server 主动推送数据的场景
如果你不确定选哪个，stdio 是最安全的默认选项，但代价是用户必须本地跑一个进程。
第二步是写配置文件。两种方式：推荐的做法是在插件根目录创建 .mcp.json，把 server 的启动命令或 URL 写进去。备选方案是直接在 plugin.json 里加一个 mcpServers 字段。前者的好处是配置和插件逻辑分离，多个 server 同时配置时不容易乱。后者适合只有一个 server 的简单插件。
第三步是处理认证。这是最容易出错的环节。SSE 类型的 server 走 OAuth 流程，Claude Code 会自动弹出浏览器让用户授权，你不需要在配置里写任何 token。HTTP 和 WebSocket 类型需要手动配 token，Skill 反复强调一点：用环境变量，别硬编码。
asana_server:
type: sse
url: https://mcp.asana.com/sse
第四步是给插件里的 command 和 agent 声明 MCP tool 的权限。每个 MCP tool 的完整名称格式是 mcp__plugin_<插件名>_<server名>__<tool名>。在 command 的 frontmatter 里用 allowed-tools 声明具体要用哪些 tool，避免用通配符全开。
第五步是测试。跑 claude --debug 看日志，或者直接在 Claude Code 里输入 /mcp 看已注册的 server 列表。如果 tool 没出现，先检查 server type 的字段名对不对，SSE 要写 url 不是 command，stdio 要写 command 不是 url。
这五步走下来，整个过程不会超过二十分钟。但有一个细节新手很容易忽略：MCP server 不是插件一加载就立刻启动的。它用的是懒加载策略，只有在第一次调用 tool 的时候才会建立连接。这意味着如果你的 command 从来没触发过那个 tool，server 可能一直没连上。测试的时候记得主动触发一次 tool 调用。
关键设计
这份 Skill 最值得关注的设计不是技术选型，而是它对插件开发者认知负担的精确拆解。
把 MCP 配置拆成四种 server type，表面上是按传输协议分类，实际上是为了引导开发者做决策。你一看到这四个选项，大脑自动开始匹配自己的场景：
-
本地的 Python 脚本，自动对应到 stdio -
Asana 的云 API，自动对应到 SSE -
自己的后端服务，自动对应到 HTTP
这个分类的巧妙之处在于，它把“我该用什么传输协议”这个需要拍脑袋的问题，变成了一个几乎不需要思考的匹配题。
另一个有意识的设计是 .mcp.json 独立于 plugin.json 的分离策略。把 MCP 配置放在单独文件里，不只是为了代码整洁。更实际的考虑是：多人协作修改同一份 plugin.json 时，MCP 的配置变更不应该引起不需要的冲突。而且 .mcp.json 的 JSON 结构比 plugin.json 的嵌套深一层更容易被脚本工具解析，比如 CI 里自动检测 MCP 配置是否完整。
但这份 Skill 也有明显的取舍。它把安全实践放在了比较靠后的位置，而没有作为配置流程的一部分嵌入进去。比如 allowed-tools 的权限最小化原则，Skill 里提到了“避免用通配符”，但这句话放在一个次级段落下，很容易被扫读时跳过。如果我收到一个 MCP 配置里有 mcp__plugin_*__* 这种全开通配符的插件，我会直接拒绝安装。这个 Skill 如果能把安全检查做成配置清单里的一个显式步骤，会比现在的位置更有实用价值。
说到生命周期管理，这份 Skill 对 MCP server 的启动时机解释得不够充分。文档里有一句话容易被忽视：“MCP servers start when plugin enables”，但实际上 stdio 类型的 server 是通过子进程方式启动的，SSE 是建立 HTTP 长连接，两者的资源占用和失败处理完全不同。如果 stdio server 挂了，你需要手动重启 Claude Code，这个细节对实际体验影响很大但 Skill 里一笔带过了。
实战场景
假设你正在写一个项目管理类的 Claude Code 插件，需要同时对接 Jira 和 GitHub。传统的做法是你自己在插件的代码里调用 Jira API 和 GitHub API，处理两种不同的认证方式，然后写一堆胶水代码把结果拼在一起。
用 MCP 集成的思路完全不同。你不需要写任何 API 调用的代码。只需要在 .mcp.json 里配两个 server：
jira:
type: sse
url: https://mcp.jira.com/sse
github:
type: sse
url: https://mcp.github.com/sse
然后在你的 agent 或 command 里声明要用到的 tool。比如一个“生成本周工作报告”的 agent，同时用 Jira 查本周任务、用 GitHub 查本周 commit。Claude Code 会自动处理两个 server 的连接和 tool 调用，你连一行 HTTP 请求都不用写。
这个模式的价值不只是省代码。更关键的是，MCP server 的维护和更新跟你的插件完全解耦了。Jira 官方更新了他们的 MCP server，新增了查询 Sprint 进度的 tool，你的插件不用改任何代码就能自动获得这个新能力。这在传统的手写 API 集成的方案里是不可想象的。
但这个模式也有一个不明显的坑：多 server 场景下的认证流程对用户体验不友好。假设你的插件同时接入了 Jira 和 Asana，用户第一次使用时会弹出两个浏览器窗口分别授权。如果其中一个授权失败，整个 workflow 就卡住了，但用户看不到明确的错误提示，只会觉得“这个插件不好用”。Skill 里对多 server 错误处理的最佳实践几乎没有涉及，这是一个明显的空白。
洞察与反思
这个 Skill 让我重新想了一个问题：好的技术文档到底应该写成什么样。
传统的 API 文档是“告诉你能做什么”，但从来不回答“你应该怎么做”。看 Anthropic 的 MCP 官方文档，你能找到完整的协议规范和 SDK 使用方法，但看不出“如果要给 Claude Code 插件加 MCP，第一步是什么”。这个 Skill 做的事情，就是把规范文档里散落在十几个页面的信息，按决策路径重新组织了一遍。
我现在越来越觉得，这种“决策型文档”才是 AI 工具文档应该进化的方向。不是罗列 API 参数，而是帮开发者做选择：你的场景是什么，选哪个方案，为什么。这比写一百个代码示例更有价值。
但这个 Skill 也暴露了 MCP 生态当前的一个尴尬处境。四种 server type 看似灵活，实际上 SSE 和 HTTP 的功能重叠严重。如果只是调用一个 REST API，你完全可以用 HTTP type，但官方推荐的是 SSE。为什么？因为 SSE 支持 OAuth 自动流程，而 HTTP 需要手动配 token。这不是技术原因，是产品策略的选择。理解了这个背景，你才能理解为什么这个 Skill 反复强调“如果要认证，优先用 SSE”。
另一个观察：这份 Skill 的适用边界比它自己描述的窄。它只针对 Claude Code 的插件体系，不适用于 Claude Desktop 或 Claude API 的 MCP 集成方式。它假设你已经有一个 Clauplugin 项目骨架，但很多开发者实际上是想从零开始理解 MCP。如果你完全是 MCP 新手，建议先读一遍 modelcontextprotocol.io 的基础文档再回来看这份 Skill，否则中间几个配置决策点你可能看不出来为什么这么选。
资源地址
| 资源 | 地址 |
|---|---|
| Smithery | https://smithery.ai/skills/anthropics/mcp-integration |
| MCP 官方文档 | https://modelcontextprotocol.io/ |
| Claude Code MCP 文档 | https://docs.claude.com/en/docs/claude-code/mcp |
总结
回到开头那个问题：花两小时卡在 MCP 配置上到底值不值。答案是不值，但之前确实没办法避免。这个 Skill 的核心贡献，就是把你每次接新服务时都要重新想一遍的那些决策固化成了可重复执行的清单：
-
选什么 server type -
配置写在哪个文件 -
token 放在哪不泄露 -
怎么给 command 声明 tool 权限
但它不是万能钥匙。多 server 错误处理、完整的安全检查清单、配置变更后的热更新策略，这几块目前还是空白。如果你在做生产级的 Claude Code 插件，建议不要只依赖这份 Skill，把 claude --debug 的日志当作你的第二份文档来读。有些问题只能在日志里看到，Skill 再详细也替代不了。
再试一个变通思路：如果你的插件只需要接一个简单的 REST API，可以考虑先跳过 MCP，直接在 command 里用 bash tool 调 curl。等你的插件逻辑跑通了，再回头按这份 Skill 的流程把 MCP 加上去。把“写插件”和“接 MCP”拆成两个独立步骤，效率反而更高。