MCP 代理
preworld-guard mcp-proxy 放在 Agent 的 MCP 客户端和你们的 MCP 服务之间。Agent 连代理,而不是直接连服务。代理先判定,再转发。安装 SDK 时带上 mcp extra。
它检查这些:
| 环节 | 动作类型 | 效果 |
|---|---|---|
| 列出工具和资源 | mcp.admit | 策略不准入的工具或资源,根本不会出现在 Agent 的列表里 |
每次 tools/call | mcp.call | 被拒绝的调用返回结构化错误,上游工具不执行 |
| 每次读取资源 | mcp.read | 读取和调用一样判定,按 URI 直接读取资源也一样 |
| 服务端反过来的提问(sampling、表单、URL) | mcp.sampling、mcp.elicitation.form、mcp.elicitation.url | 默认关闭;每一次都单独判定、单独审计 |
它还会锁定已经批准过的东西。每个工具的元数据(描述、schema)以摘要的形式保存。服务端之后改了元数据,这个工具就被冻结,直到有人批准新版本。上游的身份(传输方式、URL 或启动命令、鉴权)也用同样的方式锁定。锁定只能证明元数据没变,证明不了服务端的代码或它返回的内容没变。
工具的元数据和返回结果(包括嵌入资源的文本)还会对照一小组已知的注入短语检查。这是很窄的一道检查,不是内容过滤。
一个上游服务
在 Agent 的 MCP 配置里,用代理命令替换原来的服务命令:
preworld-guard \
--endpoint https://guard.example.com \
--project-id "$PREWORLD_GUARD_PROJECT_ID" \
--token "$PREWORLD_GUARD_TOKEN" \
mcp-proxy --upstream uv run my_mcp_server.pyHTTP 服务用 --upstream-transport 和 --upstream-url,不用 --upstream:
# Streamable HTTP(首选)
preworld-guard \
--endpoint "$PREWORLD_GUARD_ENDPOINT" --project-id "$PREWORLD_GUARD_PROJECT_ID" \
--token "$PREWORLD_GUARD_TOKEN" mcp-proxy \
--upstream-transport streamable-http --upstream-url https://mcp.example.com/mcp \
--header 'Authorization=Bearer upstream-token'
# SSE
preworld-guard \
--endpoint "$PREWORLD_GUARD_ENDPOINT" --project-id "$PREWORLD_GUARD_PROJECT_ID" \
--token "$PREWORLD_GUARD_TOKEN" mcp-proxy \
--upstream-transport sse --upstream-url https://mcp.example.com/sse代理对 Agent 一侧仍是 stdio,所以 Agent 的 MCP 客户端配置不用改。上游的 URL、请求头和 TLS 由你们自己管理。
策略里,单个上游的工具对应的资源是 mcp:<工具名>。
多个上游:注册表
--config 接收一份 JSON 格式的上游注册表。MCP 代理的接入包里带一个模板 guard-mcp.template.json:
{
"manifest_pins": "manifest-pins.json",
"upstreams": [
{
"name": "customer",
"transport": "stdio",
"command": ["replace-with-your-mcp-executable"],
"allowed_tools": ["replace_with_tool_name"]
}
]
}preworld-guard mcp-proxy --config guard-mcp.template.json每个上游有 name(小写字母、数字、- 和 _)、transport(stdio、streamable-http 或 sse)、command 或 url,以及 allowed_tools。工具以 <上游>__<工具> 的名字暴露给 Agent,策略里的资源是 mcp:<上游>__<工具>,比如 mcp:finance__transfer。其他字段:
| 字段 | 含义 |
|---|---|
headers | 发给上游的 HTTP 头。写成 "Authorization": "env:MCP_UPSTREAM_AUTH",启动时从环境变量读取值 |
allowed_resources | Agent 可以读的资源 |
allowed_networks | 这个上游允许解析到的内网地址段(CIDR)。不写就只允许公网地址 |
fallback_tools | 原工具 → 替代工具,用于降级 |
reverse_requests | 转发哪些服务端提问:sampling、form、url(配合 url_allowlist)。默认全部关闭 |
required_client_capabilities | 某个工具要求客户端具备的能力;不具备时预先拒绝这个工具 |
批准上游和工具
第一次运行前,读出上游的身份摘要,核对后批准:
preworld-guard mcp-origin --config ./mcp.json --server NAME
preworld-guard mcp-origin --config ./mcp.json --server NAME --approve SHA256元数据变了的工具会被冻结。看过新的元数据后,用同样的方式批准:
preworld-guard mcp-manifest --config ./mcp.json --server NAME --kind tool --name TOOL
preworld-guard mcp-manifest --config ./mcp.json --server NAME --kind tool --name TOOL --approve SHA256上游的传输方式、URL、启动命令或鉴权一变,就要重新批准它的身份。
让 Agent 绕不过去
由 Agent 启动的 stdio 代理,只能保护配置了它的客户端,挡不住同一个 Agent 进程直接连原始服务。需要防绕过时,把代理放在独立的进程或容器里,用 HTTP 下游,并让 Agent 所在的网络只能访问代理:
export PREWORLD_GUARD_DOWNSTREAM_TOKEN='independent-random-secret'
preworld-guard --endpoint "$PREWORLD_GUARD_ENDPOINT" \
--project-id "$PREWORLD_GUARD_PROJECT_ID" --token "$PREWORLD_GUARD_TOKEN" \
mcp-proxy --config ./mcp.json --downstream-transport streamable-http \
--listen-host 0.0.0.0 --listen-port 8766 --allowed-host guard-proxy:8766- Agent 的 MCP 客户端连
http://guard-proxy:8766/mcp,并发送Authorization: Bearer <PREWORLD_GUARD_DOWNSTREAM_TOKEN>。 --allowed-host(可重复,或用PREWORLD_GUARD_ALLOWED_HOSTS)列出 Agent 实际使用的 Host,其他 Host 返回 421。浏览器里的客户端还要加--allowed-origin。- 只有代理所在的网络能访问 MCP 服务。Agent 访问模型要走单独的受控出口,不要经过 MCP 的后端网络。
- HTTP 下游启动前,所有上游的身份都要先批准。
- 跨主机时,在代理前面加 TLS。
然后用一次本应失败的调用验证:在 Agent 的容器里,试着直接访问 MCP 服务的地址。
把 stdio 服务放进沙箱
--sandbox 把 stdio 上游放进 srt 沙箱里启动。沙箱的设置来自你们的命令行:
preworld-guard \
--endpoint "$PREWORLD_GUARD_ENDPOINT" --project-id "$PREWORLD_GUARD_PROJECT_ID" \
--token "$PREWORLD_GUARD_TOKEN" mcp-proxy \
--sandbox --sandbox-workspace "$PWD" \
--sandbox-allow-read "$PWD" --sandbox-allow-write "$PWD/.agent-tmp" \
--sandbox-deny-write "$HOME/.ssh" \
--upstream uv run my_mcp_server.py没装 srt 时,代理在启动阶段就失败,不会退回到不带沙箱的上游。
审批
MCP 工具命中需审批规则时,代理返回一个待审批的结果,票据放在 _meta 里。客户端用同样的参数加上票据重试。代理需要一个可信的服务主体(--subject-id)。见经过 MCP 代理的审批。
降级
降级只在注册表模式下可用。把原工具映射到审查过的替代工具,并写明哪些参数带过去:
{
"upstreams": [{
"name": "finance",
"transport": "streamable-http",
"url": "https://finance-mcp.example.com/mcp",
"allowed_tools": ["transfer", "preview_transfer"],
"fallback_tools": {
"transfer": {
"tool": "preview_transfer",
"argument_fields": {"account_id": "account_id"}
}
}
}]
}降级规则的 fallback_resource 必须正好是 mcp:finance__preview_transfer,并且策略要放行这个工具。Guard 核对替代工具锁定的元数据、它的 schema 和映射的字段,然后单独判定这次替代调用。原工具永远不会被调用。响应的 _meta 里写明原工具和实际执行的替代工具。单上游代理遇到降级直接拒绝。
按用户登录上游服务
从 SDK 0.6.0 起,HTTP 下游的代理可以校验每个用户从你们身份提供方拿到的令牌(JWT:issuer、audience、scope),并把每个用户对上游服务的 OAuth 授权存在你们这边的加密 vault 里。用户经由这个代理连接:--endpoint 是 MCP 代理的 HTTP 下游地址,不是控制面。
preworld-guard mcp-auth connect --upstream finance \
--endpoint https://guard-proxy.example.com --token-file /private/employee-access-tokenstatus 和 disconnect 用法相同。访问令牌和刷新令牌从不离开 vault,调用者自己的令牌也从不转发给上游。这需要身份提供方和每个上游各自的 OAuth 客户端,由我们和你们一起配置,上游的 OAuth 客户端事先在各个上游注册好。
协议覆盖范围
代理基于 MCP Python SDK 2.0。它通过 stdio、Streamable HTTP 和 SSE 连接上游,按每个服务支持的情况协商新版或旧版协议,也同时接受新旧客户端。不支持:提示词(prompts)、补全、日志、资源订阅和 roots。资源以 guard://<上游>/<编码后的 URI> 的形式出现,而不是原来的 URI。