结论先行:MCP(Model Context Protocol)是一个标准化协议,让外部系统能力以"工具/资源/提示词"三种原语暴露给模型,本质是给模型用的 RPC 框架。写一个最小 server 只要几十行——官方 Python SDK 的 FastMCP 用装饰器就能把函数变成工具。真正的难点不在协议,在工具设计:粗粒度、返回精简、描述写给模型看。
协议一分钟
MCP 走 JSON-RPC 2.0,最常见的传输是 stdio:harness 把 server 作为子进程拉起,通过 stdin/stdout 通信,server 生命周期由宿主管理。另有一种 Streamable HTTP 传输用于远程部署。stdio 适合个人与团队本机场景:零部署、随配置文件分发、凭据经环境变量注入不落盘;HTTP 适合 server 需要被多人共享、或背后连着内网服务的场景,代价是要自己管认证、限流和发布。安全边界也要想清楚:stdio 模式下 server 进程继承宿主的凭据与文件权限,它能触达的范围就是运行者的权限范围,所以内部 server 同样要按最小权限原则设计——只给它业务库的只读账号,需要写操作时单独申请。三类原语:
- Tools:模型主动调用的函数(类似 POST,有副作用,由模型决定何时用);
- Resources:可读取的数据(类似 GET,由应用侧控制何时读);
- Prompts:预置的提示词模板。
90% 的场景只需要 Tools。
最小实现:查运单状态的 MCP Server
用官方 Python SDK(pip install "mcp[cli]"),一个能跑的 server:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("order-query")
@mcp.tool()
def query_order_status(order_id: str) -> str:
"""按运单号查询物流状态。
Args:
order_id: 运单号,形如 FY2026090001
"""
order = order_service.find(order_id) # 你的业务逻辑
if order is None:
return f"未找到运单 {order_id},请确认单号格式"
return (f"运单 {order_id}: 状态={order.status}, "
f"司机={order.driver_name}, 预计送达={order.eta}")
if __name__ == "__main__":
mcp.run(transport="stdio")
客户端配置(以 Claude Code 为例):
{
"mcpServers": {
"order-query": {
"command": "python3",
"args": ["/srv/mcp/order_query/server.py"],
"env": { "ORDER_API_TOKEN": "..." }
}
}
}
调试用官方的 MCP Inspector(mcp dev server.py),可以在 UI 里列出工具、手动调用、看原始报文,比在 Agent 里盲调高效得多。上线前建议把每个工具都手动调一遍正常路径和至少一种失败路径——工具在 Inspector 里的行为和在 Agent 里的行为是一致的,因为协议层相同。
工具设计的四条经验
一、粗粒度。 不要把 REST 接口一对一包成工具(getOrder、getDriver、getRoute……),模型要在它们之间做多次调用才能拼出答案。按"任务"设计工具:query_order_status 一次返回模型可能需要的关联信息。判断标准:模型完成一个常见任务需要调几次你的工具?超过三次就该合并。
二、返回精简。 不要把整个 JSON 塞回去。对比错误写法与正确写法:
# 错误写法:把 ORM 对象整个序列化扔回去
@mcp.tool()
def query_order_bad(order_id: str) -> str:
order = order_service.find(order_id)
return json.dumps(order.__dict__, default=str)
# 模型要在一屏字段里翻找状态;内部 ID、分页元数据、时间戳全是噪音,
# 每次调用都白白消耗几百上千 token
# 正确写法:按"给模型读"组织,只留决策需要的字段
@mcp.tool()
def query_order_status(order_id: str) -> str:
order = order_service.find(order_id)
if order is None:
return f"未找到运单 {order_id},请确认单号格式(形如 FY2026090001)"
return (f"状态={order.status}; 异常标记={order.abnormal_flag or '无'}; "
f"预计送达={order.eta}; 详情可用 order_id={order_id} 查询轨迹")
三、描述写给模型,不是写给程序员。 docstring 是模型的唯一使用依据。参数含义、格式示例、错误情况怎么处理,都要写进去。上面的例子里"形如 FY2026090001"这一句,能显著降低模型传错格式的概率。
四、错误要可恢复。 “未找到运单,请确认单号格式"这样的返回让模型知道怎么修正;抛异常或者返回裸的 500 则会让模型卡住。把可预期的失败设计成正常返回值,是 MCP server 和普通 API 网关最大的区别。
两条补充纪律写在实现规范的末尾。一是副作用的幂等与标注:有写操作的工具要在描述里明说"本操作会产生真实副作用”(下单、退款、改配置),能幂等的做成幂等(同样的入参重复调用不产生二次效果),模型在循环里重试是常态,不幂等的写工具迟早造成重复操作事故。二是工具的配置化开关:每个工具都能通过 harness 配置启用或停用,出问题的工具可以单独下线而不必重新发布 server——这和权限白名单是两道闸,一个管"注册了没有",一个管"注册了但不许这个项目用"。
Resources 和 Prompts 什么时候用
Tools 之外的两类原语按需选用,三者的边界整理如下:
| 原语 | 类比 | 谁决定触发 | 典型场景 |
|---|---|---|---|
| Tools | 有副作用的 POST | 模型自主选择 | 查询业务状态、执行操作 |
| Resources | 只读的 GET | 应用侧控制 | IDE 侧栏展示数据、上下文附加 |
| Prompts | 模板函数 | 用户显式调用 | 排查 SOP、code review 清单 |
Resources 适合"数据在那躺着,应用决定何时读"的场景,比如让 IDE 侧栏展示运单详情;Prompts 适合把团队的标准化流程(排查 SOP、code review 清单)做成可选模板,由用户显式触发。拿不准就先用 Tools——它是三类里唯一能被模型自主发现和调用的,覆盖面最广。
与 Agent 循环的关系
MCP server 注册的工具和内置工具走同一条路:进 schema、被模型选择、由 harness 执行、结果进上下文。所以前几篇讲的权限模型(工具调用白名单)和上下文管理(输出截断)对 MCP 工具同样生效——这是协议标准化带来的工程红利:能力可以来自任何团队,治理仍然收在 harness 一处。
这也反过来对 MCP server 提了要求:工具数要克制(每个工具的 schema 都占每轮的上下文底座),返回体要可控(进截断闸门的内容越精简,有效信息密度越高)。一个团队内部治理经验:MCP 工具上线前过一道"工具评审"——名字是否表意、描述是否写了格式示例与错误处理、返回是否精简、粒度是否按任务合并过。这四问挡掉的问题,比上线后调试省下的时间多得多。MCP 工具和内置工具还有一个行为差异值得知道:内置工具的实现与 harness 同生命周期,出问题改 harness 就行;MCP server 是独立进程,崩溃、卡死、输出流错乱都要 harness 侧有兜底(进程重启、调用超时、坏输出丢弃),选 harness 时这一点值得列入考察项。
实战场景
一个物流团队的实战过程:第一个版本的 MCP server 把三个内部 REST 接口一对一包成了 getOrder、getDriver、getRoute 三个工具。模型查一次运单异常要连调三个工具再自己拼装,还经常拼错顺序——先查轨迹再查状态,拿到过期数据。按"粗粒度"原则重构成 query_order_status 一个工具后,单次查询一次调用完成;返回体从原始 JSON(含内部 ID、创建时间戳、分页字段等十几个字段)改写成三行紧凑文本,单次调用进入上下文的内容量明显下降(定性观察,具体 token 数字与接口形态相关,此处不给统一值)。团队随后把这套经验固化成 server 脚手架:描述模板里强制带格式示例和错误处理说明,异常统一翻译成"可恢复的自然语言返回"。三个月里这个 server 被三个不同团队复用,没有一次因为协议问题返工——出问题的从来不是协议,是工具设计。
检查清单
- 工具按任务设计而非按 REST 接口一对一包装,常见任务调用不超过三次
- 返回体按"给模型读"组织成紧凑文本,剔除内部 ID、分页元数据等噪音
- docstring 含参数格式示例(如"形如 FY2026090001")和错误情况处理方式
- 可预期的失败返回可恢复的自然语言,不抛裸异常或 500
- 上线前在 MCP Inspector 里手动调通正常路径与至少一种失败路径
- 工具数量克制,schema 总量考虑每轮上下文底座成本
- 接入 harness 的权限白名单与输出截断,治理收在 harness 一处
- 大结果支持分页参数,避免单次返回撑爆上下文