Nats Trail

Give an AI agent safe access to your production event bus.

A web UI, a CLI and an MCP server over one bounded query engine — so humans and agents debug NATS from the same source of truth.

Why this exists

Every NATS GUI answers *"what is in this stream?"*. That is the easy question.

The hard question in an event-driven system is "why did this one flow fail?" — and answering it means following a single request_id across four streams, three services and a dead-letter subject. Today you do that by hand, with a terminal per stream.

NATS Trail answers that question directly, and exposes the answer to agents as a typed, bounded, read-only tool contract — so you can point Claude at production and ask.

nats-trail trace --request-id req-0001d --limit 20

Or, from an agent: *"Why did the refresh for s3-events fail?"* — and it lands on the message that actually broke, with the retry state and the correlation ids already extracted:

The part nobody else does

There are several NATS MCP servers. They shell out to the nats CLI, return raw dumps, and expose publish and delete while describing themselves as read-only.

NATS Trail treats the agent surface as a contract, not a wrapper:

"Read-only" here means unreachable, not disabled

NATS Trail *can* write: publish, purge, delete messages, consumers and streams. Those live behind /api/mutate, reachable from the UI and the CLI.

executeMcpTool() receives an McpRuntimeData interface that exposes only read functions. There is no disabled publish behind a feature flag — there is no `publish` to call. A misconfigured environment variable cannot purge your production stream, because the code path does not exist. CLI write commands additionally refuse to run under --agent, and the test suite reads the source to assert none of this has been quietly undone.

This is the only reason it is reasonable to hand an agent a prod context.

Install

npx nats-trail serve

Open http://127.0.0.1:4000 — one process serves the UI and the API.

Prefer containers? The compose file brings up NATS Trail next to a JetStream-enabled server:

docker compose up

On Kubernetes, the Helm chart declares contexts and correlation keys in values.yaml and keeps credentials in a Secret:

helm install nats-trail ./charts/nats-trail -f my-values.yaml

See charts/nats-trail/README.md for declarative config, why it is a single-replica StatefulSet, and how authentication is delegated to whatever fronts the service.

From source

git clone https://github.com/solsolettidev/nats-trail

cd nats-trail npm install npm start

Development with hot reload

npm run dev

• UI: http://localhost:5173 (proxies /api and /ws to the bridge)
• API bridge: http://localhost:4000

npm run dev runs the TypeScript watcher, the API bridge and the UI together.

Requirements: Node.js >= 22 (for the built-in SQLite used by the correlation index) and a reachable NATS server (nats-server -js is fine).

Use it as an MCP server

Point any MCP client at the stdio server. For Claude Code:

claude mcp add nats-trail -- npx -y @nats-trail/mcp

Or wire it manually:

{

"mcpServers": { "nats-trail": { "command": "natstrail-mcp", "env": { "NATS_TRAIL_API": "http://127.0.0.1:4000", "NATS_TRAIL_TOKEN": " " } } } }

Twenty-five read-only tools, all returning the same envelope:

# start here when the topology is unknown

natstrail.discover_subjects subjects that carry traffic + inferred payload shapes natstrail.get_health_summary what is broken right now, ranked natstrail.reconstruct_flow the causal chain for one request_id natstrail.enrich_incident flat context for an incident: flow + dead letters + health

messages

natstrail.search_messages natstrail.get_message_detail natstrail.trace_by_request_id natstrail.trace_by_correlation_id natstrail.search_dlq natstrail.run_filter

topology

natstrail.list_streams natstrail.get_stream_info natstrail.list_consumers natstrail.list_kv_buckets natstrail.list_kv_keys natstrail.get_kv_history natstrail.list_object_buckets natstrail.list_objects

operations

natstrail.get_server_health natstrail.list_server_connections natstrail.list_contexts natstrail.get_connection_status natstrail.list_filters natstrail.list_audit natstrail.enrich_sentry

See docs/mcp-agent.md.

Three surfaces, one engine

                 ┌──  Web UI          explore visually, save filters

Query Engine ───┼── CLI scripts, pipelines, humans in a terminal (core) └── MCP + HTTP API agents, Sentry, dashboards

A filter you save in the UI is the same filter nats-trail filter run executes, and the same one natstrail.run_filter hands an agent. Configure a context once; use it everywhere.

• `packages/ui` — React + Vite. Presentation only.
• `packages/server` — Express + WebSocket bridge. Owns connections and credentials.
• `packages/core` — the Query Engine: envelopes, limits, truncation, filters, error normalization.
• `packages/cli` — the nats-trail binary: query commands, serve, and an interactive shell.
• `packages/mcp` — tool contracts and the stdio server.

See docs/architecture.md.

Features

Inspect — context selector (local / dev / staging / prod) with a prod confirmation gate, live subject subscription, JSON pretty print with tree view and in-payload search, stream and consumer browsing, auto-detected DLQ panel.

JetStream — streams, subjects, counts and consumer health. and a selected message rendered as a JSON tree"> NATS Core — live subject subscription with filters.

DLQ — auto-detected dead letters with reason and origin.

Viewer — tree, raw, search, fullscreen, copy-path.

Understand — subject discovery infers payload shapes from real traffic, flow reconstruction turns one request_id into a causal chain, and the health summary ranks what is actually broken.

Query — bounded stream scans with cursors and time windows, filters by subject, date, text and JSON event type, saved filters shared across all three surfaces. Binary payloads (protobuf, msgpack) are detected and shown as hex dumps rather than mojibake.

Browse — KV buckets with per-key revision history including deletes, Object Store metadata, and server health from the monitoring port (varz / jsz / connz).

Change — publish, request/reply, purge, and delete messages, consumers and streams, from the UI and the CLI, behind confirmation. Never from the agent surface.

Integrate — read-only HTTP API under /api/integration, bearer tokens with per-token audit identity, and POST /api/integration/enrich/sentry to attach NATS context to an error without exposing credentials.

Full list in docs/features.md · CLI reference in docs/cli.md.

Security

Credentials live in contexts stored locally under data/ (git-ignored). The UI never holds the NATS connection — it always goes through the bridge, which pools one connection per context.

The server binds to 127.0.0.1 by default because /api/contexts and /api/connect are unauthenticated local endpoints. To expose the Integration API and the WebSocket, configure bearer tokens with NATS_TRAIL_TOKENS=name:token or data/tokens.json; audit entries then record the authenticated token name per call.

A shared deployment has no built-in login on purpose: identity comes from whatever fronts the service (an ingress with OIDC, oauth2-proxy, Cloudflare Access, Teleport or network isolation), so no passwords are stored here. Contexts declared through NATS_TRAIL_CONFIG resolve ${VAR} from the environment and cannot be edited or deleted through the API.

Roadmap

Tracked in docs/roadmap.md.

Phases 0–3 are complete. npm release · KV and Object Store browsing · server health · binary payload handling · nkey auth · subject discovery · flow reconstruction · health summary · incident enrichment for Sentry, Grafana, Datadog and PagerDuty · stream, consumer and KV administration · MCP registry listing · indexed correlation search · declarative config and a Helm chart. All writes are human-only, behind scoped tokens and audited with their arguments.

Next: cluster awareness, deliberately deferred rather than pending work.

Deliberately out — protobuf and msgpack *field* decoding (needs a per-subject schema registry) and competing with NUI on GUI breadth. See docs/roadmap.md.

Planned, not started: for teams that explicitly want agent wri