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 thewebsiteto view a full explanation, examples, and other tools!

- @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

- 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

- 1. Start Jaeger
- 2. Add--otlpto your config
- 3. Open Jaeger UI

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

The proxy always exposesstdioto 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.

npm install -g @cardor/heimdall-mcp # or as a project dependency npm install @cardor/heimdall-mcp

Drop aheimdall.config.tsin 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.

Both are optional. If neither exists, the proxy stays fully transparent (backward compatible).

// heimdall.config.ts import type { HeimdallConfig } from '@cardor/heimdall-mcp'; export default { // default: applies to any server without an explicit entry default: { tools: { allow: [''], deny: [] }, }, // servers: keyed by --server-name (or serverInfo.name from initialize response) servers: { filesystem: { tools: { allow: ['read_file', 'list_directory', 'search_files'], deny: ['write_file', 'create_file', 'delete_file', 'move_file'], }, resources: { allow: [''], deny: ['file:///etc/', 'file:///root/'], }, }, database: { tools: { allow: ['query', 'describe_table', 'list_tables'], deny: ['execute', 'drop_table', 'truncate'], }, }, }, } satisfies HeimdallConfig;

TypeScript configs are loaded viajitiwithout pre-compilation. Also works as.js,.mjs,.cjs, or.json.

// heimdall.config.ts export default { servers: { filesystem: { tools: { allow: ['read_file', 'list_directory'] }, toolPolicies: { // '' applies to every tool (merged first; tool-specific entries override) '': { args: { path: { isPath: true, deny_pattern: ['\\.env$', '\\.pem$'] }, }, }, read_file: { args: { // scope path to the current working directory path: { isPath: true, allow_pattern: './' }, // allow only safe encodings encoding: { allow_pattern: ['utf-8', 'utf8', 'ascii'] }, }, }, }, }, }, } satisfies HeimdallConfig;

WhenisPath: true, patterns that look like directory roots are treated as containment checks rather than regex expressions:

The resolver usespath.resolve+fs.realpathSyncto prevent../traversal and symlink escapes. Patterns that don't look like directory roots (e.g."^/etc/.") fall back to regex matching.

policy.arg_warning = true policy.arg_warning_field = "path" policy.arg_warning_message = "Tool arg 'path' is denied by policy"

toolPolicies: { my_tool: { args: { 'options.target': { isPath: true, allow_pattern: './' }, }, }, }

// heimdall.config.ts export default { servers: { filesystem: { tools: { allow: ['read_file', 'write_file'] }, locks: { write_file: { resource: 'path', ttl: 30_000 }, run_migration: { resource: 'db-migration', onConflict: 'warn' }, }, }, }, } satisfies HeimdallConfig;

heimdall-mcp --store sqlite://./traces.db --lock-store postgres://user:pass@host/db -- node server.js heimdall-mcp --store sqlite://./traces.db --lock-store mysql://user:pass@host/db -- node server.js

// heimdall.config.ts export default { hosts: { 'claude-code': { locks: { Write: { resource: 'file_path', ttl: 30_000 }, Edit: { resource: 'file_path', ttl: 30_000 }, MultiEdit: { resource: 'file_path', ttl: 30_000 }, NotebookEdit: { resource: 'file_path', ttl: 30_000 }, }, }, }, } satisfies HeimdallConfig;

bin/hooks/claude-pretooluse.jsis a real, workingPreToolUsehook script for Claude Code. On every invocation it readstool_name/tool_inputfrom stdin, reloadsheimdall.config.fresh from disk (local + global, merged — never cached), matches the tool againsthosts['claude-code'].locks, resolves the lock resource from the matched rule'sresourceargument (canonicalizing filesystem paths the same wayLockRuleresource resolution does elsewhere in this doc), and attempts to acquire an exclusive lock against the same default SQLite lock store used by the proxy (~/.config/heimdall/locks.db). If the lock is free, the call is allowed. If it's held by another holder, the call is denied with a human-readable reason. The hook always exits0and fails open (silently allows) on any unexpected error — a bug in the hook must never brick a Claude Code session.

For the fullPreToolUsehook contract investigation and unresolved edge cases behind this implementation, seeSPIKE_CLAUDE_HOOKS.md.

{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "node /absolute/path/to/node_modules/@cardor/heimdall-mcp/bin/hooks/claude-pretooluse.js" } ] } ] } }

- APostToolUsecompanion hook to release the lock once the tool call completes. Locks acquired by this hook are released only via TTL expiration (default 30s, or the rule's configuredttl), not immediately after the tool finishes — a known limitation, not a bug.

src/plugins/opencode-heimdall.ts(compiled todist/plugins/opencode-heimdall.js, re-exported bybin/plugins/opencode-heimdall.js) is an OpenCode plugin implementing thetool.execute.beforehook, following the same config-loading, host-matching, and lock-acquisition logic as the Claude Code hook above — but matched againsthosts['opencode']instead ofhosts['claude-code']. There is no built-in default policy for OpenCode yet (noOPENCODE_DEFAULT_HOST_POLICYequivalent toCLAUDE_CODE_DEFAULT_HOST_POLICY), so this plugin allows every tool call until you explicitly configurehosts.opencode.locksyourself, e.g.:

// heimdall.config.ts export default { hosts: { opencode: { locks: { write: { resource: 'filePath', ttl: 30_000 }, }, }, }, } satisfies HeimdallConfig;

For the fulltool.execute.beforecontract investigation, deny-mechanism verification method, and unresolved open questions behind this implementation, seeSPIKE_OPENCODE_HOOKS.md.

opencode.jsoncis genuine JSONC — real configs can and do contain//comments and trailing commas. This installer usesjsonc-parser(the same library VS Code uses internally to editsettings.json) to compute a surgical text edit that appends the new array entry, rather than a plainJSON.parse/JSON.stringifyround-trip — so existing comments, trailing commas, and formatting elsewhere in the file are preserved. (Comments attached directly to the appended array entry's own line may shift by one entry as a side effect of the array-insertion edit; comments elsewhere in the file are untouched.)

// opencode.jsonc { "plugin": ["/absolute/path/to/node_modules/@cardor/heimdall-mcp/bin/plugins/opencode-heimdall.js"] }

Confidence caveat on the registration mechanism itself.Thepluginarray's support for bare absolute file-path entries (nopackage.json, no npm packaging) was verified with HIGH confidence against OpenCode's real fetched source (sst/opencode,packages/opencode/src/plugin/shared.ts'sisPathPluginSpec()/resolvePathPluginTarget()) cross-checked against the actually-installed OpenCode binary's embedded strings — seeSPIKE_OPENCODE_HOOKS.mdfor the verification method. That said, like the plugin's deny mechanism documented below, this hasnot been validated end-to-end against a live OpenCode process actually loading and using the plugin— treat the registration step, same as the plugin itself, as experimental until independently verified against a real OpenCode session.

Confidence caveat — read before relying on this for security.OpenCode's own published documentation fortool.execute.beforewas not locally available during development (seeSPIKE_OPENCODE_HOOKS.md), and itsoutputtype is only{ args: any }— there is no confirmeddeny/block/statusfield on this hook (contrast OpenCode's ownpermission.askhook, which does have a typedstatus: "ask" | "deny" | "allow"field). This plugin denies a conflicting lock bythrowing anErrorfrom the hook callback, on the assumption that a rejected promise aborts the tool call — the conventional pattern for void-returning before-hooks, and nothing found contradicts it, butthis has not been confirmed against a live OpenCode session. If that assumption is wrong, this plugin will silently fail to block anything while still appearing to deny (it throws; whether OpenCode's runtime actually blocks the tool call on that throw is unverified). Treat this integration as experimental until independently verified.

- Atool.execute.aftercompanion to release the lock once the tool call completes — same TTL-only-release limitation as the Claude Code hook above.
- Live confirmation of the deny mechanism described above, and of theinit --hooks opencoderegistration mechanism actually being loaded by a live OpenCode process.

A single, canonical list of everything not yet implemented, or not yet independently verified, across resource locks and host policies. Each item also has an inline note near the relevant section above with more local context.

- No read-mode locking.Every lock is acquired in exclusive'write'mode;LockRuleSchemahas nomodefield yet, even though theLockStoretype defines'read' | 'write'. SeeSemanticsabove.
- No lock support forBash.Bashis deliberately excluded fromCLAUDE_CODE_DEFAULT_HOST_POLICYbecause arbitrary shell commands have no single stable "resource" argument to lock on — locking it would be either meaningless or dangerously coarse.
- No automatic release on tool completion (Claude Code).ThePreToolUsehook has noPostToolUsecompanion to release the lock immediately once the tool call finishes. Locks it acquires are released only via TTL expiration (default 30s, or the rule's configuredttl) — not a bug, but a known limitation.
- No automatic release on tool completion (OpenCode).Same limitation as Claude Code above — thetool.execute.beforeplugin has notool.execute.aftercompanion; release is TTL-only.
- OpenCode deny mechanism unverified end-to-end.The plugin denies a conflicting lock by throwing anErrorfrom thetool.execute.beforecallback, on the assumption that a thrown error aborts the tool call. This has not been confirmed against a live OpenCode session. SeeSPIKE_OPENCODE_HOOKS.md.
- OpenCodeinit --hooks opencoderegistration unverified end-to-end.The registration mechanism (appending a bare file path toopencode.jsonc'spluginarray) was verified with high confidence against OpenCode's source and installed binary, but has not been validated against a live OpenCode process actually loading and using the plugin. SeeSPIKE_OPENCODE_HOOKS.md.

For the full hook-contract investigation behind the Claude Code caveats above, seeSPIKE_CLAUDE_HOOKS.md. For the OpenCode plugin registration/deny-mechanism investigation, seeSPIKE_OPENCODE_HOOKS.md.

[TelemetryInterceptor] → [PolicyInterceptor] → [ForwardInterceptor] ↑ blocks here, returns JSON-RPC error

{ "jsonrpc": "2.0", "id": 42, "error": { "code": -32001, "message": "Tool 'write_file' is not permitted by policy" } }

The OTel span is still recorded — withpolicy.blocked = trueandmcp.error.code = -32001— so you get a full audit trail of what was attempted and blocked.

tools/list,prompts/list, andresources/listresponses are also filtered: denied entries are removed before the client sees them. The agent never learns a denied tool exists.

Atools/callblocked by an activeresource lockreturns a distinct JSON-RPC error with structured holder info inerror.data:

{ "jsonrpc": "2.0", "id": 42, "error": { "code": -32600, "message": "Resource '/repo/file.txt' is locked (requested by tool 'write_file')", "data": { "resource_key": "/repo/file.txt", "held_by": "a1b2c3d4...", "expires_at": 1735689600000 } } }

{ "mcpServers": { "filesystem": { "command": "heimdall-mcp", "args": [ "start", "--store", "sqlite://~/.heimdall/traces.db", "--server-name", "filesystem", "--", "npx", "@modelcontextprotocol/server-filesystem", "/home/user/projects" ] } } }

--server-nameoverrides the name from the server'sinitializeresponse — for both policy lookup and themcp.server.nameOTel attribute.

import { ProxyBuilder } from '@cardor/heimdall-mcp'; import type { HeimdallConfig } from '@cardor/heimdall-mcp'; const policy: HeimdallConfig = { servers: { filesystem: { tools: { deny: ['write_file', 'delete_file'] }, }, }, }; const proxy = await ProxyBuilder.create() .inbound({ transport: 'stdio' }) .outbound({ transport: 'stdio', command: 'npx', args: ['@modelcontextprotocol/server-filesystem', '/tmp'] }) .store('sqlite://./traces.db') .config(policy) // attach policy .serverName('filesystem') // match config key .build(); await proxy.start();

Mode 1 — CLI wrapping a subprocess (stdio)

The MCP client thinks it is talking toheimdall-mcp. The proxy spawns the real server as a child process and forwards all messages.

mcp.json/ Claude Desktop configuration:

{ "mcpServers": { "my-server": { "command": "heimdall-mcp", "args": [ "--store", "sqlite://~/.mcp-traces/traces.db", "--", "node", "my-server.js" ] } } }

The--separator divides heimdall-mcp flags from the real server command. Everything after it is executed as a subprocess.

{ "mcpServers": { "filesystem": { "command": "heimdall-mcp", "args": [ "--store", "sqlite://~/.mcp-traces/traces.db", "--", "npx", "@modelcontextprotocol/server-filesystem", "/tmp" ] } } }

{ "mcpServers": { "my-server": { "command": "heimdall-mcp", "args": [ "--store", "postgres://user:pass@localhost:5432/traces", "--", "node", "my-server.js" ] } } }