知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# MCP Server 开发实战 > 导读:本文从"我手上有一个内部订单查询 API 和一套 MySQL,怎么把它做成 Agent 能直接调用的能力?"这个实际开发中的疑问出发,把 MCP 的角色划分(Host / Client / Server)与三种能力(Tools / Resources / Prompts)的选用、开发一个 Server 的完整流程(传输方式选型 → 握手初始化 → 注册能力 → 启动调试)、用主流 SDK 写一个可运行的 Server、工具设计的工程要点、Resources 与 Prompts 的实现、接入客户端与多 Server 管理、生产化要点、本地调试与"连不上"排查逐项讲透,最后给出工程实践与踩坑清单。适合已有后端经验、准备把内部系统接进 Agent 生态的 Java / Python 工程师。  *图:MCP 以标准接口把外部能力接入宿主应用* ## 一、先建立全局认知 ### Q:MCP 里的 Host / Client / Server 到底谁是谁?为什么要有 Client 这一层? A:结论先行——**MCP(Model Context Protocol,模型上下文协议,一套让 LLM 应用与外部能力用统一协议对话的开放标准)是"三段式"结构:Host 是用户直接交互的应用,Server 是能力提供方,而 Client 是 Host 内部为每一个 Server 单独建立的连接器;三者中你真正要开发的是 Server,Client 由宿主应用提供。** Client 这一层存在的唯一理由,是**隔离与一对一会话**:一个 Host 可以同时连很多 Server,每个 Server 都有一条独立的、带自己握手状态与能力协商结果的会话通道。 把它画成一张图:  *图:MCP 的 Host / Client / Server 拓扑* ```text ┌───────────────────────── Host(宿主应用)─────────────────────────┐ │ Claude Desktop / IDE Agent / 你自研的 Agent 服务 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Client A │ │ Client B │ │ Client C │ ← 1 Server 1 Client │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ┌────┴──────────────┴──────────────┴────┐ │ │ │ LLM(决定调用哪个能力、传什么参数) │ │ │ └───────────────────────────────────────┘ │ └────────┬──────────────┬──────────────┬───────────────────────────┘ │ stdio │ stdio │ Streamable HTTP ┌────┴────┐ ┌─────┴────┐ ┌─────┴──────┐ │ Server A│ │ Server B │ │ Server C │ │ 文件系统 │ │ 订单 API │ │ 远程 SaaS │ └─────────┘ └──────────┘ └────────────┘ ``` 三个角色各自负责什么: | 角色 | 归属 | 职责 | 你要不要写 | | --- | --- | --- | --- | | Host(宿主) | 应用层 | 管会话、管 UI、把 Server 的能力转成模型可用的工具列表、执行模型的选择 | 通常不写(用现成客户端) | | Client(客户端连接器) | Host 内部 | 与**单个** Server 建立传输、完成握手、转发请求与通知 | 不写,但要知道它的行为 | | Server(服务端) | 能力层 | 声明并实现 Tools / Resources / Prompts | **这就是本文要写的** | 几个容易混淆的点: - **Host 不是"模型"**。模型是 Host 内部的一个组件,负责"决定调用什么";Host 负责"真的去调、把结果塞回上下文"。所以 Server 的返回值最终是**给模型看的文本**,不是给程序 parse 的二进制。 - **Client 与 Server 是一对一**。同类型的两个 Server(比如两个不同的数据库)也要两条独立连接,各自独立协商能力,互不共享状态。这也意味着"Server 里的全局变量"只在自己进程/会话内共享,别指望跨 Server 共享。 - **协议本身是 JSON-RPC 2.0**。所有请求/响应/通知都是 JSON-RPC 消息,方法名形如 `tools/list`、`tools/call`、`resources/read`、`prompts/get`。知道这一点,调试时你就能直接看报文,而不是对着黑盒猜。 ### Q:Tools / Resources / Prompts 三种能力,什么时候用哪个? A:结论先行——**按"谁来触发"来判断:Tools 由模型决定调用(模型控制),Resources 由宿主应用决定读取(应用控制),Prompts 由用户显式选择(用户控制)。** 三者不是"强弱版本",而是三条不同的触发链路,选错的代价是"该被检索的东西被当工具瞎调"或"该让用户点一下的东西模型永远想不起来"。 三者的官方语义定位与对照: | 能力 | 触发方 | 交互形态 | 典型用法 | 失败代价 | | --- | --- | --- | --- | --- | | Tools | 模型 | 请求-响应,有副作用可能 | 查订单、发消息、建工单、跑 SQL | 高(可能写数据) | | Resources | 宿主应用 | 按 URI 读取,只读 | 读文档、读表结构、读配置、读日志片段 | 低(只读) | | Prompts | 用户 | 用户在界面上选一个模板并填参数 | "/review-pr"、"把这段日志按模板归因" | 低(只是拼提示词) | 判断口诀: 1. **"模型需要自己决定要不要做、按什么参数做"** → 用 Tools。比如"用户问订单状态,模型自己决定去查订单"。 2. **"这是背景资料,需要被读进来当上下文,但不该由模型凭空决定去读"** → 用 Resources。比如"表结构说明"、"接口文档"。 3. **"这是一个人工工作流的入口,用户点了才生效"** → 用 Prompts。比如 IDE 里的斜杠命令。 三条容易被忽略的边界: - **Resources 更适合"挂在那儿等被引用",而不是"等模型来拉"**。如果宿主没有实现自动注入 Resources 的策略,模型是不知道有这些资源的。所以关键资料**不要只放 Resources**,要么在 Tools 里提供一个 `get_xxx` 兜底,要么在 Prompts/System Prompt 里说明有哪些资源 URI。 - **Tools 的描述是给模型看的,不是给人看的**。描述质量直接决定调用正确率(后面有专节讲)。 - **三者可以互相兜底**:把"读表结构"同时做成 Resource(供宿主注入)和 Tool(供模型主动拉),是生产环境很常见的一种冗余设计。**具体客户端对 Resources/Prompts 的支持度不一,接入前需结合版本与客户端文档确认。** ### Q:什么样的系统适合做成 MCP Server?什么不适合? A:结论先行——**适合"有明确边界、可被语言描述、调用频率不极端、结果能被文本化"的内部能力;不适合高频大吞吐的数据通道、不适合把整个业务系统无脑暴露、也不适合把已经在 Agent 进程内、零网络成本就能完成的纯计算包一层协议。** 适合的典型形态: - 内部业务 API 的"读操作"(查订单、查工单、查用户画像) - 只读数据库查询(表结构 + 受控 SQL) - 内部知识库/文档检索(如果已有 RAG 接口,包一层即可) - DevOps 操作(查日志、看监控、发版前检查) - 第三方 SaaS 的封装(CRM、项目管理) 不适合或要谨慎的: - **高频、低延迟的数据通道**:MCP 走 JSON-RPC(部分传输还要 HTTP 往返),比直接函数调用多了一层序列化与网络。压测前先算清楚这份开销。 - **大结果集**:返回 200MB 日志会让上下文直接爆掉(见"返回值结构"一节)。 - **写操作的默认开放**:`delete_xxx`、`exec_sql` 这类工具默认不要直接给模型,先做审批或白名单。 - **纯本地计算**:在 Agent 进程内 `def add(a,b)` 就能做的事,没必要发一条 MCP 消息。 一句话判断法:**"如果这个能力被外部合作方调用,我会不会给它单独设计一套鉴权和限流?"会,那它适合做成 Server;不会,那它大概率就地实现更划算。** ## 二、开发一个 Server 的完整流程 ### Q:传输方式怎么选,stdio 还是可流式 HTTP(Streamable HTTP)? A:结论先行——**本地、单用户、由宿主拉起的进程用 stdio;需要远程部署、多客户端共享、要走企业网关与统一鉴权的用 Streamable HTTP。** 判断标准只有一条:**Server 是"宿主的子进程"还是"独立部署的服务"**。 两种传输的关键差异: | 维度 | stdio | Streamable HTTP | | --- | --- | --- | | 部署形态 | 宿主 spawn 的子进程,生命周期跟随宿主 | 独立服务,长期在线 | | 通信 | 标准输入/输出上的换行分隔 JSON-RPC | HTTP POST(响应可为 JSON 或 SSE 流) | | 鉴权 | 靠进程环境变量/本机权限,无网络鉴权 | 标准 HTTP 鉴权(如 OAuth,规范在演进) | | 多客户端 | 一对一,天然隔离 | 需处理会话与并发 | | 网络成本 | 无 | 有 RTT,需考虑超时与重试 | | 调试难度 | 看不到明文流量,要靠日志 | 可以用 curl / 抓包直接看 | | 典型场景 | 本地工具、IDE、个人助手 | 团队共享、SaaS 化、企业内部平台 | 几个必须知道的细节: - **stdio 下 stdout 是协议通道,日志必须写 stderr。** 这是最常见、也最致命的错误——你随手一个 `print()` 或某个库的 `stdout` 输出就会插入一条非 JSON 内容,Client 解析失败并断连。表现为"Server 明明启动了,客户端就是连不上"。 - **HTTP + SSE 是上一代方案**。较新的规范用 **Streamable HTTP** 取代了"HTTP + SSE"双向长连接的做法;如果你翻到旧教程里的 `/sse` 端点配置,**需结合协议版本与客户端支持情况确认**,新项目优先 Streamable HTTP。 - **Streamable HTTP 有会话概念**:服务端可以在响应头里下发会话标识,后续请求带着它继续同一会话。会话隔离、粘性、过期清理都是服务端要自己处理的(多实例部署时尤为麻烦)。**具体头字段名与语义会随规范版本变化,落地前须核对官方文档。** - **能 stdio 就 stdio**:如果你的用户就是本机开发者/本机 Agent,stdio 少一整层安全与运维成本。反过来,只要出现"多个客户端共享同一份能力",就得忍受 HTTP 的复杂度。 ### Q:一次完整的 MCP 会话是怎么"握手"起来的? A:结论先行——**流程是固定的四步:Client 发 `initialize` 请求(带自己的协议版本与能力)→ Server 回 `initialize` 响应(带自己的协议版本与能力)→ Client 发 `notifications/initialized` 通知 → 双方进入正常请求期,Client 才开始 `tools/list`、`tools/call`。**  *图:MCP 客户端与服务端的初始化与工具调用时序* ```text Client Server │ ── initialize (protocolVersion, clientInfo, capabilities) ──→ │ ① 版本 + 能力协商 │ ←── result (protocolVersion, serverInfo, capabilities) ────── │ ② 声明自己会什么 │ ── notifications/initialized ────────────────────────────────→ │ ③ 确认 │ │ │ ── tools/list ───────────────────────────────────────────────→ │ ④ 拉工具清单(给模型) │ ←── result: [{name, description, inputSchema}, ...] ───────── │ │ │ │ ── tools/call {name, arguments} ─────────────────────────────→ │ ⑤ 模型选中后执行 │ ←── result: {content: [...], isError?: bool} ──────────────── │ │ │ │ ── resources/list / resources/read / prompts/list / prompts/get │ ⑥ 其余能力同构 │ │ │ ←── notifications/* (Server 主动推送,如清单变化) │ ⑦ 可选 ``` 理解握手的意义在于三点: 1. **能力协商决定"能用什么"**。你的 Server 在 `initialize` 响应里声明支持 `tools`、`resources`、`prompts` 中的哪些;Client 也会声明它支持什么(比如是否支持 roots、sampling)。**任何一方没声明的能力,另一方不会去用。**所以"我明明实现了 Resource,客户端却不显示"往往不是实现问题,而是协商结果或客户端支持度问题。 2. **版本不匹配要有降级策略**。如果双方协议版本不一致,规范要求 Client 在响应里看到不匹配的版本时决定是否继续。**具体的版本号列表与降级规则随规范迭代,须以官方文档为准**,但工程上至少要保证"版本不兼容时给出可读的错误,而不是静默失败"。 3. **`initialize` 之后才允许业务请求**。在这之前的任何 `tools/call` 都是协议错误。自己写 Client 时特别容易踩:先握手,再拉清单,最后才调用。 ### Q:怎么注册能力、启动和调试? A:结论先行——**注册能力就是"在代码里声明清单 + 实现处理函数",SDK 会把两者绑定;启动就是选一个传输跑起来;调试则优先用官方 Inspector,而不是先接进真实客户端。** 主流 SDK 的抽象层次基本一致,分两层: - **低层 API**:显式实现 `list_tools` / `call_tool` 等处理器,返回协议对象(如 `Tool`、`TextContent`)。控制力最强,最贴近规范,但样板代码多。 - **高层 API(装饰器/FastMCP 风格)**:用 `@tool` / `@resource` / `@prompt` 装饰函数,**从函数签名和类型注解自动生成 inputSchema,从 docstring 自动生成 description**。这是绝大多数项目的起点。 > **版本提示**:官方 Python SDK 与社区同名 `fastmcp` 包在历史上存在"同名不同物"的混淆,导入路径与部分方法名在版本间发生过调整(如装饰器参数、`run()` 的 transport 取值)。本文示例按"官方 SDK + FastMCP 风格高层 API"书写,**具体导入路径、类名、参数名请结合你锁定的版本与官方文档确认**,不要照抄旧教程。 启动与调试的最小闭环: ```bash # ① 用官方 Inspector 打开调试界面(会读取你传入的启动命令) npx @modelcontextprotocol/inspector python order_server.py # ② 或直接用官方 SDK 提供的 CLI 入口(子命令名随版本可能变化) # python -m mcp run order_server.py # ③ 手工验证 stdio Server:把一行 JSON-RPC 打进去看响应 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python order_server.py ``` 调试顺序建议固定为:**Inspector 单测能力 → 看 stderr 日志 → 再接客户端**。原因很简单:接进客户端后,报错信息通常会被客户端吞掉大半,你看到的只是"工具调用失败"。 ## 三、动手写一个真正可用的 Server ### Q:用 Python SDK 写一个"查内部 API"的 Server,骨架长什么样? A:结论先行——**一个可用的 Server = 一个读工具(幂等、可重试)+ 一个检索类工具(带分页、有上限)+ 一处结构化错误约定 + 一处 stderr 日志。先把这四件事做对,再谈 Resources 和 Prompts。** 下面这段代码解决的问题是:让 Agent 能"按订单号查详情"和"按条件搜索订单",并且**在任何失败路径上都不抛异常给协议层,而是返回模型能理解的结构化结果**。示例调用的是内部 HTTP API;如果换成"查数据库",整体结构完全一致,只需把 HTTP 客户端换成一个**只读账号**的数据库连接,并同样加超时、分页上限与字段投影。 ```python # 文件:order_server.py # 依赖:官方 Python SDK(pip 包名 mcp,含 mcp.server.fastmcp.FastMCP)、httpx、pydantic # 说明:示例按"官方 SDK 的高层 FastMCP 风格 API"书写; # 导入路径、装饰器参数、run() 的 transport 取值需结合你锁定的 SDK 版本确认。 from __future__ import annotations import os import sys import logging from typing import Annotated, Any import httpx from pydantic import Field from mcp.server.fastmcp import FastMCP # 关键点 1:日志一律走 stderr。stdio 传输下 stdout 是协议通道,任何 print 都会污染协议流。 logging.basicConfig( level=logging.INFO, stream=sys.stderr, format="%(asctime)s %(levelname)s %(name)s %(message)s", ) log = logging.getLogger("order-server") API_BASE = os.environ["ORDER_API_BASE"] # 例:https://api.internal.example.com API_TOKEN = os.environ["ORDER_API_TOKEN"] # 由宿主注入,绝不写进代码或镜像 mcp = FastMCP("order-tools") # 这个名字会出现在客户端的 Server 列表里 READ_TIMEOUT = 8.0 MAX_PAGE_SIZE = 50 # 关键点 2:分页有硬上限,防止撑爆上下文 def _fail(code: str, message: str, *, retryable: bool = False, hint: str | None = None) -> dict: """统一的失败返回体:模型能读懂,且能据此决定是否换个参数重试。""" return {"ok": False, "error": {"code": code, "message": message, "retryable": retryable, "hint": hint}} @mcp.tool() async def query_order( order_id: Annotated[str, Field(description="订单号,形如 SO20260914001,字母数字,长度<=32")], ) -> dict: """按订单号查询单个订单的摘要信息(状态、金额、创建时间、买家昵称)。 只读且幂等,可以安全重试。查不到时返回 ok=false 与 code=NOT_FOUND,不要臆造订单。 """ try: async with httpx.AsyncClient(timeout=READ_TIMEOUT) as client: resp = await client.get( f"{API_BASE}/orders/{order_id}", headers={"Authorization": f"Bearer {API_TOKEN}"}, ) except httpx.TimeoutException: log.warning("query_order timeout order_id=%s", order_id) return _fail("TIMEOUT", "查询订单超时,可稍后重试", retryable=True) except httpx.HTTPError as exc: log.error("query_order transport error: %s", exc) return _fail("UPSTREAM_UNAVAILABLE", "订单服务暂时不可用", retryable=True) if resp.status_code == 404: return _fail("NOT_FOUND", f"订单 {order_id} 不存在", hint="请与用户确认订单号是否正确") if resp.status_code == 403: return _fail("FORBIDDEN", "当前凭证无权查询该订单") if resp.status_code >= 500: return _fail("UPSTREAM_ERROR", f"订单服务错误({resp.status_code})", retryable=True) raw = resp.json() # 关键点 3:只挑必要字段,不把上游原始报文整包返回(上游字段可能几十个且含敏感信息)。 return { "ok": True, "data": { "order_id": raw.get("id"), "status": raw.get("status"), "amount": raw.get("amount"), "currency": raw.get("currency", "CNY"), "created_at": raw.get("createdAt"), "buyer_nick": raw.get("buyer", {}).get("nick"), }, } @mcp.tool() async def search_orders( keyword: Annotated[str | None, Field(description="模糊关键词,匹配订单号或买家昵称")] = None, status: Annotated[str | None, Field(description="订单状态,如 PAID/SHIPPED/CLOSED")] = None, page: Annotated[int, Field(description="页码,从 1 开始", ge=1)] = 1, page_size: Annotated[int, Field(description="每页条数,默认 10,最大 50", ge=1, le=MAX_PAGE_SIZE)] = 10, ) -> dict: """按条件搜索订单,返回分页结果。只读操作。 结果只包含摘要字段;需要详情请用 query_order。若 has_more=true, 请用 page+1 继续翻页,不要一次要求超大 page_size。 """ params: dict[str, Any] = {"page": page, "pageSize": page_size} if keyword: params["q"] = keyword if status: params["status"] = status try: async with httpx.AsyncClient(timeout=READ_TIMEOUT) as client: resp = await client.get( f"{API_BASE}/orders", params=params, headers={"Authorization": f"Bearer {API_TOKEN}"}, ) except httpx.TimeoutException: return _fail("TIMEOUT", "搜索超时,可缩小条件或稍后重试", retryable=True) except httpx.HTTPError as exc: log.error("search_orders error: %s", exc) return _fail("UPSTREAM_UNAVAILABLE", "订单服务暂时不可用", retryable=True) # 关键点:4xx 与 5xx 要分开处理——前者重试无意义,后者才可退避重试。 if resp.status_code == 400: return _fail("INVALID_ARGUMENT", "查询条件不合法", hint="请减少过滤条件后重试") if resp.status_code >= 500: return _fail("UPSTREAM_ERROR", f"订单服务错误({resp.status_code})", retryable=True) body = resp.json() items = [ {"order_id": it.get("id"), "status": it.get("status"), "amount": it.get("amount"), "created_at": it.get("createdAt")} for it in body.get("items", []) ] total = body.get("total", len(items)) return { "ok": True, "data": {"items": items, "total": total}, "page": {"page": page, "page_size": page_size, "has_more": page * page_size < total}, } if __name__ == "__main__": # 关键点 4:传输方式由启动参数/环境决定,本地默认 stdio。 transport = os.environ.get("MCP_TRANSPORT", "stdio") log.info("starting order-tools server, transport=%s", transport) mcp.run(transport=transport) ``` 逐段解读: - **装饰器 + 类型注解 = 协议里的 inputSchema**。`Annotated[..., Field(description=...)]` 会把描述写进 schema 的 `description`,这是模型判断"参数该填什么"的主要依据。`ge`/`le` 会变成 `minimum`/`maximum`,**但不是所有客户端和模型都会严格遵守约束,服务端必须再校验一次**。 - **docstring 就是工具的 description**。它会连同参数描述一起被塞进模型的工具清单,所以它应当写"**做什么 + 什么时候用 + 只读还是有副作用 + 失败语义**",而不是"函数的实现说明"。 - **返回 `dict` 比返回裸字符串更好**。SDK 会把它序列化成文本内容块给模型;结构化字段能让模型稳定地判断 `ok`、`error.code`、`has_more`。**返回结构的具体能力(是否支持结构化内容块 `structuredContent`)随 SDK 版本演进,需结合实际版本确认。** - **异常不越过边界**。上面的写法是把可预期错误翻译成返回体;如果确实抛出异常,多数 SDK 会把它转成 `isError: true` 的内容返回,**但异常类型、是否附带 traceback、是否中断会话,各 SDK 行为不一,需结合版本确认**。生产上更推荐"能预期的错误用手写返回体,不可预期的用异常兜底"。 - **超时必须显式设置**。httpx 默认无超时或超时很长,一个卡住的上游会让整轮 Agent 对话停住。8 秒是一个可讨论的经验值,应按 P99 调整。 - **凭证从环境变量读**。宿主在启动 Server 时注入环境变量是最常见的做法;写死凭证、或把 token 明文打进镜像,是审计红线。 ### Q:工具设计有哪些工程要点(schema、返回值、错误、分页、超时)? A:结论先行——**工具设计的核心目标只有一个:让模型"看一眼就知道该不该用、该传什么、拿到什么、失败了怎么办"。** 围绕这个目标,有五条硬规则。 **(1)schema 描述:写给模型看** | 做法 | 反例 | 正例 | | --- | --- | --- | | 描述写清取值范围与格式 | `order_id: string` | `订单号,形如 SO20260914001,字母数字,<=32 位` | | 同义/别名要写进去 | `status: string` | `订单状态:PAID 已付款 / SHIPPED 已发货 / CLOSED 已关闭` | | 参数越少越好 | 12 个可选参数让模型自己组合 | 保留高频 3~5 个,其余拆分或给默认值 | | 用枚举而不是自由文本 | `type: string` | `enum: ["order","refund","invoice"]` | | 别让模型猜时间语义 | `date: string` | `日期,格式 YYYY-MM-DD;不传则默认最近 7 天` | **(2)返回值结构:小而稳** - **只放必要字段**。上游返回 40 个字段,工具只暴露 6 个。多余字段既浪费 Token,又可能把手机号、身份证等敏感信息带进上下文。 - **给结果设体积上限**。经验做法:单次工具返回控制在几百到几千 Token 量级;超过就分页或摘要。**具体阈值取决于模型上下文窗口与业务容忍度,需实测**。 - **结构固定**。成功时 `{ok, data}`,失败时 `{ok:false, error:{code,message,retryable,hint}}`。固定的形状让模型不用每次重新猜格式。 - **别把大对象塞进一条工具结果**。10 万行日志应该由工具落到一个临时文件/对象存储,然后**在上下文里只返回一个引用(路径或 ID)+ 摘要 + 怎么读的命令**。这也是"只留引用"原则在工具层的体现。 **(3)错误约定:可判别、可决策** ```json { "ok": false, "error": { "code": "INVALID_ARGUMENT", "message": "status 只接受 PAID/SHIPPED/CLOSED", "retryable": false, "hint": "请改用合法状态值,或省略 status 查询全部" } } ``` 错误设计的三个原则: - **分类**:`INVALID_ARGUMENT`(模型改参数即可)、`NOT_FOUND`(换查询)、`FORBIDDEN`(不要重试,告诉用户)、`TIMEOUT`/`UPSTREAM_UNAVAILABLE`(可退避重试)。**没有分类的错误,模型只能瞎重试。** - **可重试要显式标注**。`retryable: true` 是给编排层看的,可以在 Agent 循环里做退避。 - **错误信息里写"下一步怎么做"**,而不只是"失败了"。模型对行动建议的响应远好于对错误码的响应。 **(4)分页:必须有上限,且要告诉模型怎么翻** - 服务端强制 `page_size` 上限(示例里的 `le=MAX_PAGE_SIZE`),别信模型会自己收敛。 - 返回体里带 `has_more` 和当前页码,让模型知道"还有更多"。 - 返回 `total` 时要谨慎:某些上游算 total 很贵,可能触发慢查询。**如果 total 不可靠,宁可只返回 has_more。** - 列表类工具最好再给一个"聚合/统计"工具(如 `count_orders`),因为很多问题的答案其实只需要数字,不需要 500 行明细。 **(5)超时与重试** - **读工具**:短超时(几秒)+ 有限重试 + 幂等。 - **写工具**:默认不自动重试;如果需要重试,必须带**幂等键(idempotency key)**,由调用方生成并在上游去重。 - **不要在工具内部做长时间阻塞**。长任务应该返回"任务已提交 + 任务 ID",再提供一个查询任务的工具。这样模型不会卡在一次调用里。 ### Q:Resources 和 Prompts 怎么写?什么时候值得写? A:结论先行——**Resources 适合"稳定、只读、可被引用"的背景资料,Prompts 适合"人工发起、参数固定"的高频工作流;两者都是锦上添花,不要为了"三种能力都用上"而硬写。** Resources 的代码形态(URI 寻址 + 只读读取): ```python # 解决的问题:把"订单表结构说明"作为可引用资料暴露出去,让宿主/模型按 URI 取用。 # 说明:resource URI 的 scheme、模板语法与装饰器写法随 SDK 版本略有差异,需核对官方文档。 @mcp.resource("schema://orders/table") def orders_schema() -> str: """订单主表 order_main 的结构说明(只读)。""" return ( "表 order_main:\n" " id string 订单号,主键\n" " status string PAID/SHIPPED/CLOSED\n" " amount decimal 金额,单位元\n" " created_at datetime 创建时间(UTC+8)\n" " buyer_id string 买家 ID\n" "查询示例:SELECT id, status, amount FROM order_main WHERE id = ?\n" ) @mcp.resource("order://{order_id}/summary") def order_summary(order_id: str) -> str: """按订单号读取订单摘要(URI 模板参数)。""" # 注意:Resource 也是"被读取就执行",同样要限权、限流、限超时。 return f"订单 {order_id} 的摘要(示例省略真实取值来源)" ``` Resources 的适用与不适用: - **适合**:表结构/字段字典、接口文档、配置说明、固定词典、最近一次部署记录。特点是**变更是低频的,且内容本身就是上下文**。 - **不适合**:需要按业务条件动态检索的数据(那是 Tool 的活);需要写操作的东西(Resource 是只读语义);超大文档整篇塞入(应该自己做切片,暴露多个 URI,或干脆用检索工具)。 - **一个实战建议**:Resource 的 URI 设计要"可被发现"。如果客户端不会自动列出资源,就在 System Prompt 或某个 Tool 的返回里明确写出可用 URI 前缀,否则模型根本不知道它存在。 Prompts 的代码形态(模板 + 参数): ```python # 解决的问题:把"订单异常归因"这个高频人工工作流固化成模板,用户在界面上选一次即可。 @mcp.prompt() def diagnose_order(order_id: str, symptom: str = "用户反馈金额不对") -> str: """生成"订单异常归因"的分析提示词。""" return ( f"请对订单 {order_id} 做异常归因分析。\n" f"用户描述的现象:{symptom}\n\n" "要求:\n" "1. 先用 query_order 拉取订单摘要,再用 search_orders 拉取该买家近期订单做对比;\n" "2. 只基于工具返回的数据下结论,数据不足就明确说缺哪一项;\n" "3. 输出结构:现象 → 证据(引用字段值)→ 可能原因(按可能性排序)→ 建议动作。" ) ``` Prompts 的价值在于**把"提示词工程"从散落在各处的复制粘贴,变成 Server 侧可版本化的资产**。注意两点:一是它返回的仍然只是文本,最终解释权在宿主;二是**参数要少而明确**,参数一多,用户体验还不如手写。 ## 四、接到客户端与生产化 ### Q:怎么把 Server 接进客户端?多 Server 怎么管? A:结论先行——**接入就是写一份"启动命令 + 参数 + 环境变量"的配置,客户端负责把它拉起来并完成握手;多 Server 的管理重点是"命名空间、工具去重、性能隔离、故障隔离"四件事。** 配置文件的核心结构(不同客户端的文件名与字段名不同,这里给出通用形态,**实际键名需按客户端文档确认**): ```json { "mcpServers": { "order-tools": { "command": "python", "args": ["/opt/mcp/order_server.py"], "env": { "ORDER_API_BASE": "https://api.internal.example.com", "ORDER_API_TOKEN": "${ORDER_API_TOKEN}" } }, "docs-search": { "command": "npx", "args": ["-y", "@acme/mcp-docs-search"], "env": { "DOCS_INDEX": "team-wiki" } }, "remote-analytics": { "type": "http", "url": "https://mcp.internal.example.com/analytics", "headers": { "Authorization": "Bearer ${MCP_ANALYTICS_TOKEN}" } } } } ``` 要点: - **`${VAR}` 展开**可以让密钥不落配置文件,但**它只是"不写在文件里",并不等于安全**——宿主进程环境里的值仍是明文。生产上更稳的是走密钥管理/短期凭证。**是否支持 `${}` 及展开时机需按客户端确认。** - **配置文件是"每客户端一份"**。同一个 Server 在 IDE、桌面助手、自研 Agent 里要各配一次。团队里应当把这份配置作为代码管理,避免"我的能用你的不能用"。 - **HTTP 类型的 Server 要区分 `url` 与鉴权头**,并确认客户端支持 Streamable HTTP(老客户端可能只支持 stdio 或旧 SSE)。 多 Server 管理的四个工程问题: | 问题 | 表现 | 处理办法 | | --- | --- | --- | | 工具重名 | 两个 Server 都提供 `search` | 在 Server 侧加业务前缀(`order_search`),不要指望宿主帮你改名 | | 工具数量爆炸 | 10 个 Server 各 20 个工具 = 200 个工具全塞进 System Prompt | 按场景拆 Host/会话,或减少暴露面;**工具数越多,选错率越高、Token 越贵** | | 启动慢拖垮体验 | 某个 Server 用 npx 首次下载依赖,启动 30 秒 | 预热/本地缓存依赖,healthcheck 超时要短 | | 单点故障牵连全局 | 一个 Server 崩溃导致宿主整体卡住 | 关注宿主的隔离行为;对远程 Server 做独立限流与降级 | ### Q:生产化要解决哪些问题(鉴权、权限、幂等、限流、可观测、版本)? A:结论先行——**MCP Server 本质就是一个"暴露给不可信调用方(模型 + 用户输入)的内部服务",所以要把后端服务那一整套安全与稳定性手段搬过来,唯一的新变量是"调用参数由模型生成,因此必须当作不可信输入"。** **(1)鉴权与凭证** - stdio:靠"进程由谁拉起 + 本机权限"来隔离,凭证走环境变量或本机密钥文件,**不要写在代码/镜像/日志里**。 - HTTP:走标准 HTTP 鉴权。规范方向是基于 OAuth 的授权模型(资源服务器 + 授权服务器),**细节仍在演进,需结合规范版本与官方文档确认**;在企业内部更常见的替代是走 API 网关做统一的 mTLS/JWT 校验。 - **凭证的最小生命周期**:优先短期 Token + 自动轮换,而不是长期静态 Key。 - 日志中一律对 Token、手机号、身份证做脱敏(`Bearer ***`)。 **(2)权限最小化** - **数据库账号只给只读**,且限制到具体库/表/列;别让 `run_sql` 工具用应用主账号。 - **禁止字符串拼接 SQL**。模型生成的 SQL 一律当不可信输入:只允许单条 SELECT、强制加 LIMIT、拒绝 DDL/DML(除非有独立的高危工具和审批通道)。 - 每个工具对应一个明确权限域(订单只读 / 工单读写 / 财务只读),**不要做一个万能的 `call_internal_api(path, method, body)`**——那等于把整个内网 API 网关交给模型。 - 高危操作(退款、删除、发版)默认"两步走":工具只做检查与生成预案,实际执行需要人工确认(Human-in-the-loop)。 **(3)幂等与副作用** - 读工具天然幂等,放心重试。 - 写工具必须显式设计幂等:客户端传 `idempotency_key`,服务端按 key 去重;或把"创建类"操作做成"先查后建 + 唯一约束兜底"。 - **工具的 description 里必须写清楚"这个操作会改数据"**,否则模型会当成查询反复调用。这是最容易被忽视的一条。 **(4)限流与配额** - 按"工具 × 调用方"限流,而不是只按 IP。模型可能在一轮里连续调同一个工具十几次。 - 给昂贵的工具(全表扫描、外部付费 API)设独立配额与熔断。 - **反循环保护**:同一工具、同一参数在一轮内重复调用 N 次就拒绝并返回提示,避免模型陷入死循环刷爆成本。 **(5)日志与可观测** - 结构化日志:`request_id`、`tool_name`、参数摘要(脱敏)、耗时、上游状态码、结果大小、是否报错。**不要记录完整返回体**,它会带来体积与合规问题。 - 指标:调用量、错误率(按 error.code 分)、P99 耗时、单次返回 Token 估算量。 - 链路:把 `request_id` 透传到上游服务,才能做端到端排障。 - **stdio 下日志只能进 stderr**,所以要把 stderr 收集进你的日志系统,否则线上等于没有日志。 **(6)版本与向后兼容** - **能力只增不减**:删工具、改工具名、把必填参数变成必填的另一套语义,都是破坏性变更。 - **优先加可选参数**,而不是改现有参数含义;语义要变就新增一个工具名(`search_orders_v2`),旧工具保留并标注 deprecated。 - 在 `serverInfo.version` 里维护版本号,并在 Tools 列表中通过描述告知"推荐用法"。 - **协议版本也要跟**:Server 声明支持的协议版本会随 SDK 升级变化,升级前在测试环境用真实客户端回归一遍握手。 ### Q:连不上、调不通,怎么排查? A:结论先行——**"连不上"九成是三类问题:进程没起来(依赖/路径/权限)、stdout 被污染(协议流被破坏)、握手或能力协商失败(版本/配置/客户端不支持)。排查顺序应当是"先证明进程能跑,再证明协议能通,最后才怀疑客户端"。** 排查清单(按顺序执行): ```bash # 第 1 步:手工启动,确认进程本身不报错(stderr 会打印日志) python order_server.py # 第 2 步:确认依赖与环境变量都齐(缺 ORDER_API_TOKEN 之类的必填项会直接崩) python -c "import mcp, httpx, pydantic; print('deps ok')" # 第 3 步:验证 stdio 协议能通——打一行 tools/list 进去,看是否只有一行合法 JSON 出来 printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python order_server.py # 如果输出里混入了任何非 JSON 的行(print 调试、库的 banner、进度条),就是 stdout 被污染。 # 第 4 步:用 Inspector 走一遍完整握手(它会明确告诉你卡在哪一步) npx @modelcontextprotocol/inspector python order_server.py ``` 对应到症状的定位表: | 症状 | 最可能的原因 | 处理 | | --- | --- | --- | | 客户端显示 Server 启动失败/立刻退出 | 依赖缺失、脚本路径写错、必填环境变量为空 | 手工跑一次,看 stderr 首行报错 | | 进程活着但客户端报"解析消息失败" | stdout 被污染(print/logging 配错流) | 把所有输出改到 stderr;检查第三方库是否往 stdout 写 | | 连接建立后没有工具列表 | 握手失败或能力未声明;客户端不支持该能力 | 用 Inspector 看 `initialize` 往返;核对协议版本与能力声明 | | 工具出现在列表但调用总报 schema 错误 | inputSchema 生成异常(类型注解/默认值写法不被支持) | 打印实际 `tools/list` 输出,核对 schema 是否符合预期 | | 调用超时但服务端日志显示上游正常 | 工具内部没有设超时,或返回体过大导致写回阻塞 | 显式设置超时;限制返回体积,大结果改写引用 | | 只有某些机器连不上 | 路径/解释器/权限差异、企业代理拦截远程 Server | 统一用绝对路径与虚拟环境;远程走网关并确认代理白名单 | | 远程 Server 偶发 401/会话失效 | 会话 ID 或 Token 过期,多实例无粘性 | 检查会话粘性/共享存储;凭证自动刷新 | 一句话总结排查方法论:**把"宿主 → Client → 传输 → Server 进程 → 上游 API"五段拆开,逐段用最小可复现命令验证,永远不要在"整条链一起看"的状态下猜。** ## 五、工程实践与踩坑 以下是最常见、也最"贵"的一批坑,按代价从高到低排: 1. **工具描述太差,模型永远不调或永远调错。** 症状:明明有工具,模型却说"我没有查询订单的能力",或者把订单号填成了用户名。 处理:description 写"做什么 + 何时用 + 参数格式举例 + 与相邻工具的区别";参数描述写取值范围;必要时在描述里给出 1 个正例。 2. **返回体过大,一次性撑爆上下文。** 症状:一次工具调用后对话突然变慢/变贵/开始丢信息,甚至直接超窗。 处理:服务端限 `page_size`、限字段数、限字符数;大结果落盘/落对象存储,上下文中只回引用 + 摘要 + 读取方式。 3. **错误直接抛异常,模型只看到"调用失败"。** 症状:模型开始胡乱重试或编造结果。 处理:可预期错误翻译成结构化返回体(code/message/retryable/hint),异常只作兜底。 4. **凭证泄漏。** 症状:Token 硬编码进代码、打进镜像、写进日志、出现在错误信息里被模型原样复述给用户。 处理:环境变量/密钥管理注入;日志与错误信息统一脱敏;**错误信息永远不要回显请求头**。 5. **传输方式选错。** 症状:本是团队共享的能力却做成 stdio,导致每人一个副本、配置散落、无法统一限流;或本机小工具硬做 HTTP,白白引入鉴权与会话复杂度。 处理:本地个人用 stdio,团队共享/远程用 Streamable HTTP。 6. **工具爆炸导致选择困难。** 症状:一个 Host 挂了几十个 Server、几百个工具,模型选错工具、Token 暴涨。 处理:按场景拆分 Host;Server 侧只暴露必要工具;给工具加业务前缀避免重名。 7. **写操作没有幂等键。** 症状:超时重试导致重复创建工单/重复退款。 处理:幂等键 + 上游去重 + 唯一约束;错误地"自动重试写操作"是重大事故源。 8. **`run_sql` 类工具没有防线。** 症状:模型生成多语句、DDL、无 LIMIT 全表扫描,拖垮数据库。 处理:只读账号 + 单语句解析 + 强制 LIMIT + 语句白名单 + 超时 + 独立限流。 9. **无版本策略,一次升级全挂。** 症状:改了工具名/参数后,旧配置的客户端全线报错。 处理:只增不改;破坏性变更走新工具名 + 双跑期 + 弃用标注。 10. **stdout 打印调试信息。** 症状:本地偶然好用,进客户端就"连不上"。 处理:所有日志走 stderr;CI 里加一条"stdio 冒烟测试",把 `tools/list` 往返纳入自动化。 11. **不区分"读"和"写"的描述。** 症状:模型把有副作用的工具当查询反复调用。 处理:description 首句明确"只读"或"会修改数据",并在高风险工具上加人工确认。 12. **忽略 Session/连接生命周期。** 症状:HTTP 传输下会话不粘、实例扩容后状态丢失。 处理:把会话状态外置(Redis 等),或者干脆设计成无状态 Server(推荐);本地 stdio 注意子进程随宿主退出的清理。 ## 小结 - MCP 是**三段式**:Host 管交互、Client 管单条连接、Server 管能力;你要写的是 Server。 - 三种能力按**触发方**选:Tools 模型触发(可能有副作用)、Resources 应用触发(只读资料)、Prompts 用户触发(工作流模板)。 - 开发流程是固定的:**选传输 → 握手协商 → 注册能力(清单+实现)→ 启动 → 用 Inspector 调试 → 接客户端**。 - 传输选型的唯一标准:**宿主的子进程用 stdio,独立部署用 Streamable HTTP**;stdio 下 stdout 是协议通道,日志必须走 stderr。 - 工具设计五要点:**schema 描述给模型看、返回值小而稳、错误可分类可决策、分页有硬上限、超时显式设置**。 - 生产化是"后端服务那套 + 一个新变量":新变量是"参数由模型生成,一律不可信";其余靠鉴权、最小权限、幂等、限流、可观测、版本兼容来守。 - 排查方法论:**先证明进程能跑,再证明协议能通,最后才怀疑客户端**,逐段用最小命令验证。 - 全文涉及的 SDK 类名、方法名、装饰器参数、协议版本号与鉴权细节**都处于演进中**,落地时必须以你锁定的 SDK 版本与官方文档为准,不要照抄任何教程(包括本文)中的代码细节。 ## 思考题 1. 你的团队有一个"只读的用户画像查询服务",用户是本机 IDE 里的 Agent。选 stdio 还是 Streamable HTTP?请说明理由,并写出接入配置的关键字段。 2. 一个 `search_logs` 工具可能返回 50 万行日志,请设计它的返回结构与分页策略,说明如何避免撑爆上下文,同时保证模型能拿到它真正需要的那几行。 3. 你在 `tools/list` 里同时暴露了 `get_order`(只读)和 `cancel_order`(写)。请分别写出它们的 description 首句,并说明为什么不能只写"订单相关操作"。 4. 某个 HTTP 类型的 Server 在多实例部署后出现"偶发 401 / 会话丢失",请给出至少三种可能的根因和验证方法。 5. 如果宿主客户端不支持 Resources 自动注入,你设计的关键资料要如何让模型知道并使用?请给出至少两种兜底方案。 6. 协议版本升级后,你的 Server 在新客户端上握手失败,旧客户端正常。请写出你的排查步骤与回归验证清单。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入