构建 MCP 服务器时如何选型与落地（部署模型、工具设计…

当你要为 Claude 构建 MCP 服务器或封装 API 时，先做需求发现再决定部署形态与工具设计，避免早期选错导致重写。

适用场景

解决思路

1. 先加载 Claude 专属上下文：在回答或搭建脚手架前，抓取 https://claude.com/docs/llms-full.txt（Claude connector 文档的完整导出），因为 MCP 规范是通用的，而 Claude 有额外的认证类型、审核标准和限制。
2. 在完成 Phase 1 的问题之前不要开始搭建脚手架；如果用户的开场消息已回答了这些问题，确认后直接跳到推荐。
3. Phase 1 需求盘问（一次性批量提问，不要逐条盘问，按用户已提供的信息调整措辞）：1) 它连接什么——云 API（SaaS、REST、GraphQL）倾向远程 HTTP；本地进程/文件系统/桌面应用倾向 MCPB 或本地 stdio；硬件、OS 级 API 或用户特定状态倾向 MCPB；无外部依赖的纯逻辑/计算两者皆可，默认远程。
4. 2) 谁会用——只有我/我的团队在本机用，本地 stdio 可接受（最易原型）；任何安装它的人，强烈优先远程 HTTP，若必须本地则用 MCPB；想要 UI 组件的 Claude 桌面用户，用 MCP app（远程或 MCPB）。
5. 3) 暴露多少个不同操作——约 15 个以下用「每个操作一个工具」；几十到几百个操作（如封装大型 API 面）用「搜索 + 执行」模式。
6. 4) 工具是否需要调用中途的用户输入或丰富展示——简单结构化输入（从列表选、输入值、确认）用 Elicitation（规范原生、零 UI 代码，但宿主支持在铺开中，Claude Code ≥2.1.76，务必配合能力检查与回退，见 references/elicitation.md）；丰富/可视化 UI（图表、带搜索的自定义选择器、实时仪表盘）用 MCP app 组件（基于 iframe，需要 @modelcontextprotocol/ext-apps，见 build-mcp-app 技能）；两者都不需要则返回文本/JSON 的普通工具。
7. 5) 上游服务用什么认证——无/API key 较直接；OAuth 2.0 则需要支持 CIMD（首选）或 DCR 的远程服务器，见 references/auth.md。
8. Phase 2 推荐部署模型（要有主见，只推荐一条路径，按优先级）：⭐ 远程 streamable-HTTP MCP 服务器（默认推荐）——托管服务通过 streamable HTTP 讲 MCP，是封装云 API 的推荐路径；优势为零安装摩擦（用户加个 URL 即可）、一次部署服务所有用户且你可控制升级、OAuth 流程可正常工作（服务器可处理重定向、DCR、令牌存储）、跨 Claude desktop、Claude Code、Claude.ai 及第三方 MCP 宿主可用；除非服务器必须接触用户本机，否则选它。最快部署用 Cloudflare Workers（见 references/deploy-cloudflare-workers.md，两条命令从零到上线 URL）；可移植的 Node/Python 用 references/remote-http-scaffold.md（Express 或 FastMCP，可跑在任何主机）。
9. Elicitation（结构化输入、无需构建 UI）：若工具只需用户确认、选一个选项或填短表单，用 elicitation 零 UI 代码完成；服务器发送扁平 JSON schema，宿主渲染原生表单，规范原生、无需额外包。注意宿主支持较新（Claude Code 在 v2.1.76 发布，Desktop 未确认），若客户端未声明该能力 SDK 会抛错；务必先检查 clientCapabilities.elicitation 并准备回退，规范做法见 references/elicitation.md。当需要嵌套/复杂数据、可滚动/可搜索列表、可视化预览、实时更新时，升级到 build-mcp-app 组件。
10. MCP app（远程 HTTP + 交互式 UI）：在远程 HTTP 基础上加 UI 资源——在聊天中渲染的交互式组件，支持带搜索的丰富选择器、图表、实时仪表盘、可视化预览，构建一次即可在 Claude 和 ChatGPT 渲染；当 elicitation 的扁平表单约束不适用（需要自定义布局、大型可搜索列表、可视化内容或实时更新）时选它；通常远程，但若 UI 需驱动本地应用可作为 MCPB 发布；交接给 build-mcp-app 技能。
11. MCPB（打包的本地服务器）：本地 MCP 服务器与其运行时一起打包，用户无需安装 Node/Python，是发布本地服务器的受认可方式；当服务器必须跑在用户机器上（读本地文件、驱动桌面应用、与 localhost 服务通信或需要 OS 级访问）时选它；交接给 build-mcpb 技能。
12. 本地 stdio（npx / uvx）——不推荐用于分发：通过 npx / uvx 在用户机器上启动的脚本，适合个人工具和原型；分发很痛苦（用户需正确运行时、无法推送更新、唯一分发渠道是 Claude Code 插件）；仅作为过渡推荐，若用户坚持则搭建但注明 MCPB 升级路径。
13. Phase 3 选择工具设计模式（工具 schema 会直接进入 Claude 的上下文窗口，如何切分比多数人预期更重要）：模式 A「每个操作一个工具」（小接口面）——操作空间小（约 15 个以下）时给每个操作专用工具，配紧凑描述和 schema，例如 create_issue（参数 title、body、labels[]）、update_issue（参数 id、title?、body?、state?）、search_issues（参数 query、limit?）、add_comment（参数 issue_id、body）；优点是 Claude 读一次工具列表就知道能做什么、无发现往返、每个工具 schema 精确校验输入；当一个或多个工具带交互式组件（MCP app）时尤其好，每个组件自然绑定一个工具。
14. 模式 B「搜索 + 执行」（大接口面）——封装大型 API（几十到几百个端点）时把每个操作都列为工具会淹没上下文窗口并降低模型表现；改为只暴露两个工具：search_actions（给定自然语言意图，返回匹配动作及其 ID、描述和参数 schema）和 execute_action（按 ID 加 params 对象执行动作）；服务器内部持有完整目录，Claude 搜索、选择、执行，上下文保持精简。混合做法：把最常用的 3–5 个动作提升为专用工具，长尾留在搜索/执行后面；schema 示例和描述撰写指南见 references/tool-design.md。
15. Phase 4 选择框架（推荐以下两个，其他框架存在但这两个对 MCP 规范覆盖和 Claude 兼容性最好）：官方 TypeScript SDK（@modelcontextprotocol/sdk，TS/JS）为默认选择，规范覆盖最好、最先获得新特性；FastMCP 3.x（PyPI 上的 fastmcp，Python）适合用户偏好 Python 或封装 Python 库，基于装饰器、样板极少，注意这是 jlowin 的包，不是官方 mcp SDK 里捆绑的已冻结的 FastMCP 1.0；若用户已有语言/技术栈偏好就随它，两者产生相同的线上协议。
16. Phase 5 搭建脚手架并交接：确定四个决策（部署模型、工具模式、框架、认证）后只做以下之一——1) 远程 HTTP 且无 UI：用 references/remote-http-scaffold.md（可移植）或 references/deploy-cloudflare-workers.md（最快部署）就地搭建，本技能可完成；2) MCP app（UI 组件）：总结目前决策后加载 build-mcp-app 技能；3) MCPB（打包本地）：总结目前决策后加载 build-mcpb 技能；4) 本地 stdio 原型：就地搭建（最简单情形），标注 MCPB 升级路径。交接时用一段话重述设计简报，避免下一个技能重复提问。
17. 了解工具之外的其它原语（多数服务器从工具开始且从不需要其它，但知道它们存在可避免重复造轮子）：Resources 由宿主应用（非 Claude）触发，用于把文档/文件/数据暴露为可浏览上下文；Prompts 由用户（斜杠命令）触发，用于固定工作流（如 /summarize-thread）；Elicitation 由服务器在工具中途触发，用于不构建 UI 就向用户要输入；Sampling 由服务器在工具中途触发，用于在工具逻辑中需要 LLM 推理；见 references/resources-and-prompts.md、references/elicitation.md、references/server-capabilities.md。
18. Phase 6 在 Claude 中测试并发布：1) 把服务器 URL 作为自定义 connector 加到 Settings → Connectors 对真实 Claude 测试（本地服务器用 Cloudflare tunnel），Claude 在 initialize 时以 clientInfo.name: "claude-ai" 标识自己，见 https://claude.com/docs/connectors/building/testing；2) 运行提交前检查清单——读写工具拆分、必需注解、名称长度限制、提示注入规则，见 https://claude.com/docs/connectors/building/review-criteria；3) 提交到 Anthropic Directory，见 https://claude.com/docs/connectors/building/submission；4) 建议发布一个用 skills 包装此 MCP 的插件——多数合作方两者都发，见 https://claude.com/docs/connectors/building/what-to-build。
19. 参考决策矩阵：封装小型 SaaS API → 远程 HTTP + 每操作一个工具；封装大型 SaaS API（50+ 端点）→ 远程 HTTP + 搜索/执行；带丰富表单/选择器的 SaaS API → MCP app（远程）+ 每操作一个工具；驱动本地桌面应用 → MCPB + 每操作一个工具；带聊天内 UI 的本地桌面应用 → MCP app（MCPB）+ 每操作一个工具；读写本地文件系统 → MCPB + 视接口面而定；个人原型 → 本地 stdio + 最快的方式。
20. 参考文件：references/remote-http-scaffold.md（TS SDK 和 FastMCP 的最小远程服务器）、references/deploy-cloudflare-workers.md（最快部署路径，Workers 原生脚手架）、references/tool-design.md（撰写 Claude 能理解的工具描述和 schema）、references/auth.md（OAuth、CIMD、DCR、令牌存储模式）、references/resources-and-prompts.md（两个非工具原语）、references/elicitation.md（规范原生的工具中途用户输入，含能力检查与回退）、references/server-capabilities.md（instructions、sampling、roots、logging、progress、cancellation）、references/versions.md（版本敏感声明台账，更新时检查）。

适用边界 · 注意事项

• 当服务器必须接触用户本机（读本地文件、驱动桌面应用、与 localhost 服务通信或需要 OS 级访问）时，不要选远程 HTTP，应选 MCPB。
• 当需要嵌套/复杂数据、可滚动/可搜索列表、可视化预览或实时更新时，不要用 elicitation 的扁平表单，应升级到 MCP app 组件。
• 不要把本地 stdio（npx / uvx）作为面向他人分发的方案，它只适合个人工具和原型，分发困难且无法推送更新。