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

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

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

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

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

Config format

// 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 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:

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.

// 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;

ArgConstraint fields

Path scoping with isPath: true

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

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:

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

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:

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

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: