@cardor/heimdall-mcp
Transparent proxy for any MCP server. Intercepts all JSON-RPC messages, measures latency, stores traces in a configurable database, and enforces per-server allow/deny policies — without touching the original server.
Visit the website to view a full explanation, examples, and other tools!
Table of Contents
- @cardor/heimdall-mcp
- Table of Contents
- How it works
- Installation
- Policy config
- Config files
- Config format
- Merge strategy
- Argument policies
- What happens when a call is blocked
- Server name
- Policy config in library mode
- Usage modes
- Mode 1 — CLI wrapping a subprocess (stdio)
- Mode 2 — CLI wrapping a remote HTTP server
- Mode 3 — CLI wrapping a remote SSE server
- Mode 4 — Library for developers
- Stores
- SQLite
- PostgreSQL
- MySQL
- What gets recorded
- Jaeger UI (OTLP)
- 1. Start Jaeger
- 2. Add
--otlpto your config - 3. Open Jaeger UI
- Custom interceptors
- CLI reference
- start
- init
- health
- Tracing reference
- Roadmap
How it works
flowchart LR
A["MCP Client\n(Claude Desktop / OpenCode / Cursor)"]
subgraph proxy["heimdall-mcp"]
B["TelemetryInterceptor"]
P["PolicyInterceptor"]
C["ForwardInterceptor"]
D[("SQLite\nPostgres\nMySQL")]
B --> P
P --> C
B -->|"saves span"| D
end
S["Real MCP server\n(subprocess / HTTP / SSE)"]
A -->|"stdio"| B
C -->|"stdio · http · sse"| S
S -->|"response"| C
C -->|"response"| A
