Skip to content

MCP 代理 ​

preworld-guard mcp-proxy 放在 Agent 的 MCP 客户端和你们的 MCP 服务之间。Agent 连代理,而不是直接连服务。代理先判定,再转发。安装 SDK 时带上 mcp extra。

它检查这些:

环节动作类型效果
列出工具和资源mcp.admit策略不准入的工具或资源,根本不会出现在 Agent 的列表里
每次 tools/callmcp.call被拒绝的调用返回结构化错误,上游工具不执行
每次读取资源mcp.read读取和调用一样判定,按 URI 直接读取资源也一样
服务端反过来的提问(sampling、表单、URL)mcp.sampling、mcp.elicitation.form、mcp.elicitation.url默认关闭;每一次都单独判定、单独审计

它还会锁定已经批准过的东西。每个工具的元数据(描述、schema)以摘要的形式保存。服务端之后改了元数据,这个工具就被冻结,直到有人批准新版本。上游的身份(传输方式、URL 或启动命令、鉴权)也用同样的方式锁定。锁定只能证明元数据没变,证明不了服务端的代码或它返回的内容没变。

工具的元数据和返回结果(包括嵌入资源的文本)还会对照一小组已知的注入短语检查。这是很窄的一道检查,不是内容过滤。

一个上游服务 ​

在 Agent 的 MCP 配置里,用代理命令替换原来的服务命令:

sh
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.py

HTTP 服务用 --upstream-transport 和 --upstream-url,不用 --upstream:

sh
# 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:

json
{
  "manifest_pins": "manifest-pins.json",
  "upstreams": [
    {
      "name": "customer",
      "transport": "stdio",
      "command": ["replace-with-your-mcp-executable"],
      "allowed_tools": ["replace_with_tool_name"]
    }
  ]
}
sh
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_resourcesAgent 可以读的资源
allowed_networks这个上游允许解析到的内网地址段(CIDR)。不写就只允许公网地址
fallback_tools原工具 → 替代工具,用于降级
reverse_requests转发哪些服务端提问:sampling、form、url(配合 url_allowlist)。默认全部关闭
required_client_capabilities某个工具要求客户端具备的能力;不具备时预先拒绝这个工具

批准上游和工具 ​

第一次运行前,读出上游的身份摘要,核对后批准:

sh
preworld-guard mcp-origin --config ./mcp.json --server NAME
preworld-guard mcp-origin --config ./mcp.json --server NAME --approve SHA256

元数据变了的工具会被冻结。看过新的元数据后,用同样的方式批准:

sh
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 所在的网络只能访问代理:

sh
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 沙箱里启动。沙箱的设置来自你们的命令行:

sh
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 代理的审批。

降级 ​

降级只在注册表模式下可用。把原工具映射到审查过的替代工具,并写明哪些参数带过去:

json
{
  "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 下游地址,不是控制面。

sh
preworld-guard mcp-auth connect --upstream finance \
  --endpoint https://guard-proxy.example.com --token-file /private/employee-access-token

status 和 disconnect 用法相同。访问令牌和刷新令牌从不离开 vault,调用者自己的令牌也从不转发给上游。这需要身份提供方和每个上游各自的 OAuth 客户端,由我们和你们一起配置,上游的 OAuth 客户端事先在各个上游注册好。

协议覆盖范围 ​

代理基于 MCP Python SDK 2.0。它通过 stdio、Streamable HTTP 和 SSE 连接上游,按每个服务支持的情况协商新版或旧版协议,也同时接受新旧客户端。不支持:提示词(prompts)、补全、日志、资源订阅和 roots。资源以 guard://<上游>/<编码后的 URI> 的形式出现,而不是原来的 URI。