课时

在本讲中，我们将拆解什么是 MCP（ Model Context Protocol），为什么该协议在 ChatGPT Apps 技术栈中必不可少，以及它与“自定义的 REST”有何不同。我们会对齐一张架构图（ChatGPT → MCP 客户端 → 你的 MCP 服务器 → 数据库/API），学习协议的关键实体（ tools、 resources、 prompts 和 capabilities），并理解 MCP 如何已经通过类似 callTool 这样的调用“隐藏”在 Apps SDK 内，以及如何不再把它当作黑盒。

在本讲中，我们拆解基于 JSON‑RPC 2.0 之上的 MCP “原始”消息格式：区分 request、 reply 与 notification，如何用 id 关联消息，服务器何时应返回 result、何时应返回 error，以及协议中 tools/ resources/ prompts 原语（方法 tools/list、 tools/call、 resources/read、 prompts/get）的样子。最后我们会把这些与 Apps SDK 串起来，以 window.openai.callTool 为例，并练习阅读/修复 MCP‑JSON。

解析客户端与 MCP 服务器通过 initialize 请求进行“初次相识”的过程：如何协商 protocolVersion、客户端与服务器各自声明哪些 capabilities、为什么必须等待 notifications/initialized，以及在完成 handshake 之后如何通过 tools/list、 resources/list 和 prompts/list 做 discovery。最后——提供 GiftGen 的实操示例与常见错误清单。

在本课中，我们将用 Node.js/TypeScript 搭建第一个可工作的 MCP 服务器：启动 HTTP 端点 /mcp，从包 @modelcontextprotocol/sdk 创建服务器 McpServer，接上类似 StreamableHttpServerTransport 的传输层，并注册 MCP 的三类基础实体： tool（工具 suggest_gifts，其 Zod 模式为 inputSchema）、 resource（目录 gift_catalog，带正确的 mimeType）和 prompt（模板 birthday_gift）。另外——我们还会讲运行时、如何在本地启动，以及常见错误分析。

在本讲中，我们将通过检查器讲解 MCP 服务器的实用调试：MCP Jam/Inspector 如何重放握手（方法 initialize）并读取 capabilities，如何手动调用 tools/list 和 tools/call 并查看原始 JSON‑RPC，以及如何在服务端搭建日志（结构化 JSON 日志、 stdout/ stderr 分流、PII 脱敏），以便在接入 ChatGPT Apps / Apps SDK 之前就捕获问题。