mcp-guard
The policy and evidence layer between your AI agent and its tools.
One binary. One config file. No Docker, no Kubernetes, no DevOps team.
Quick Start •
Modes •
Features •
Roadmap •
Documentation
The Problem
Model Context Protocol (MCP) servers give AI agents real power: files, shells, databases, SaaS APIs. Most of them run with no policy at all.
- A server advertises whatever tools it likes, and the agent calls them. Nobody said which tools were allowed.
- A server can silently rewrite its tool descriptions after you approved it. The model reads those descriptions as instructions.
- When something goes wrong, there is no record of what the agent actually did.
- Remote servers are often exposed with no authentication whatsoever.
The Solution
mcp-guard sits between the agent and every MCP server it uses, and answers three questions: what may the agent do, did the tools change, and what did it actually do?```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Agent │─────▶│ mcp-guard │─────▶│ MCP Server │
│ (Claude, │ │ │ │ (yours) │
│ Cursor...) │◀─────│ │◀─────│ │
└─────────────┘ └─────────────┘ └─────────────┘
│
Tool policy (allow / deny)
Tool pinning (lockfile)
Audit log of every call
Auth + rate limits (gateway mode)
## Quick Start
Build the binary (there are no prebuilt binaries or Homebrew tap yet):```bash
cargo install mcp-guard
# or: git clone https://github.com/botzrDev/mcp-guard && cd mcp-guard && cargo build --release
Then see what your agents are running unprotected:```bash
mcp-guard doctor
``````
Scanned 2 client config file(s):
Claude Desktop /Users/you/Library/Application Support/Claude/claude_desktop_config.json
Cursor /Users/you/.cursor/mcp.json
Servers: 4 found, 0 guarded by mcp-guard
WARN Claude Desktop / filesystem
npx -y @modelcontextprotocol/server-filesystem /Users/you runs with full access to
every tool it offers, no audit log, and no pinning of its tool definitions
fix: mcp-guard wrap --client claude-desktop --server "filesystem"
...
Next step: mcp-guard wrap --client claude-desktop
Put the guard in front of them. The client's config is backed up first, and the original command, arguments and environment are preserved:```bash
mcp-guard wrap --client claude-desktop --deny "delete_*,execute_*"
Restart the client. Every stdio server now runs behind mcp-guard with a per-server config under ~/.config/mcp-guard/, an audit log, and its tool definitions pinned on first use. Edit [policy] in the generated config to tighten access, and run mcp-guard doctor again.
Two ways to run it
Local mode: mcp-guard serve
For the servers your own agent launches on your machine. The MCP client runs mcp-guard serve, which launches the real server as a subprocess and proxies the protocol. There is nothing to authenticate here: you are the user. What you get is control and evidence.
| What it does | How |
|---|---|
| Restrict which tools the agent may call | [policy] allowed_tools and denied_tools, with globs |
| Detect tool poisoning and rug pulls | Tool definitions are hashed into a lockfile on first use. Changed or new tools are hidden and rejected until you review them with mcp-guard pin |
| Record what happened | Every tool call and every denial is written to an audit log |
| Prove what happened | The flight recorder keeps every request, response and decision in a hash-chained, redacted session file. replay renders it, verify checks it |
| Ask before acting | A hold rule pauses a call until you approve it from another terminal, with a desktop notification and a timeout |
| Keep secrets out of guard configs | Environment variables stay on the client's entry and are inherited by the upstream |
| Get in and out safely | mcp-guard wrap backs up the client config; mcp-guard unwrap restores it |
Works with Claude Desktop, Claude Code, Cursor, Windsurf and VS Code, or any JSON file with an mcpServers or servers map. See docs/local-mode.md.
Gateway mode: mcp-guard run
For servers other people or other systems reach over the network. mcp-guard listens on HTTP, authenticates callers, applies per-identity tool permissions and rate limits, and forwards to the upstream over stdio, HTTP or SSE.```bash
mcp-guard init # generate mcp-guard.toml with a demo API key
mcp-guard run # listen on :3000
curl -H "Authorization: Bearer mcp_YOUR_KEY" http://localhost:3000/health
## Features
### Local mode (free, all tiers)
- Tool policy with allow and deny globs
- Argument-level rules (`write_file` only under the workspace, `http_request` only `GET`), tested with `mcp-guard policy test`
- Shadow mode: observe first, then `mcp-guard policy suggest --apply` writes a least-privilege policy from what the agent actually used
- Tool pinning with a reviewable JSON lockfile (`mcp-guard pin`)
- Flight recorder: tamper-evident, redacted per-session recording; `mcp-guard replay` shows what the agent did (or writes an HTML report), `mcp-guard verify` proves nobody edited it
- Holds: `action = "hold"` pauses a risky call until you run `mcp-guard approve`, sudo for agents
- Per-server audit log
- `doctor`, `wrap`, `unwrap` for Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
- `guard/health`, `guard/metrics`, `guard/version` tools exposed to the agent
- Transparent forwarding of the `initialize` handshake and of resources, prompts and notifications
### Gateway mode
| Authentication | Free | Pro | Enterprise |
|--------|:----:|:---:|:----------:|
| API Keys | ✓ | ✓ | ✓ |
| JWT (HS256) | ✓ | ✓ | ✓ |
| JWT (JWKS/RS256/ES256) | | ✓ | ✓ |
| OAuth 2.1 + PKCE | | ✓ | ✓ |
| mTLS Client Certificates | | | ✓ |
| Transport | Free | Pro | Enterprise |
|------|:----:|:---:|:----------:|
| Stdio | ✓ | ✓ | ✓ |
| HTTP | | ✓ | ✓ |
| SSE | | ✓ | ✓ |
| Multi-Server Routing | | | ✓ |
| Security & Observability | Free | Pro | Enterprise |
|---------|:----:|:---:|:----------:|
| Per-Tool Authorization | ✓ | ✓ | ✓ |
| Tools Filtering | ✓ | ✓ | ✓ |
| Global Rate Limiting | ✓ | ✓ | ✓ |
| Per-Identity Rate Limiting | | ✓ | ✓ |
| Prometheus Metrics | ✓ | ✓ | ✓ |
| Health Endpoints | ✓ | ✓ | ✓ |
| Audit Logs (file/console) | ✓ | ✓ | ✓ |
| OpenTelemetry Tracing | | | ✓ |
| SIEM Log Shipping | | | ✓ |
Pro and Enterprise builds are not on sale yet. The tier split is under review; see Roadmap.
## Configuration
`mcp-guard init` generates a config file with sensible defaults. The full annotated template is at templates/mcp-guard.toml.```toml
# mcp-guard.toml
[server]
listen = "0.0.0.0:3000"
[upstream]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./"]
[rate_limit]
requests_per_second = 10
burst_size = 20
[[auth.api_keys]]
key_hash = "sha256:..."
user_id = "developer-1"
allowed_tools = ["read_file", "list_directory"]
# Used by `mcp-guard serve` (local mode)
[policy]
mode = "enforce" # or "observe" to record without blocking
allowed_tools = ["*"]
denied_tools = ["delete_*", "execute_*"]
pin_tools = true
on_pin_mismatch = "deny" # or "warn"
[[policy.rules]]
name = "writes stay in the workspace"
tools = ["write_file", "edit_file"]
action = "deny"
[policy.rules.when]
path = { not_starts_with = "/home/me/project/" }
JWT configuration```toml
[auth.jwt]
mode = "simple"
secret = "your-secret-key"
issuer = "https://your-issuer.com"
audience = "mcp-guard"
[auth.jwt.scope_mapping]
"read" = ["read_file", "list_directory"]
"write" = ["write_file", "create_directory"]
"admin" = ["*"]
OAuth 2.1 configuration```toml
[auth.oauth]
provider = "github" # or "google", "okta", "custom"
client_id = "your-client-id"
client_secret = "your-client-secret"
[auth.oauth.scope_mapping]
"repo" = ["read_file", "write_file"]
"admin:org" = ["*"]
Multi-server routing (Enterprise)```toml
[[upstream.servers]]
name = "filesystem"
path_prefix = "/fs"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./"]
[[upstream.servers]]
name = "database"
path_prefix = "/db"
transport = "http"
url = "http://localhost:8080"
## Protocol support
mcp-guard speaks MCP revisions 2024-11-05 through 2025-11-25 and passes the upstream's negotiated version through unchanged. It is transparent for resources, prompts, logging and progress notifications. Server-initiated requests (sampling, elicitation, roots) are not yet relayed in local mode and are answered with a method-not-found error so the upstream does not hang. Support for the 2026-07-28 stateless revision is on the roadmap.
## Performance
Targets, checked with the Criterion suite in `crates/mcp-guard-core/benches` (`cargo bench`):
| Metric | Target |
|--------|--------|
| Latency overhead | <2ms p99 |
| Binary size | <15MB |
| Memory usage | <50MB RSS |
| Throughput | >5,000 RPS |
## CLI Reference```
mcp-guard <command>
Local mode
doctor Scan MCP client configs and report unprotected servers
wrap Put mcp-guard in front of a client's stdio servers
unwrap Restore servers wrapped with `wrap`
pin Pin, review or accept the upstream's tool definitions
policy test Evaluate the policy against one tool call
policy suggest Propose a least-privilege policy from the audit log
replay Show a recorded session as a timeline, or write an HTML report
verify Check a recording's hash chain
holds List calls waiting for approval
approve / deny Decide a held call
serve Run as a stdio proxy (what wrapped clients launch)
Gateway mode
init Generate config file with demo API key
validate Check config file for errors
keygen Generate a new API key
hash-key Hash an existing API key for the config
run Start the HTTP gateway
check-upstream Test upstream server connectivity
version Show version and build info
Options:
-c, --config Config file path (default: mcp-guard.toml)
-v, --verbose Verbose logging (stderr)
-h, --help Show help
Roadmap
The direction: stop competing on authentication, which the MCP spec and every API gateway now cover, and own the layer above it, what an agent may do and proof of what it did. In rough order:
- Result inspection. Rules on what comes back from a server (secret and PII redaction, size limits), extending today's argument rules.
- Recorder in gateway mode. Per-identity recording for
mcp-guard run. - Protocol shim. Full support for the 2026-07-28 stateless revision, relaying server-initiated requests, and exposing old stdio servers as compliant remote servers.
- Prebuilt binaries and a Homebrew tap.
- Re-tiering. Make the open core complete (all auth, all transports) and charge for policy packs, the recorder, fleet management and support.
The full list, including release tasks, known gaps and decisions still open, is in FUTURE.md. Issues and pull requests on any of these are welcome.
Documentation
| Topic | Guide |
|---|---|
| Local mode | wrap, doctor, pin, serve |
| Flight recorder | replay, verify, record format |
| Getting Started | Quick Start |
| Authentication | Auth Guide |
| Transports | Stdio/HTTP/SSE |
| Configuration | Reference |
| Rate Limiting | Rate Limits |
| Observability | Metrics & Tracing |
| Security Model | Threats and controls |
| Deployment | Production Guide |
| API Reference | HTTP API |
| CLI | Command reference |
Repository layout```
crates/
mcp-guard-core/ Library: config, auth, authz, policy, pinning, transports, server
mcp-guard-cli/ The mcp-guard binary
mcp-guard-pro/ Pro license verification (optional feature)
mcp-guard-enterprise/ Enterprise license verification and admin tools (optional feature)
docs/ User and developer documentation
examples/ Config examples (API key, JWT with Auth0, GitHub OAuth, multi-server, Kubernetes)
templates/ Annotated config template
landing/, workers/ Website and Cloudflare Workers for licensing (not needed to use mcp-guard)
## Security
Security vulnerabilities should be reported via support@botzr.com.
See SECURITY.md for our security policy.
## Contributing
We welcome contributions. See CONTRIBUTING.md for guidelines.```bash
git clone https://github.com/botzrDev/mcp-guard
cd mcp-guard
cargo build
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
License
AGPL-3.0. See LICENSE.
Commercial licenses available for Pro and Enterprise tiers.
Built by botzr
