MCP：把数据接口变成 Agent 工具

前面的 API 已经能被程序调用，但 Agent 还需要知道“有哪些能力、什么时候用、参数怎么填、结果怎么读”。MCP（Model Context Protocol）提供了一套开放的协议约定，把外部数据和能力以统一方式交给 AI 应用。

MCP 基于 JSON-RPC 消息。Host 是承载 AI 应用的程序，Client 负责与某个 MCP Server 建立连接，Server 暴露外部能力。一个 Host 可以连接多个 Server。

Server 可以提供三类能力，但控制方不同：

• Tools：模型控制的可调用函数，例如查询数据或执行计算。客户端发现工具后，模型可以决定是否调用。
• Resources：应用控制的上下文数据，例如文件、数据库 schema 或其他可读取内容。Host 决定何时把资源纳入上下文。
• Prompts：服务器提供的可复用提示模板，应用可以发现并使用它们。

不要把 resources 当成“模型自动调用的工具”，也不要把 prompts 当成数据接口；三者的用途和控制方式不同。

tools/list 用于发现工具。工具定义至少应包含唯一的 name、描述用途的 description 和非空的 JSON Schema inputSchema；title、outputSchema 与行为 annotations 是可选信息。列表支持分页，服务端应尽量稳定排序。

tools/call 带着工具名和参数调用工具。结果可以包含文本、图片、资源链接等 content，也可以包含符合 outputSchema 的 structuredContent。如果声明了 outputSchema，服务器必须返回符合 schema 的结构化结果，客户端应进行校验。

错误分两类：

• 协议错误：请求结构不合法、未知工具等，使用 JSON-RPC 的 error 返回。
• 工具执行错误：参数值不合法、上游失败或业务条件不满足，放在工具结果中并设置 isError: true。这类结果应包含可操作的说明，方便模型修正参数后重试。

工具注解只是行为提示，不是权限控制或安全保证。服务器仍必须在服务端校验输入、鉴权、限流并清洗输出。

传输方式只规定消息如何发送，不改变 MCP 消息本身的语义：

• stdio：客户端启动本地子进程，通过标准输入输出传递换行分隔的 JSON-RPC 消息，适合本地工具。
• Streamable HTTP：通过一个 MCP HTTP 端点发送请求，客户端使用 HTTP POST；响应可以是 JSON，也可以是请求范围内的 SSE 流，适合远程服务。

早期的 HTTP+SSE 传输方式已由 Streamable HTTP 取代。课程不要把某个 SDK 的类名或启动命令当成协议本身；SDK 会变化，协议字段和官方规范才是接口依据。

{
  "name": "get_market_total",
  "description": "查询指定交易日、指定市场的成交额汇总；返回金额单位为亿元",
  "inputSchema": {
    "type": "object",
    "properties": {
      "trade_date": {"type": "string", "description": "YYYYMMDD"},
      "market": {"type": "string", "enum": ["SH", "SZ", "BJ"]}
    },
    "required": ["trade_date", "market"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "trade_date": {"type": "string"},
      "market": {"type": "string"},
      "turnover_yi_yuan": {"type": "number"}
    },
    "required": ["trade_date", "market", "turnover_yi_yuan"]
  }
}

工具描述应写清数据范围、单位、日期格式、是否需要分页、常见错误和适用场景。返回结果应控制体积，优先提供筛选、汇总和明确的下一页信息，避免把无关的原始数据全部塞进模型上下文。

1. 把 REST 接口逐个机械转换成大量工具，让模型难以选择。
2. 只写“查询日 K”，不写范围、单位、参数格式和限制条件。
3. 把协议错误和业务错误混在一起，导致调用方无法决定是否重试。
4. 把 readOnlyHint 等注解当成真正的权限控制。
5. 把 resources、tools、prompts 当成同一种能力。
6. 把某个版本 SDK 的示例代码当成永久不变的协议细节。

• MCP 官方规范
• MCP Tools 规范
• MCP Resources 规范
• MCP Transports 规范