io.github.solsolettidev/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

... View full README on GitHub