AI Agent / 系统课时
暴露 MCP 工具
暴露 MCP 工具
本节把一个普通 Python 函数变成 MCP 工具,并让客户端能够发现它的名称、参数结构和用途,再通过统一的工具调用完成参数校验与执行。完成后,你会知道工具定义中哪些信息会直接影响 Agent 是否能正确选择和调用它。
学习目标
- 使用 MCPServer 把本地函数注册为可发现工具
- 区分结构校验、业务校验与函数执行
- 通过工具清单和调用结果验证暴露是否正确
工具暴露的核心链路
MCP 工具不是“把函数名发给模型”这么简单。服务端需要公开工具元数据,客户端先获取工具清单,再把名称、描述和输入结构提供给 Agent;Agent 决定调用后,客户端把参数送回 MCP 服务端,由服务端完成校验并执行本地函数。

工具的输入结构通常由函数签名和类型标注派生。类型不匹配属于结构问题,应尽量在进入业务逻辑前被拒绝;例如“数量必须大于 0”这类跨字段或业务规则,仍应在函数内部显式检查。
注册一个可调用工具
把下面的服务保存为 orders_server.py,放在上一课 probe.py 所在目录。沿用 Python SDK 2.3.0。金额用整数分保存,避免二进制浮点舍入。
from typing import Annotated
from mcp.server.mcpserver import MCPServer
from pydantic import Field
server = MCPServer("order-tools")
@server.tool()
def order_total(
unit_cents: Annotated[int, Field(strict=True, ge=0, le=10_000_000)],
quantity: Annotated[int, Field(strict=True, gt=0, le=10_000)],
) -> int:
"""计算单价与数量的乘积,输入和输出金额都以分计。"""
return unit_cents * quantity
if __name__ == "__main__":
server.run(transport="stdio")python probe.py orders_server.py --tool order_total --arguments '{"unit_cents":1990,"quantity":3}'列表应包含 order_total,调用输出 tool_error: False 和 text: 5970。把数量改成 0,客户端应看到工具失败。参数类型、范围和单位同时写进工具定义,函数仍应依据实际业务校验请求人是否可以访问或修改相应订单。
让工具容易被正确调用
工具能注册成功,不代表 Agent 就会用对。名称应表达动作,描述应说明适用场景,参数名要避免缩写;不要把多个完全不同的业务动作塞进一个“万能工具”,否则模型很难稳定选择参数和调用时机。
参数校验最好分两层:JSON Schema 或 SDK 负责检查类型、必填字段等结构约束,函数内部负责库存不能为负、用户是否有权限、订单状态能否迁移等业务约束。即使调用来自模型,也不能跳过后端原本需要的权限和一致性检查。
验证发现与执行
验证时不要只看“服务能启动”。先确认客户端能够列出工具及参数结构,再用一组合法参数发起调用,最后补一组非法参数检查失败是否可控。对本例而言,1990 分乘以 3 得到 5970 分。数量 0、浮点数或字符串都应作为不合法参数处理。
真正可用的 MCP 工具需要同时满足三个条件:客户端找得到、Agent 看得懂、服务端执行得安全。把这三个条件分别验证,比只测试本地函数本身更接近真实 Agent 运行环境。