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 SECURITY_GUARANTEES.md for full details.

---

Integrations

MCPTrust works with your existing stack:

Platform	Status	Notes
Claude Desktop	✅ Works	Point mcpServers to mcptrust proxy -- <server>
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 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@<SHA>
  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.

---

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

---

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 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 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 for full options.

---

Documentation

• CLI Reference — Commands, flags, examples
• Claude Code Guide — Full integration walkthrough
• LangChain Guide — Python adapter for agents
• Sigstore Guide — Keyless signing for CI/CD
• Security Guarantees — Explicit security properties
• Threat Model — What we protect against
• Policy Guide — Writing CEL rules
• Migration Guide — 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 THREAT_MODEL.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 for vulnerability reporting.

License

Apache-2.0