Let Your AI Assistant Explore the Event Store with res-mcp

When you’re debugging with an AI assistant, half the work is giving it enough context. You copy event payloads into the chat, paste stream contents, look up IDs, then repeat the process every time you need another piece of information.

ruby_event_store-mcp removes that step. It’s the companion to the res CLI. Instead of you querying the event store from the terminal, your AI assistant does it for you through MCP tools. You ask questions in plain English, it reads the events itself.

The difference from copying the events into the chat yourself is that the assistant can ask follow-up questions on its own. If it needs to inspect another stream, load an aggregate’s history, or trace a correlation, it simply calls another tool. You stay in the conversation instead of switching between your AI client and a terminal.

Setup

Add the gem and install:

gem "ruby_event_store-mcp"

bundle install

That installs the res-mcp binary — but it doesn’t register anything with your AI client yet. The binary speaks MCP over stdio, launched from your app’s root, where — exactly like the res CLI — it loads config/environment.rb and reads your app’s Rails.configuration.event_store. There’s no HTTP endpoint to mount and nothing to deploy. Telling your client about it is a separate, one-time step — and every MCP client takes the same server definition, only the file it goes in changes.

Claude Code — drop a .mcp.json in your project root:

{
  "mcpServers": {
    "res": {
      "command": "bundle",
      "args": ["exec", "res-mcp"]
    }
  }
}

(or run claude mcp add res -- bundle exec res-mcp). Launched from the project directory, Claude Code runs the server there, so no cwd is needed. On the next launch it asks you to trust the project’s MCP server — approve it, then run /mcp to see res connected with its nine tools.

Claude Desktop — the same block, but with an explicit cwd pointing at your app’s root, in claude_desktop_config.json:

{
  "mcpServers": {
    "res": {
      "command": "bundle",
      "args": ["exec", "res-mcp"],
      "cwd": "/path/to/your/rails/app"
    }
  }
}

(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json.)

Other MCP clients — Cursor, Windsurf, Cline and the rest take the same mcpServers block in their own config file; VS Code’s built-in MCP uses a servers key with "type": "stdio" instead. The bundle exec res-mcp command is the portable part.

That’s the whole setup. No routes, no mounts, no credentials.

Ask questions, not commands

Once it’s connected you just talk to the assistant — no slash command, no skill. You ask in plain English and it decides which tools to call (the first call asks your permission; allowlist the res server to stop being asked).

The server gives the assistant nine read-only tools over your event store. You never call them by name — you ask a question, and the assistant picks the tools it needs. They cover three kinds of questions:

Browse streams and events

• stream_show — a stream’s event count, version, and first/last event
• stream_events — the events in a stream, filterable by type, time, or position
• event_show — one event in full, data and metadata
• event_streams — every stream a given event belongs to

Search and summarize

• recent — the most recent events across the whole store (“what just happened?”)
• search — events anywhere, filtered by type, time range, or stream
• stats — total counts and the unique event types present

Follow a process

• aggregate_history — the full event history of one aggregate instance (e.g. a single Fulfillment::Order)
• trace — the causation tree of everything sharing a correlation ID, so you can see where a multi-step flow stopped

Examples

For example, instead of browsing the streams yourself, you can simply ask:

“What just happened? Show the 20 most recent events.”

“Walk me through the history of Fulfillment::Order f47ac10b-58cc-4372-a567-0e02b2c3d479.”

“Are there any OrderPlaced events from the last hour without a matching OrderConfirmed?”

“Trace correlation 452fd6f0-e3a2-4716-bc8a-43bbcf2cae61 — where did the process stop?”

The assistant calls recent, aggregate_history, search, or trace behind the scenes, reads the results, and reasons over them — no copy-pasting event payloads into the chat, no switching to a Rails console mid-thought.

Why it’s safe to point at any app

Every tool uses the public event_store.* API — the same one your application uses through Rails.configuration.event_store. There’s no direct SQL access, no ActiveRecord internals, and no adapter-specific code.

The server is also intentionally read-only. Your AI assistant can inspect events, streams, and correlations, but it cannot append, link, or delete events. The worst it can do is answer your questions.