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 |
If you only have ten minutes, start with Quickstart. It is the canonical 10-minute on-ramp and the most current copy of the install instructions.
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
- Hot-reload policy without dropping connections
Routing
- Route multiple upstreams by tool prefix
- Bridge stdio MCP clients (Claude Desktop, Cursor) to the gateway
Operations
- 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
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 —
mcpgw server,mcpgw stdio,mcpgw version - 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
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.