Documentation
Herkos is a local-first, in-path MCP broker for AI coding agents. It runs on your machine, between the agent and the MCP servers it uses, and gives you deny-by-default control over which tools run and what leaves, with a signed record of every brokered call.
What Herkos does
Your AI coding agent connects to MCP servers you did not write - GitHub, Slack, a database, the filesystem. Any of them can read your code through a tool call and send it to a backend you do not control, and you get no deny-by-default say over which tools run or a verifiable record of what left. Herkos sits in-path between the agent and those servers and gates every tool call.
Its mechanism is SpanGate. For each query, Herkos's local code graph emits a minimal set of (file, line-range) spans, and that one set is both the minimal context a query needs and the egress allowlist - one core.Binding, by type invariant. The shipping broker enforces the egress half deny-by-default and signs an offline-verifiable log of every brokered call.
The minimal context an agent needs is exactly the only thing it should be allowed to send. One set of spans, two jobs. You hold the leash, not the cloud.
The pieces
| Piece | What it is |
|---|---|
| SpanGate | The core. Emits the minimal span set and uses it as both context and allowlist. |
| The broker | herkos serve sits in-path in front of an MCP server and gates outbound tool calls by tool name, deny-by-default. |
| Span receipt | A signed Merkle receipt of which spans touched the model, verifiable locally with your own key. |
| Serve audit log | herkos serve --receipts writes a separate per-call, signed, hash-chained log of every brokered tools/call (tool name, request hash, allow or deny), verifiable offline with just the public key. |
| Scanner | herkos scan audits an MCP config for over-scoped tools, poisoned descriptions (drift from a baseline), and unrestricted egress. |
Where to go next
- Install with
go installor build from source. - Quickstart: keygen, register, serve, with the real commands.
- Concepts: SpanGate, receipts, and the two enforcement modes.
- Dual-use binding: the one idea, and exactly where it holds and does not.
- Case studies: five real 2025 MCP incidents, and what Herkos would actually have done.
- Security model: the threat model and the bypass we publish ourselves.
- CLI reference: every command and flag.
Early development, working end to end. The SpanGate core, the tree-sitter parser, the CLI, and the live in-path broker all work today. The broker speaks the real MCP stdio wire format and was verified against a reference MCP server: an allowed tool reaches the upstream server, a non-allowlisted one is blocked in-path with a JSON-RPC error and the session keeps going. The broker's egress guard is tool-name only for now, and userspace mode is advisory rather than kernel-enforced. Not production-secure yet. See the security model for exactly what holds and what does not.