Show HN: Heimdall MCP – Transparent proxy that traces every MCP tool call with OpenTelemetry

[enmanuelmag]

Discussion Topic

Problem

I've been building with MCP servers (Claude Desktop, OpenCode, Cursor) and kept hitting the same wall: no visibility into what's actually happening inside.

Which tools are slow? Which ones fail silently? What inputs is Claude sending? How long did each call take?

Zero way to know, unless you dig through logs manually.

The solution

Built Heimdall, a transparent proxy that sits between your MCP client and any server, captures every JSON-RPC message as an OpenTelemetry span, and persists it to a storage backend you choose.

Key points:

• Zero modifications to target server
• Works with stdio, HTTP, SSE transports
• Pure JS/WASM, no native deps
• Storage: SQLite (local), Postgres, MySQL, or OTLP compatible backends
• TypeScript library + CLI wrapper

How use it

CLI — one-line mcp.json change

Before:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-server.js"]
    }
  }
}

After:

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

That's it. Restart Claude Desktop and every tool call starts being recorded.

For remote servers (HTTP/SSE):

{
  "command": "heimdall-mcp",
  "args": [
    "--store", "postgres://user:pass@localhost/mydb",
    "--target", "http://my-mcp-server.com/sse"
  ]
}

TypeScript Library

import { McpProxy } from '@cardor/heimdall-mcp'

const proxy = await McpProxy
  .create()
  .inbound({ transport: 'stdio' })
  .outbound({ transport: 'http', url: 'http://localhost:3001' })
  .store('sqlite://./traces.db')
  .build()

await proxy.start()

Custom interceptors too — for redacting sensitive fields, adding business logic, etc.

What gets recorded

Every interaction becomes a structured OTel span:

{
  "name": "mcp.tool.call",
  "attributes": {
    "gen_ai.tool.name": "search_documents",
    "mcp.duration_ms": 843,
    "mcp.status": "ok"
  },
  "events": [
    { "name": "request",  "body": { "query": "quarterly report" } },
    { "name": "response", "body": { "results": [...] } }
  ]
}

Stack

• Runtime: Node 22+ / Bun
• Storage: @libsql/client (SQLite WASM), postgres package, mysql2
• OTel: @opentelemetry/sdk-trace-node (official SDK, not custom)
• Zero native dependencies — pure JS/WASM

Repo & Links

• Docs: https://stack.cardor.dev/heimdall
• GitHub: https://github.com/enmanuelmag/heimdall-mcp
• npm: pnpm install -g @cardor/heimdall-mcp