enmanuelmag/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
- Resource locks
- Host policies
- Limitations
- 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 --otlp to your config
- 3. Open Jaeger UI
- Custom interceptors
- CLI reference
- start
- init
- health
- Tracing reference
- Roadmap
---
How it works
The proxy always exposes **stdio** to the MCP client and speaks the correct transport to the real server. Every request/response pair is converted into a span with timing, attributes, and the input/output body.
---
Installation
---
Policy config
Drop a heimdall.config.ts in your project root and define exactly which tools, prompts, and resources each MCP server is allowed to expose to the agent — at the proxy layer, without touching the server code.
Config files
| Scope | Path | Purpose |
|--------|------|---------|
| Local | {project-root}/heimdall.config.{ts,js,mjs,cjs,json} | Per-repo rules |
| Global | ~/.config/heimdall/heimdall.config.{ts,js,mjs,cjs,json} | User/org-wide rules |
Both are optional. If neither exists, the proxy stays fully transparent (backward compatible).
Config format
TypeScript configs are loaded via jiti without pre-compilation. Also works as .js, .mjs, .cjs, or .json.
Merge strategy
When both local and global configs exist, they merge with **security-first semantics**:
| Rule | Behavior |
|---|---|
| **Deny → union** | Denied by either = denied. Global deny cannot be overridden locally. |
| **Allow → intersection** | Must pass both. * or [] means "defer to the other side." |
| **Deny beats allow** | Within any single config, deny always wins. |
The global config enforces a floor the team can't accidentally loosen. Local configs can only add *more* restrictions, never fewer.
Argument policies
toolPolicies adds a second enforcement layer on top of name-level tools rules. Instead of just deciding _which_ tools are callable, you can constrain _what arguments_ are allowed on each call.
ArgConstraint fields
| Field | Type | Default | Description |
|---|---|---|---|
| isPath | boolean | false | Enables path-aware matching (containment check) instead of regex |
| allow_pattern | string \| string[] | — | Arg must match at least one pattern to pass |
| deny_pattern | string \| string[] | — | Arg is blocked if it matches any pattern; deny wins over allow |
| array_mode | 'all' \| 'any' | 'all' | For array-typed args: require all items to pass (all) or at least one (any) |
| case_sensitive | boolean | true | Regex flag; not applied to path-root matching |
| warn_only | boolean | false | Record the violation in the OTel span without blocking the call |
Path scoping with isPath: true
When isPath: true, patterns that look like directory roots are treated as containment checks rather than regex expressions:
| Pattern | Meaning |
|---|---|
| "./" or "." | Arg must resolve within process.cwd() |
| "/some/dir" | Arg must resolve within /some/dir |
| "~" / "${HOME}/projects" | Resolved to homedir |
| "${CWD}/data" | Resolved to cwd + /data |
The resolver uses path.resolve + fs.realpathSync to prevent ../ traversal and symlink escapes. Patterns that don't look like directory roots (e.g. "^/etc/.*") fall back to regex matching.
warn_only mode
Useful for gradual rollout: set warn_only: true to observe violations without blocking. The call is forwarded and the following attributes appear in the OTel span:
Switch to warn_only: false (the default) when you're ready to enforce.
Dot-notation for nested args
Use dot notation to constrain fields inside nested parameter objects:
---
Resource locks
Prevent concurrent tools/call invocations from racing on the same resource (e.g. two agents writing the same file at once). Configure a locks block per server, keyed by tool name.
Use cases
Concrete scenarios where resource locks solve a real coordination problem: