mcp-guard

mcp-guard is a local-first MCP proxy that enforces policy before forwarding JSON-RPC tool calls to an upstream MCP server.

What it does

• Enforces allow/deny tool lists
• Enforces argument-level rules (arg_rules)
• Enforces payload-size limits
• Applies per-tool/per-client rate limits
• Redacts sensitive text in audit excerpts
• Persists signed audit events to JSONL or SQLite
• Supports replay by event_id

CLI

mcp-guard run --config mcp-guard.yaml
mcp-guard validate --config mcp-guard.yaml
mcp-guard replay --log logs/session.jsonl --id <event_id>
mcp-guard policy test --config mcp-guard.yaml --fixture fixtures/*.json

Quick start

1. Validate config:

mcp-guard validate --config mcp-guard.yaml

2. Run policy fixtures:

mcp-guard policy test --config mcp-guard.yaml --fixture fixtures/*.json

3. Start proxy:

mcp-guard run --config mcp-guard.yaml

Demo scenarios

• Block filesystem.delete: fixtures/block-filesystem-delete.json
• URL whitelist for http.fetch: fixtures/allow-http-fetch-example.json
• Deny non-whitelisted http.fetch: fixtures/deny-http-fetch-non-whitelist.json

Config shape

Top-level keys:

• version
• servers
• policies
• redaction
• rate_limits
• audit
• defaults

See mcp-guard.yaml for a full example.

Audit event schema

Each JSONL line stores:

• event_id
• timestamp
• client_id
• server
• tool
• decision
• reason
• latency_ms
• arg_hash
• redactions_applied
• request_excerpt
• response_excerpt
• event_hash

event_hash is a SHA-256 signature over the event body (excluding event_hash) for replay integrity checks.

Build and test

go test ./...
go build ./cmd/mcp-guard

Packaging

• Static binaries: see Makefile
• Docker image: see Dockerfile
• CI matrix (Linux/macOS/Windows): .github/workflows/ci.yml

Docs

• Architecture: docs/architecture.md
• Threat model: docs/threat-model.md
• Benchmarks: docs/benchmark.md
• Skillbench follow-up plan: docs/skillbench-roadmap.md

License

Apache-2.0