mcptrust proxy
Command reference for the runtime enforcement proxy.
Synopsis
mcptrust proxy [flags] -- <server-command>Description
Runs as a stdio proxy between the host (AI agent) and the MCP server. Enforces lockfile allowlists at runtime.
Enforcement Modes
| Mode | Flag | Behavior |
|---|---|---|
| Enforce (default) | - | Filter lists, block calls to unapproved tools |
| Audit-only | --audit-only | Log blocked requests, but allow all traffic |
| Filter-only | --filter-only | Filter lists, but don't block calls |
Flags
| Flag | Default | Description |
|---|---|---|
--lock | (required) | Path to v3 lockfile |
--timeout | 10s | Server startup timeout |
--fail-on | critical | Drift severity threshold: critical, moderate, info |
--policy | (empty) | Policy preset name (optional) |
--audit-only | false | Log blocked requests but allow all traffic |
--filter-only | false | Filter lists but don't block calls |
--allow-static-resources | false | Allow resources from startup resources/list |
--print-effective-allowlist | false | Print derived allowlist and exit |
What Gets Filtered/Blocked
| MCP Method | Enforce Behavior |
|---|---|
tools/list | Only show allowlisted tools |
tools/call | Block calls to non-allowlisted tools |
prompts/list | Only show allowlisted prompts |
prompts/get | Block gets for non-allowlisted prompts |
resources/templates/list | Only show allowlisted templates |
resources/read | Block reads for non-allowlisted resources |
Preflight Drift Check
Before bridging traffic, the proxy:
- Calls
tools/liston the server. - Compares against lockfile.
- If drift severity ≥
--fail-on, exits with error.
Advanced Features
Security & ID Translation
- ID Translation: The proxy generates fresh IDs for every request; original host IDs are never forwarded to the untrusted server.
- Anti-Spoofing: Responses with unknown or duplicate IDs are dropped silently.
- Fail-Closed: If the internal tracking table is saturated, the proxy returns an
OverloadedErrorand rejects new traffic rather than failing open.
Resource Limits
- Message Size: NDJSON lines larger than 10MB are dropped to prevent buffer exhaustion.
- OOM Protection: Strict memory limits are enforced on buffered messages.
Examples
# Enforce mode
mcptrust proxy --lock mcp-lock.json -- npx -y @scope/server
# Audit-only (for rollout testing)
mcptrust proxy --audit-only --lock mcp-lock.json -- npx -y @scope/server
# Strict drift threshold
mcptrust proxy --fail-on info --lock mcp-lock.json -- npx -y @scope/server