Leash MCP观测器深度解读:如何拦截并强制执行AI代理的MCP工具调用
Leash MCP观测器深度解读:如何拦截并强制执行AI代理的MCP工具调用
Leash MCP观测器是 Leash 项目内建的透明代理组件,用于拦截、记录并强制执行 AI 代理发出的 MCP(Model Context Protocol)工具调用。它嗅探 JSON-RPC 与 SSE 两种传输,解析出 method 与工具名,再交由策略判定——不合规的 tools/call 会被直接拒绝。下面拆解这条从"抓包"到"执法"的完整链路。
- 🕵️ 双传输嗅探:同时覆盖 JSON-RPC 与 SSE 流式响应
- 🚦 转发前拦截:拒绝发生在请求发往上游之前
- 📜 Cedar 策略驱动:
forbid语句自动转译为 MCP 拒绝规则 - 📊 全链路遥测:结构化日志 + OpenTelemetry 指标与 span
核心拦截链路:从透明代理到策略判定
整个机制的核心是 proxy.go 中的透明 MITM 代理,配合 mcp_observer.go 中的 MCP 观测器。完整流程共 8 步:
- Agent 向 MCP 服务器发起 HTTP(S) 请求(如
mcp.context7.com) - eBPF LSM 先做网络层策略检查
- MITM 代理拦截 TLS 连接并读取 JSON-RPC 载荷
- 观测器解析
method字段(如tools/call)并提取params.name(工具名) - 策略检查器执行
CheckMCPCall(server, tool)判定 - 若被拒绝,代理返回
403 Forbidden及拒绝原因 - 若放行,请求被转发到上游服务器
- 事件写入 WebSocket 事件流,附带 server、tool、method 等元数据
💡 关键点:网络层放行 ≠ 工具调用放行。连接策略放行后,代理仍能在 HTTP 层精确到"单个工具"进行执法,形成两层防御。
请求嗅探:JSON-RPC 与 SSE 双传输
代理创建时会实例化观测器(见 mcp_observer.go#L85-L98)。每个 HTTP 请求进入 inspectHTTPRequest 后按顺序处理:
- 内容类型过滤:非
application/json请求直接跳过 - 限额嗅探:最多读取 1MB 请求体,随后把完整请求体原样恢复,不影响后续转发
- 信封解析:校验
jsonrpc: "2.0",提取method、id;若是tools/call则解析params.name得到工具名 - 事件映射:将方法名映射为语义化事件
| JSON-RPC 方法 | 生成的事件名 |
|---|---|
tools/call |
mcp.call |
tools/list |
mcp.discover |
initialize / initialized |
mcp.initialize / mcp.initialized |
resources/list、resources/read |
mcp.resources.* |
prompts/list、prompts/get |
mcp.prompts.* |
SSE 传输同样被完整覆盖:当响应 Content-Type 为 text/event-stream 时,响应体会被包装成流式嗅探器(sseSniffer),逐块读取并按 SSE 事件边界解析 data: 行,默认每连接最多记录 10 个事件,防止长连接耗尽内存。
强制执行:不转发,直接返回 JSON-RPC 错误
判定逻辑由 PolicyChecker 接口承接,真正执行在 enforceMCPCall:
- 仅对
tools/call方法生效 - 调用 CheckMCPCall(server, tool):无 MCP 规则时全部放行;有规则时按 server + tool 规范化匹配,首个匹配规则生效
- 被拒绝时,代理不转发请求,而是直接构造一个标准的 JSON-RPC 错误体返回,然后关闭连接
拒绝响应示例(由 proxy.go#L344 构造):
{"jsonrpc":"2.0","id":"1","error":{"code":-32000,"message":"MCP tools/call denied by policy (server=xxx) (tool=yyy)"}}
同时观测器会写入一条 decision=denied 的 mcp.call 事件,并记录 http.request 日志行,形成完整审计闭环。
还有一个精妙细节:当存在 MCP 策略时,代理会通过 setForceParse 开启强制解析——即使观测模式为 off,也会解析出 method 与 tool 供判定使用。这意味着强制执行不受观测开关影响,只记录不拦截时也不会漏判。
Cedar 策略如何转译为 MCP 规则
用户以 Cedar 策略声明意图,转译器 cedar_to_leash.go 将其编译为运行时规则,支持三种模式:
1️⃣ 服务器级拒绝——阻断到某服务器的全部 MCP 流量,同时转译为网络拒绝规则(双保险):
forbid (principal, action == Action::"McpCall", resource)
when { resource in [ MCP::Server::"mcp.untrusted.com" ] };
2️⃣ 工具级拒绝——只拦截某个服务器上的特定工具,其余工具照常可用:
forbid (principal, action == Action::"McpCall", resource == MCP::Tool::"resolve-library-id")
when { resource in [ MCP::Server::"mcp.context7.com" ] };
3️⃣ 信息型 permit——V1 中仅记录不执行,转译时产生 mcp_allow_noop lint 警告。
⚠️ 注意:工具级拒绝必须同时提供
MCP::Tool与MCP::Server两个资源才能生效。更多示例见 CEDAR.md。
观测数据:结构化日志与 OpenTelemetry 遥测
每次 MCP 交互都会产出一条结构化日志,包含 event、server、method、tool、status、outcome、decision、duration_ms 等字段;enhanced 模式下还会追加 transport、proto 与截断后的 session 字段。
遥测层由 mcp_instruments.go 提供:
- 指标:
mcp.requests_total、mcp.errors_total计数器与mcp.request.duration耗时直方图 - 追踪:每个请求生成一个 span(如
mcp.tools/call:xxx),启用传播时还会向转发请求注入 W3C trace 头,实现跨服务关联 - 策略提示:最近观测到的 server / tool 列表通过 SnapshotMCPHints 暴露给补全引擎,帮助你在编辑策略时自动联想
配置 MCP 观测器:3 个环境变量速查
MCP 观测器由 mcp_config.go 读取环境变量完成配置,全部有合理默认值:
| 环境变量 | 默认值 | 作用 |
|---|---|---|
LEASH_MCP_OBS |
basic |
观测模式:off / basic / enhanced(enhanced 追加 transport、proto、session 字段) |
LEASH_MCP_SNIFF_LIMIT |
1048576(1MB) |
单请求/响应的嗅探字节预算 |
LEASH_MCP_SSE_EVENT_LIMIT |
10 |
每个 SSE 连接最多记录的事件数 |
当前限制与适用边界
| 限制 | 说明 |
|---|---|
仅 forbid 生效 |
permit 目前仅作信息记录,会触发 mcp_allow_noop lint 警告 |
| HTTP/2 隧道 | ALPN 协商为 h2 的连接走透明隧道,不解析 MCP 载荷 |
| 大载荷放弃嗅探 | 请求体超过嗅探预算时跳过解析,转发不受影响 |
| 工具级策略需双资源 | MCP::Tool 必须与 MCP::Server 同时出现 |
总结
Leash MCP观测器把"AI 代理调用了哪个 MCP 工具"从黑盒变成了可审计、可拦截的白盒:透明代理负责抓包,观测器负责解析,Cedar 策略负责决策,OTel 负责度量。配合 Leash 的 eBPF 文件/网络监控,你可以在 Control UI(默认 localhost:18080)中完整看到 AI 代理的每一次工具调用,并即时拒绝高危操作——这也是"take your AI agents for a walk"这句口号的具体落地。
相关源码入口:
- MCP 观测器:internal/proxy/mcp_observer.go
- 代理与强制拦截:internal/proxy/proxy.go
- 策略判定实现:internal/lsm/net_connect.go
- 架构文档:docs/design/ARCHITECTURE.md