Documentation overview
mcpgw documentation is organized using the Diátaxis framework. Pick the quadrant that matches what you are trying to do.
| You are… | Go to | Examples |
|---|---|---|
| Brand new — want it running | Tutorials | First traced call, protect a real MCP server |
| Solving a specific problem | How-to guides | Deny a tool, redact secrets, rate-limit |
| Looking up a specific fact | Reference | Config schema, CLI flags, error codes |
| Trying to understand the design | Explanation | Architecture, policy model, licensing |
Start with Quickstart. It is the canonical on-ramp and the most current copy of the install instructions. Before an upgrade, read Compatibility and upgrades.
Tutorials
Learning-oriented walkthroughs. Follow them top-to-bottom; they are designed so you cannot fail if you copy carefully.
- 01 — Your first traced MCP call — install the gateway, point Claude Desktop at it, see a span in Datadog APM
- 02 — Protect a real MCP server with policy — wrap an existing filesystem MCP server, write your first deny + redact rules, watch the audit log
How-to guides
Task-oriented recipes. Each one solves a single problem and assumes you already know how to start the gateway.
Policy
- Deny a tool by name
- Enable default-deny policy
- Enable API-key authentication
- Redact secrets in tool arguments
- Rate-limit a write tool
- Govern elicitation/create messages — deny, redact, or rate-limit server-initiated prompts using the
directionmatcher - Govern MCP Apps content — strip, allow selectively, or monitor interactive UI blocks in tool-call responses using
strip_app - Enable a guardrail webhook — delegate pass / mask / reject to an outbound HTTP endpoint, fail-closed by default
- Hot-reload policy without dropping connections
Routing
- Route multiple upstreams by tool prefix
- Bridge stdio MCP clients (Claude Desktop, Cursor) to the gateway
- Enable tool-search synthesis — synthesize a virtual
mcp_searchtool to slash tool-definition tokens
Operations
- Enable OAuth 2.1 authentication — switch from API keys (or run alongside) to JWT bearer tokens
- Run mcpgw behind a load balancer
- Enable Datadog tracing via the OTLP receiver
- Ship audit logs to Google Cloud Storage
- Ship audit logs to Amazon S3
- Ship audit logs to Kafka
- Ship audit logs to a SIEM webhook
- Tail and parse the audit log
- Rotate the license JWT
- Configure a shared rate-limit store (Redis) — one global limit across replicas instead of N×
- Run mcpgw in HA on Kubernetes — Helm chart, Traefik frontend, two-stage drain, PDB, HPA
Reference
Information-oriented technical descriptions. Look here for the exact answer to “what does this field do?”
- Configuration schema — every key in
mcpgw.yaml - CLI commands and flags —
serve,stdio,version,healthcheck,reload, plus the admin surface:doctor,config,key,license,policy(incl.replay),upstream,tools,trace,audit(incl.follow),completion - Policy rule schema — full grammar for
policy.rules[] - Error codes — every JSON-RPC + HTTP code mcpgw can return
- OpenTelemetry semantic conventions — span names, attributes, enum values
- Audit log schema — every field in
audit.jsonl - Health endpoints —
/healthz,/readyz, semantics and exit codes - License JWT claims — claim shape, grace window, fail-closed conditions
- Compatibility and upgrades — tagged breaking changes, protocol dialects, reload boundaries, and rollback notes
The legacy policy-cookbook.md and semconv.md are kept for backwards-linking; new content lives under the quadrants above.
Explanation
Understanding-oriented discussion. These exist so you can make the right design call, not just copy a recipe.
- Architecture and request lifecycle
- How OAuth works in mcpgw — the RFC 9728 / RFC 6750 model, hot reload, failure modes
- Tool-search tradeoffs — why synthesize mode helps some agents and hurts others
- Why policy is first-match-wins (and what that means for you)
- How trusted-proxy rate-limit identity stays spoof-resistant
- Why redact is regex-over-body in v1, not JSONPath
- Guardrail webhooks: design and tradeoffs — engine purity, fail posture, latency budget, why SSE is deferred
- How licensing fails open and fails closed
- mcpgw vs the alternatives (DIY, egress proxy, network firewall)