Documentation · v0.2
Documentation
MCPdef is one static binary between your agents and the MCP servers they call. These pages are the whole manual: how it works inside, every configuration key, the wire surface, and how to run it.
Start here
Five minutes
Quickstart
One config file, a call that is allowed and a call that is refused, with real output.
How it works
Architecture
The path one tools/call takes through the crates, in gate order.
Configure it
Configuration
Every mcpdef.toml key and CLI flag.
All pages
Start
Architecture
How one tools/call moves through the binary: the crates, the gate order, the sandbox path.
Reference
Configuration
Every knob: mcpdef.toml keys, CLI flags, and the on-disk data formats.
Reference
API
The wire surface as built: listener endpoints, status codes, method dispatch, gate order and every deny reason.
Reference
Protocol revisions
The two MCP eras, 2025-11-25 and the stateless 2026-07-28: how to pick one per listener and per upstream, and what is not implemented yet.
Run it
Operations
The runbook: deploy, what state to back up, ledger verification with out-of-band seals, monitoring, troubleshooting.
Run it
Deploy
A cloud VM with Docker or Podman, or Kubernetes with the Helm chart; metrics and the Grafana dashboard.
Run it
Container image
The published image: tags, a quick docker run, and where MCPdef fits in a stack.
What these docs say plainly
- The hash chain proves internal consistency, not tamper-proof: catching tail-truncation needs a
(head, count)pair sealed out-of-band. Operations has the procedure. - Two things have not landed: the
transformpolicy effect, and resource-URI allowlists (parsed and reserved, but only tools are gated). See status. - The gateway has no in-process TLS. Put a TLS-terminating proxy and
[gateway.auth]in front of it for anything off-host. Deploy says how.