Mcptrust

MCPTrust

Deny-by-default runtime proxy + CI gate for MCP servers. Pin what you run. Verify provenance. Enforce what tools/prompts/resources are allowed.

For: Teams running MCP servers in Claude Desktop, LangChain, AutoGen, CrewAI, or internal AI agents.

---

What It Blocks

> MCPTrust is the firewall between your AI agent and the MCP server.

• 🚫 Shadow tools at runtime — Server adds a new exec_shell tool after you approved it? Blocked.
• 🚫 Drift after lockfile — Server changed since last CI check? Fails the build.
• 🚫 Supply-chain swaps — Tarball hash doesn't match pinned artifact? Execution denied.

Without MCPTrust, any MCP server can silently add dangerous capabilities. With MCPTrust, it's deny-by-default.

---

2-Minute Quickstart

# 1. Install
go install github.com/mcptrust/mcptrust/cmd/mcptrust@latest

# 2. Lock the server's capabilities
mcptrust lock -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# 3. Run with enforcement (blocks anything not in lockfile)
mcptrust proxy --lock mcp-lock.json -- npx -y @modelcontextprotocol/server-filesystem /tmp

That's it. The proxy now sits between your host and the server, blocking any tool/prompt/resource not in your lockfile.

---

Try the "Fail Closed" Demo

See MCPTrust block a rogue tool in real-time:

# Lock a server
mcptrust lock -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Now imagine the server adds a new tool after you locked it...
# The proxy blocks unknown tools and logs:

mcptrust proxy --lock mcp-lock.json -- npx -y @modelcontextprotocol/server-filesystem /tmp
# → [BLOCKED] tools/call: unknown tool "exec_shell" not in allowlist

Expected output when a tool is blocked:

mcptrust: action=blocked method=tools/call tool=exec_shell reason="not in allowlist"

---

How It Works

┌──────────┐      ┌─────────────────────┐      ┌────────────┐
│   Host   │ ──── │   mcptrust proxy    │ ──── │ MCP Server │
│ (Claude) │      │                     │      │            │
└──────────┘      └─────────────────────┘      └────────────┘
                          │
                          ▼
              ┌─────────────────────────────┐
              │  • ID translation (anti-    │
              │    spoofing, server never   │
              │    sees host request IDs)   │
              │  • List filtering           │
              │  • Call/read blocking       │
              │  • Drift preflight check    │
              │  • Audit logs/receipts      │
              └─────────────────────────────┘

---

Feature Grid

| Feature | What It Does | |---------|--------------| | Runtime proxy | Deny-by-default enforcement between host and server | | Lockfile v3 | Allowlist tools, prompts, resources, templates | | Drift detection | CI fails on critical/moderate/info changes | | Policy presets | baseline (warn) or strict (fail-closed) | | Artifact pinning | SHA-512/256 integrity + provenance verification | | ID translation | Anti-spoofing: server never sees real host IDs | | Audit-only mode | Log everything, block nothing (training/rollout) | | Filter-only mode | Filter lists, don't block calls (visibility) |

---

Trust & Security Guarantees

MCPTrust makes explicit guarantees that other tools don't:

| Invariant | Mechanism | |-----------|-----------| | Server never sees host request IDs | Proxy-generated IDs; host IDs never forwarded | | Unknown/duplicate responses dropped | Anti-spoofing: responses must match pending requests | | Fail-closed on pending saturation | If tracking table is full, deny (no silent pass) | | Fail-closed on RNG failure | If ID generation fails, deny the request | | Fail-closed on checksum mismatch | Artifact hash must match or execution denied | | NDJSON line limits | Lines > 10MB dropped (OOM defense) | | HTTPS-only tarball downloads | HTTP blocked; private IPs blocked (SSRF defense) | | CI action pinned to SHA | Composite action uses pinned dependencies |

See [SECURITYGUARANTEES.md](SECURITYGUARANTEES.md) for full details.

---

Integrations

MCPTrust works with your existing stack:

| Platform | Status | Notes | |----------|--------|-------| | Claude Desktop | ✅ Works | Point mcpServers to mcptrust proxy -- | | Claude Code | ✅ Works | Use claude mcp add with mcptrust proxy | | Node MCP servers | ✅ Works | Any stdio-based server (npx, node, etc.) | | Python agents | ✅ Works | LangChain, AutoGen, CrewAI — use proxy as subprocess | | GitHub Actions | ✅ Native | [Composite action](.github/actions/mcptrust) for CI gates | | Docker | ✅ Works | mcptrust run supports docker run IMAGE |

Claude Desktop Example

{
  "mcpServers": {
    "filesystem": {
      "command": "mcptrust",
      "args": ["proxy", "--lock", "/path/to/mcp-lock.json", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Claude Code Example

# Generate lockfile
mcptrust lock --v3 -- npx @modelcontextprotocol/server-filesystem /tmp

# Add MCP server with MCPTrust proxy
claude mcp add my-server -- mcptrust proxy --lock mcp-lock.json -- npx @modelcontextprotocol/server-filesystem /tmp

---

GitHub Action (CI Gate)

Add MCPTrust to your CI in 30 seconds:

- uses: mcptrust/mcptrust/.github/actions/mcptrust@
  with:
    mode: check
    lockfile: mcp-lock.json
    fail_on: critical
    policy: baseline
    server_command: 'npx -y @modelcontextprotocol/server-filesystem /tmp'

| Mode | Purpose | |------|---------| | lock | Generate lockfile from server | | check | Fail if drift detected | | policy | Enforce CEL governance rules |

> [!TIP] > Pin to a commit SHA for security tooling. See [Action README](.github/actions/mcptrust/README.md).

---

Proxy Modes

                          ┌─────────────────────────────┐
                          │        Proxy Modes          │
                          └─────────────────────────────┘
                                       │
           ┌───────────────────────────┼───────────────────────────┐
           │                           │                           │
           ▼                           ▼                           ▼
   ┌───────────────┐          ┌───────────────┐         ┌────────────────┐
   │    ENFORCE    │          │  FILTER-ONLY  │         │  AUDIT-ONLY    │
   │   (default)   │          │               │         │                │
   ├───────────────┤          ├───────────────┤         ├────────────────┤
   │ ✅ Filter lists│         │ ✅ Filter lists│         │ ❌ No filtering│
   │ ✅ Block calls │         │ ❌ Allow calls │         │ ❌ Allow calls │
   ├───────────────┤          ├───────────────┤         ├───────────── ──┤
   │  Production   │          │    Rollout    │         │   Training     │
   └───────────────┘          └───────────────┘         └────────────────┘

| Mode | Lists Filtered | Calls Blocked | Use Case | |------|----------------|---------------|----------| | enforce (default) | ✅ | ✅ | Production | | --filter-only | ✅ | ❌ | Visibility rollout | | --audit-only | ❌ | ❌ | Training/logging |

# Enforce mode (default) — blocks unknown tools
mcptrust proxy --lock mcp-lock.json -- npx -y ...

# Audit-only — log but don't block (safe for rollout)
mcptrust proxy --audit-only --lock mcp-lock.json -- npx -y ...

# Filter-only — filter lists, don't block calls
mcptrust proxy --filter-only --lock mcp-lock.json -- npx -y ...

---

Supply Chain Security

MCPTrust pins and verifies the exact artifact you run:

# Lock with artifact pinning + provenance
mcptrust lock --pin --verify-provenance -- "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Enforced execution (verifies everything, then runs)
mcptrust run --lock mcp-lock.json

| Guarantee | Mechanism | |-----------|-----------| | Tarball SHA-512 matches | lockfile.artifact.integrity | | Tarball SHA-256 matches | lockfile.artifact.tarball_sha256 | | SLSA provenance verified | cosign attestation validation | | No postinstall scripts | --ignore-scripts enforced | | Local execution only | Binary from verified node_modules/.bin/ |

---

Security Posture

MCPTrust's own supply chain is hardened:

• ✅ GitHub Actions pinned to SHAs — All action dependencies use commit SHAs
• ✅ Dependabot enabled — Automated updates for GitHub Actions
• ✅ Release checksums fail-closed — Binary verification required
• ✅ HTTPS-only downloads — HTTP and private IPs blocked
• ✅ Responsible disclosure — See [SECURITY.md](SECURITY.md)

---

CLI Reference

| Command | Purpose | |---------|---------| | scan | Inspect MCP server capabilities | | lock | Create mcp-lock.json from server state | | diff | Detect drift between lockfile and live server | | proxy | Run as stdio enforcement proxy | | run | Verified execution from pinned artifact | | sign / verify | Ed25519 or Sigstore signatures | | policy check | Enforce CEL governance rules | | bundle export | Create deterministic ZIP for distribution |

See [docs/CLI.md](docs/CLI.md) for full reference.

---

Signing & Verification

Ed25519 (Local)

mcptrust keygen                           # Generate keypair
mcptrust sign --key private.key mcp-lock.json
mcptrust verify --key public.key mcp-lock.json

Sigstore (CI/CD, Keyless)

mcptrust sign --sigstore mcp-lock.json
mcptrust verify mcp-lock.json \
  --issuer https://token.actions.githubusercontent.com \
  --identity "https://github.com/org/repo/.github/workflows/sign.yml@refs/heads/main"

See [docs/SIGSTORE.md](docs/SIGSTORE.md) for GitHub Actions examples.

---

Observability

Structured Logging

mcptrust lock --log-format jsonl --log-output /var/log/mcptrust.jsonl -- "..."

Receipts (Audit Trail)

mcptrust lock --receipt /var/log/mcptrust/receipt.json -- "..."

OpenTelemetry

mcptrust lock --otel --otel-endpoint localhost:4318 -- "..."

See [docs/observability-otel.md](docs/observability-otel.md) for full options.

---

Documentation

• [CLI Reference](docs/CLI.md) — Commands, flags, examples
• [Claude Code Guide](docs/CLAUDE_CODE.md) — Full integration walkthrough
• [LangChain Guide](docs/LANGCHAIN.md) — Python adapter for agents
• [Sigstore Guide](docs/SIGSTORE.md) — Keyless signing for CI/CD
• [Security Guarantees](SECURITY_GUARANTEES.md) — Explicit security properties
• [Threat Model](docs/THREAT_MODEL.md) — What we protect against
• [Policy Guide](docs/POLICY.md) — Writing CEL rules
• [Migration Guide](docs/MIGRATION.md) — Version compatibility

---

Roadmap

• 🔜 Policy packs — Shareable governance rule sets
• 🔜 Receipts schema v2 — Stable schema for SIEM integration
• 🔜 Resource/prompt template locking — Full MCP surface coverage

---

Limitations

MCPTrust secures the interface, not the implementation:

| Out of Scope | Why | |--------------|----- | | Malicious logic | A tool named read_file that runs rm -rf looks identical via schema | | Runtime prompt injection | MCPTrust doesn't monitor agent ↔ tool conversations | | Key compromise | If private.key is stolen, attacker can sign malicious lockfiles | | Development overhead | For quick prototyping, the lockfile workflow may be overkill |

See [THREATMODEL.md](docs/THREATMODEL.md) for full details.

---

Development

go test ./...                              # Unit tests
bash tests/gauntlet.sh                     # Integration suite
MCPTRUST_BIN=./mcptrust bash scripts/smoke.sh  # Smoke test

---

Contributing

Issues and PRs welcome. See [SECURITY.md](SECURITY.md) for vulnerability reporting.

License

[Apache-2.0](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mcptrust
• Source: mcptrust/mcptrust
• License: Apache-2.0
• Homepage: https://mcptrust.dev

Install and usage instructions live in the source repository linked above.