前言¶

用 MCP（Model Context Protocol）写服务时，真正的工作量往往不在协议本身，而在这些细节上：选哪种 transport、工具的输入输出 schema 怎么设计、错误怎么返回才不会让模型误读、鉴权用 OAuth 还是 API key、content 与 structuredContent 该走哪个通道、已知 SDK 行为如何规避，以及什么时候该做 v2 迁移。mcp-best-practices 就是针对这一连串问题给出的参考 Skill，把构建和审查 MCP server / tool 时需要覆盖的点整理成了一份可查阅的清单。

这是什么¶

mcp-best-practices 是一个面向 MCP 服务开发的社区 Skill，坐标 @user_15292d5a/yjkj-mcp-best-practices，当前版本 1.0.0，分类 dev-programming，来源标记为 community。它以 TypeScript SDK 为基准（对应 spec 2025-11-25，SDK v1.29，v2 为 alpha 版），覆盖从传输层到部署上线的一整条链路。

核心功能¶

根据官方简介，该 Skill 覆盖以下主题：

• transports：传输方式的选择与配置
• tool 与 schema 设计：工具接口和数据结构的编写规范
• error handling：错误返回方式，避免模型把错误当成正常结果
• security and OAuth：鉴权与安全实践
• performance：性能相关的注意事项
• known SDK bugs：TypeScript SDK 已知问题的规避
• content vs structuredContent：两种内容交付通道的区别与取舍
• v2 migration：从 v1 迁移到 v2 alpha 的注意事项
• MCP Apps、extensions 与 Registry：生态相关的扩展话题

它的定位是”构建或审查 MCP server / tool 时使用”，即既适用于从零搭建，也适用于代码评审时对照检查。

安装与启用¶

该 Skill 基于通用 SKILL.md 格式分发。已抓取的资料显示其标签为 requires_api_key=false，即使用时不需要额外配置 API key。

官方抓取资料中未给出具体的安装命令或各工具（Cursor、Claude Code、Codex CLI）的配置差异，安装方式请以官方页面为准：

https://api.skillhub.cn/user_15292d5a/yjkj-mcp-best-practices

在支持 Agent Skill 的客户端中启用时，通常需要指定该 Skill 的安装目录，具体字段以客户端文档为准，本文不作推断。

典型用法¶

已抓取资料中未提供可复现的代码示例，因此这里不给出虚构的调用样例。实际使用方式是：在开发或审查 MCP 服务的过程中，将 Skill 作为参考文档查阅，针对当前所处的环节（比如选 transport、写 schema、处理错误、配置 OAuth）找到对应条目核对。相关示例请以官方页面为准。

适用场景与注意¶

适合以下开发者：

• 正在用 TypeScript SDK 构建 MCP server 或 tool 的人
• 需要评审 MCP 相关代码、寻找常见问题清单的人
• 计划从 SDK v1 迁移到 v2 alpha 的人

需要注意的限制：

• 该 Skill 以 TypeScript SDK 为基准，其他语言 SDK 的对应实践不在其覆盖范围内
• SDK v2 仍为 alpha 版本，v2 相关建议（迁移、MCP Apps、extensions）需要结合官方公告判断稳定性
• 内容基准为 spec 2025-11-25，后续规范变更可能需要重新核对

结尾¶

mcp-best-practices 的价值在于把 MCP 服务开发的常见决策点和坑位整理成一份按主题组织的清单，省去在协议文档、SDK 仓库和 issue 之间反复检索的成本。官方地址：https://api.skillhub.cn/user_15292d5a/yjkj-mcp-best-practices