Skip to content

MCP proxy ​

preworld-guard mcp-proxy sits between the agent's MCP client and your MCP servers. The agent connects to the proxy instead of the server. The proxy decides, then forwards. Install the SDK with the mcp extra.

What it checks:

StepAction typeEffect
Listing tools and resourcesmcp.admitA tool or resource the policy doesn't admit never appears in the agent's list
Each tools/callmcp.callA denied call returns a structured error; the upstream tool doesn't run
Each resource readmcp.readReads are checked like calls, including direct reads of a resource by URI
Questions from the server (sampling, forms, URLs)mcp.sampling, mcp.elicitation.form, mcp.elicitation.urlOff by default; each one is checked and audited on its own

It also pins what it has approved. Each tool's metadata (description, schema) is stored as a digest. If the server later changes it, that tool is frozen until someone approves the new version. The upstream's identity (transport, URL or command, authentication) is pinned the same way. A pin proves the metadata didn't change. It can't prove the server's code or its answers stayed the same.

Tool metadata and results, including the text of embedded resources, are also checked against a short list of known injection phrases. That is a narrow check, not a content filter.

One upstream server ​

Put the proxy command in the agent's MCP configuration in place of the server command:

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

For an HTTP server, use --upstream-transport and --upstream-url instead of --upstream:

sh
# Streamable HTTP (preferred)
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

Towards the agent the proxy speaks stdio, so the agent's MCP client setup stays the same. The upstream URL, headers and TLS are yours to manage.

In the policy, a tool from a single upstream is the resource mcp:<tool name>.

Several servers: the registry ​

--config takes a JSON registry of upstream servers. The connection package for the MCP proxy includes a template, 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

Each upstream has a name (lowercase letters, digits, - and _), a transport (stdio, streamable-http or sse), a command or url, and allowed_tools. Tools are exposed as <upstream>__<tool>, and the policy resource is mcp:<upstream>__<tool>, for example mcp:finance__transfer. Other fields:

FieldMeaning
headersUpstream HTTP headers. Write "Authorization": "env:MCP_UPSTREAM_AUTH" to read the value from the environment at start-up
allowed_resourcesResources the agent may read
allowed_networksPrivate address ranges (CIDR) this upstream may resolve to. Without it, only public addresses are allowed
fallback_toolsOriginal tool → fallback tool, for degrade
reverse_requestsWhich server questions to pass on: sampling, form, url (with url_allowlist). All off by default
required_client_capabilitiesCapabilities a tool needs from the client; missing ones refuse the tool up front

Approve upstreams and tools ​

Before the first run, read the upstream's identity digest, check it, then approve it:

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

A tool whose metadata changed is frozen. Look at the new metadata and approve it the same way:

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

Change the transport, URL, command or authentication of an upstream, and its origin must be approved again.

Make it impossible to go around ​

A stdio proxy started by the agent protects the clients configured to use it. It can't stop the same agent process from connecting to the server directly. When that matters, run the proxy in its own process or container with an HTTP downstream, and give the agent's network a route only to the proxy:

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
  • The agent's MCP client connects to http://guard-proxy:8766/mcp with Authorization: Bearer <PREWORLD_GUARD_DOWNSTREAM_TOKEN>.
  • --allowed-host (repeatable, or PREWORLD_GUARD_ALLOWED_HOSTS) lists the Host names the agent uses. Others get 421. Browser clients also need --allowed-origin.
  • Only the proxy's network reaches the MCP servers. The agent reaches its model through a separate controlled exit, not through the MCP network.
  • Every upstream origin must be approved before the HTTP downstream starts.
  • Across hosts, put TLS in front of the proxy.

Then check with a call that should fail: from the agent's container, try to reach the MCP server's address directly.

Wrap stdio servers in a sandbox ​

--sandbox starts a stdio upstream inside an srt sandbox. The settings come from your command line:

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

If srt isn't installed, the proxy fails at start-up. It never falls back to an unsandboxed server.

Approvals ​

An approval rule on an MCP tool makes the proxy return a pending result with a ticket in _meta. The client retries with the same arguments and the ticket. The proxy needs a trusted service subject (--subject-id). See Approvals through the MCP proxy.

Degrade ​

Degrade works only with the registry. Map the original tool to a reviewed fallback and say which arguments carry over:

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"}
      }
    }
  }]
}

The degrade rule's fallback_resource must be exactly mcp:finance__preview_transfer, and the policy must allow that tool. Guard checks the fallback's pinned metadata, its schema and the mapped fields, then decides the fallback call on its own. The original tool is never called. The response's _meta names both tools. A single-upstream proxy denies a degrade.

Per-user sign-in to upstream servers ​

From SDK 0.6.0, an HTTP-downstream proxy can check each user's token from your identity provider (JWT: issuer, audience, scope) and keep each user's OAuth grant to an upstream server in an encrypted vault on your side. Users connect through that proxy: --endpoint is the MCP proxy's HTTP downstream, not the control plane.

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

status and disconnect work the same way. Tokens and refresh tokens never leave the vault, and the caller's own token is never forwarded upstream. This needs an identity provider and per-upstream OAuth clients. We set it up with you, with OAuth clients registered in advance at each upstream.

Protocol coverage ​

The proxy uses the MCP Python SDK 2.0. It talks to upstream servers over stdio, Streamable HTTP and SSE, negotiating the newer or older protocol as each server supports, and accepts both newer and older clients. Not supported: prompts, completions, logging, resource subscriptions and roots. Resources appear as guard://<upstream>/<encoded URI>, not under their original URI.