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

Trust & Security Guarantees

MCPTrust makes explicit guarantees that other tools don't:

See SECURITY_GUARANTEES.md for full details.

Integrations

MCPTrust works with your existing stack:

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'

[!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     │
   └───────────────┘          └───────────────┘         └────────────────┘

# 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

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

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:

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