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

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
adapters/python		adapters/python
cmd/mcptrust		cmd/mcptrust
docs		docs
examples		examples
internal		internal
scripts		scripts
testdata		testdata
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MAINTAINER_VERIFICATION.md		MAINTAINER_VERIFICATION.md
Makefile		Makefile
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
SECURITY.md		SECURITY.md
SECURITY_GUARANTEES.md		SECURITY_GUARANTEES.md
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

MCPTrust

What It Blocks

2-Minute Quickstart

Try the "Fail Closed" Demo

How It Works

Feature Grid

Trust & Security Guarantees

Integrations

Claude Desktop Example

Claude Code Example

GitHub Action (CI Gate)

Proxy Modes

Supply Chain Security

Security Posture

CLI Reference

Signing & Verification

Ed25519 (Local)

Sigstore (CI/CD, Keyless)

Observability

Structured Logging

Receipts (Audit Trail)

OpenTelemetry

Documentation

Roadmap

Limitations

Development

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Languages

License

mcptrust/mcptrust

Folders and files

Latest commit

History

Repository files navigation

MCPTrust

What It Blocks

2-Minute Quickstart

Try the "Fail Closed" Demo

How It Works

Feature Grid

Trust & Security Guarantees

Integrations

Claude Desktop Example

Claude Code Example

GitHub Action (CI Gate)

Proxy Modes

Supply Chain Security

Security Posture

CLI Reference

Signing & Verification

Ed25519 (Local)

Sigstore (CI/CD, Keyless)

Observability

Structured Logging

Receipts (Audit Trail)

OpenTelemetry

Documentation

Roadmap

Limitations

Development

Contributing

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages