前言¶

用 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