给 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)
    ...

白名单(而不是黑名单)是关键。枚举值写死在代码里,模型没法构造出意料之外的查询。

写操作那边我们做了三层隔离:

  1. 独立进程、独立凭据,凭据只有目标接口的写权限,没有库权限;
  2. 工具默认不注册,需要时通过环境变量打开,会话结束就关;
  3. 所有写操作工具必须带 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 传输,凭据走环境变量而不是命令行参数。
查看「AI 应用」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

给 AI 助手接内部系统:MCP 工具的粒度与权限边界 - 起航社区