mcp-guard

A small Model Context Protocol (MCP) server that shows how to give AI agents access to tools safely:

• OAuth 2.1 resource server: validates bearer JWTs from an external authorization server (signature via JWKS, iss, aud/RFC 8707 resource, exp) and publishes RFC 9728 Protected Resource Metadata so MCP clients can discover where to authenticate.

• Admin policy controls: a YAML policy that IT can review and version decides which tools each agent can see (tools/list is filtered) and call (tools/call is enforced). Rules use scopes plus roles, it denies by default, and it includes a per-client kill switch and rate limit.

• Audit and metrics: one JSON audit line per decision (argument names only, never values) and Prometheus metrics (mcp_tool_calls_total, mcp_tool_denials_total, mcp_tool_call_seconds).

• Tests: unit tests for the token verifier and policy engine, plus end-to-end tests over real Streamable HTTP using the official MCP Python SDK client.

Built on the official MCP Python SDK (v2).

Architecture

 MCP client / agent ──Bearer JWT──▶  Streamable HTTP /mcp
                                         │
                       SDK bearer auth ──┤  401 + WWW-Authenticate (resource_metadata) if missing/invalid
                     JWTTokenVerifier    │  iss / aud / exp / signature (JWKS or HS256 in dev)
                                         ▼
                                  PolicyMiddleware
                         tools/list ─▶ filter by policy
                         tools/call ─▶ blocked? scopes? roles? rate limit?
                                         │            └─ deny ─▶ JSON-RPC -32003 + audit + metric
                                         ▼
                                   tool handlers  ─▶ audit + latency histogram

Related MCP server: MCP-ToolHub

Quick start

pip install -e ".[dev]"
export MCP_GUARD_HS256_SECRET=dev-secret-at-least-32-bytes-long!!
python -m mcp_guard.server            # serves http://127.0.0.1:8000/mcp

# mint dev tokens with different permissions
python -m mcp_guard.devtoken --client reader --scope "tickets:read"
python -m mcp_guard.devtoken --client ops    --scope "tickets:read tickets:write" --role admin

Discovery and ops endpoints:

Policy

tools:
  search_tickets: { scopes: [tickets:read] }
  create_ticket:  { scopes: [tickets:write] }
  close_ticket:   { scopes: [tickets:write], roles: [admin] }
clients:
  blocked: [rogue-agent]
  rate_limit_per_minute: 120

Production notes

• Set MCP_GUARD_JWKS_URL (RS256/ES256 keys from your IdP) and do not set the HS256 secret.

• MCP_GUARD_RESOURCE_URL must be this server's canonical URL. Tokens whose aud doesn't match are rejected, which prevents token replay across servers (the confused-deputy problem).

• Rate-limit buckets are in-memory per process. Behind multiple replicas, move them to Redis.

• Suggested SLOs: 99.9% availability of /mcp, p95 policy-check overhead under 5 ms, measured from mcp_tool_call_seconds.

Tests

pytest -q

License

MIT