给 AI 助手接内部系统:MCP 工具的粒度与权限边界
给它一个万能接口,十次里错三次,还敢自己去调写接口。改成动作级工具、白名单参数、默认 dry run 之后,才敢放进日常排查流程里用。
让 AI 助手帮忙查线上问题,最省事的做法是给它一个能执行命令的工具,然后告诉它"需要什么自己跑"。我这么干过两天,就把它关了:它会用 curl 拼出一个带管理端 token 的请求,把结果原样贴出来;也会在没确认的情况下尝试 POST 一个修改接口。
问题不在模型的能力,在我给它的东西太宽。后来改成自己写 MCP 服务,把每个能力收敛成一个明确的工具,限制参数、限制返回、限制权限,才真正能用起来。
一、先想清楚为什么不直接给它一个 shell
"给个终端"这条路看起来最灵活,实际上把所有风险都留在了最后一步。几个具体的例子:
- 它会读到
.env,然后把里面的连接串打进回答里; - 它会把一次查询写成
select * from orders,几百兆结果直接灌进上下文; - 它无法判断"这个接口是只读还是写",
GET和DELETE在它眼里只是两个 URL。
而 MCP 工具的价值恰恰是把"能做什么"预先定义好。模型只能在你给的几个动作里选,选错的代价被限制住了。
二、工具粒度:一个动作一个工具,不要包成万能入口
第一版我写了一个 query_api(path, method, body) 的工具,想着"这样什么都能调"。结果模型每次都要自己拼路径,十次里错三次,还有一次把查询参数写进了 body。
改成按业务动作拆分之后,调用成功率立刻上来了:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("ops-tools")
@mcp.tool()
def order_status(order_no: str) -> dict:
"""按订单号查询订单当前状态。
Args:
order_no: 订单号,形如 OD 加 12 位数字,例如 OD202611160001。
仅支持精确查询,不支持模糊匹配。
"""
...
return {"order_no": order_no, "status": "PAID", "updated_at": "2026-11-16 09:12:03"}
@mcp.tool()
def order_timeline(order_no: str, limit: int = 20) -> list:
"""查询订单的状态流转记录,按时间倒序。
Args:
order_no: 订单号,精确匹配。
limit: 返回条数,1–50,默认 20。
"""
limit = max(1, min(int(limit), 50))
...
三个细节值得说:
- docstring 就是给模型看的说明书,写清参数格式、边界、是否支持模糊匹配。写"查询订单"这种描述,模型只能靠猜。
- 参数是强类型的,不要用
**kwargs或者一个大 JSON 字符串。类型明确,模型填错的机会就少。 - 默认值和上限写在函数签名里,让它在不传参数时也有安全行为。
| 粒度 | 例子 | 问题 |
|---|---|---|
| 万能入口 | query_api(path, method, body) |
模型要自己拼协议,错误率高 |
| 资源级 | get_order(id) / list_orders(status) |
可用,但一个工具承担多种语义 |
| 动作级 | order_status(order_no) / order_timeline(order_no) |
推荐,语义单一,参数可校验 |
三、权限:只读优先,写操作单独隔离
我们的原则是:默认只读,写操作单独一个服务、单独一套凭据、默认关闭。
只读工具也要做参数约束,因为"只读"不等于"无害"。一个 list_orders 如果不限制条数和时间范围,模型很容易拉出几十万行,然后上下文爆掉,或者把大量客户信息带到外部接口。
from datetime import date, timedelta
@mcp.tool()
def list_orders(status: str, days: int = 7, limit: int = 50) -> list:
"""按状态列出最近若干天的订单,最多 50 条。
Args:
status: 只能是 PAID / SHIPPED / CLOSED 之一。
days: 回溯天数,1–30。
limit: 返回条数,1–50。
"""
if status not in {"PAID", "SHIPPED", "CLOSED"}:
raise ValueError("status must be one of PAID/SHIPPED/CLOSED")
days = max(1, min(int(days), 30))
limit = max(1, min(int(limit), 50))
since = date.today() - timedelta(days=days)
...
白名单(而不是黑名单)是关键。枚举值写死在代码里,模型没法构造出意料之外的查询。
写操作那边我们做了三层隔离:
- 独立进程、独立凭据,凭据只有目标接口的写权限,没有库权限;
- 工具默认不注册,需要时通过环境变量打开,会话结束就关;
- 所有写操作工具必须带
dry_run参数,默认True,真写要显式传False。
@mcp.tool()
def close_order(order_no: str, reason: str, dry_run: bool = True) -> dict:
"""关闭订单。默认只做校验不落库,dry_run=False 才真正执行。"""
...
if dry_run:
return {"dry_run": True, "would_close": order_no, "reason": reason}
...
dry_run 这个参数救过我们一次:模型想"帮忙"把一批异常订单关掉,先跑了一遍 dry run,返回里列出了 37 个单号,人一看就发现里面有一半是测试数据,及时拦住了。
四、返回值的形状,决定它会不会用错
工具返回什么,比工具做什么更容易被忽略。第一版我把接口原始 JSON 直接返回,字段名是 st、cd、dt 这种缩写,模型经常把 cd 当状态码解释。
现在固定三条:
- 字段名写全:
status而不是st,created_at而不是ct; - 带单位:金额返回
{"amount": 128.50, "currency": "CNY"},不要只给一个数字; - 大结果截断并说明:超过 50 条时返回
{"items": [...], "truncated": true, "total": 1820},让模型知道"这不是全部",而不是以为查到的就是全部。
{
"order_no": "OD202611160001",
"status": "PAID",
"amount": {"value": 128.5, "currency": "CNY"},
"created_at": "2026-11-16T09:12:03+08:00",
"items_truncated": false
}
时间统一带时区。不带时区的时间,模型会按自己的假设去算差值,算出来的"已经过了 8 小时"可能是错的。
五、可观测性:每次调用记四个字段
工具被调用时,模型不会告诉你它想干什么,只能从调用记录里推断。我们每次记四个字段:
import json, time, logging
def audit(tool: str, args: dict, ok: bool, cost_ms: int):
logging.info(json.dumps({
"tool": tool,
"args": {k: v for k, v in args.items() if k not in {"token", "password"}},
"ok": ok,
"cost_ms": cost_ms,
"ts": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
}, ensure_ascii=False))
参数要脱敏后再记,这一点很容易漏。日志本身也是数据泄露面,尤其当工具参数里带着手机号、证件号的时候。
四个字段的用途:tool 看哪些工具真被用、args 看它是不是在乱传参、ok 看失败率、cost_ms 看哪个工具拖慢了整轮对话。上线第一周我们就靠 args 发现模型习惯性把 days 传成 90(被上限截到 30),于是把上限写进了 docstring,之后就没再出现过。
六、客户端怎么接
服务端跑起来之后,客户端只需要一段配置:
{
"mcpServers": {
"ops-tools": {
"command": "python",
"args": ["/opt/mcp/ops_server.py"],
"env": {"OPS_API_BASE": "https://ops.example.com/api"}
}
}
}
凭据放环境变量,不要写在 args 里 —— 命令行参数在进程列表里是明文可见的。启动方式优先用 stdio(客户端拉起子进程),比开放一个本地端口安全;如果必须用 HTTP,至少绑 127.0.0.1 并加 token 校验。
| 传输方式 | 安全性 | 适用场景 |
|---|---|---|
| stdio(客户端拉起) | 高,不监听端口 | 本机使用,推荐 |
| HTTP 绑 127.0.0.1 | 中,本机其他进程可访问 | 多客户端共用 |
| HTTP 绑 0.0.0.0 | 低,必须加鉴权 | 不推荐 |
小结
- 不要给模型一个万能入口或 shell,把能力收敛成动作级工具,参数强类型、边界写在签名里。
- docstring 是给模型的说明书,写清格式、取值范围、是否支持模糊匹配,比工具名重要。
- 只读也要限条数和时间窗,白名单枚举优于黑名单;写操作单独进程、单独凭据、默认关闭。
- 写工具一律带
dry_run且默认True,先看它会做什么,再决定让它做。 - 返回值用全字段名、带单位和时区,大结果显式标注
truncated,否则模型会当成全量。 - 每次调用记 tool / args / ok / cost_ms,参数脱敏;日志也是数据泄露面。
- 优先 stdio 传输,凭据走环境变量而不是命令行参数。
正在加载评论…