Do I need RelayOrb just to see what my agent did?

Usually not. Claude Code, Cursor, and other agent apps already show tool calls. RelayOrb is for when you need the raw protocol messages, a repeatable test, or an offline replay.

How do I see the raw MCP messages my agent sent?

Wrap the MCP server command with relayorb record -- in your agent's config, use the agent, then run relayorb show . You get every tool call with its arguments, result, latency, and errors.

How do I test an MCP server?

Record a real session, export it as a JSON fixture, and run relayorb check -- in CI. It re-sends the recorded calls and fails if any answer changed.

Which MCP clients does RelayOrb work with?

Any client that starts MCP servers over stdio, including Claude Code, Claude Desktop, Cursor, OpenAI Codex, and VS Code.

Does RelayOrb send my data anywhere?

No. It has no account, no cloud, and no telemetry. Recordings stay in a local SQLite file at ~/.relayorb/recordings.db.

Yes. It is open source under the Apache-2.0 license, with prebuilt binaries for macOS, Linux, and Windows.

Free · Open source · Runs on your machine

RelayOrbTurn real AI agent sessions into tests for MCP servers.

RelayOrb records the messages between an AI agent (Claude Code, Cursor, Codex, Claude Desktop) and an MCP server. Save a recording, and RelayOrb can check every new build of the server against it, or replay it so agent tests run without the real server.

Install

curl -fsSL https://relayorb.com/install.sh | sh

macOS and Linux: the script above downloads the prebuilt binary to ~/.local/bin.
npm (any OS): npm install -g @khalidsaidi/relayorb, or run it without installing via npx @khalidsaidi/relayorb.
Windows: download the zip from GitHub Releases.
From source: cargo install --git https://github.com/khalidsaidi/relayorb relayorb

View on GitHub Quickstart

Tested on Linux, macOS, and Windows against 7 real MCP servers and 10 stress tests. See the results

Who it's for

You build an MCP server

The problem: A refactor quietly changes a tool's output or schema, and agents that relied on it start failing. Unit tests don't catch it because they don't speak the protocol.

RelayOrb: Record one real session with an agent, commit it, and run relayorb check in CI. Every build is compared against the recording, and the job fails if any answer changed.

relayorb check fixtures/session.json -- node dist/server.js

You build an agent or app that uses MCP tools

The problem: Your tests hit real tools: they need API keys, cost money, are slow, and return different answers each run.

RelayOrb: Replay a recorded session instead of the real server. Your agent gets the same answers every time, offline, with no keys.

relayorb replay fixtures/session.json

A tool call went wrong and you need the raw messages

The problem: The server hung, returned something malformed, or the agent sent bad arguments, and your agent app only shows a summary.

RelayOrb: Record the session and read the exact JSON-RPC traffic: every request, response, error, and how long each took. Compare it with a run that worked to see the first call where they went different ways.

relayorb diff my-server~1 my-server

When you don't need it

You just want to see what your agent did once. Claude Code, Cursor, and other agent apps already show tool calls and results.
Your MCP server is remote (HTTP). RelayOrb works with local servers that run over stdio, which is how most MCP servers run today.

How it works

Record: put relayorb record -- in front of the server command in your agent's config, and use the agent normally.
Save: relayorb export writes the session to a JSON file you can commit.
Use it: relayorb check tests a server build against it, relayorb replay stands in for the server, and relayorb show lets you read it.

Point your agent config at relayorb instead of the MCP server. RelayOrb starts the real server, relays traffic both ways, and records each request and response with its timing.

Agent

Your MCP client

Claude Desktop, Claude Code, Cursor, or any MCP client

stdio

Recorder

relayorb record

Relays every JSON-RPC message unchanged and keeps a copy

Local SQLite file

~/.relayorb/recordings.db

stdio

Tools

MCP server

Any MCP server that runs over stdio, unmodified

Record your agent

Wrap any stdio MCP server by putting relayorb record -- in front of its command. This works in Claude Desktop, Claude Code, Cursor, and any other MCP client config.

MCP client config (e.g. claude_desktop_config.json)

{
  "mcpServers": {
    "filesystem": {
      "command": "relayorb",
      "args": ["record", "--name", "fs", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Then use the agent as usual and run relayorb list and relayorb show fs to see what happened.

Commands

relayorb record [--name NAME] -- <mcp server command...>
Wrap any stdio MCP server. Point your agent config at relayorb instead of the server; every request and response is recorded.
relayorb list
List recorded sessions.
relayorb show <session> [--json]
Show a session timeline: method, tool name, latency, and errors for each message.
relayorb export <session> -o session.json
Save a session as a JSON fixture you can commit to your repo.
relayorb replay <session-or-file>
Act as a fake MCP server that answers from the recording: no API keys, no network, same answers every time.
relayorb check <session-or-file> -- <mcp server command...>
Re-send the recorded tool calls to the live server and diff the answers. Exits non-zero on a mismatch.
relayorb diff <run-a> <run-b>
Compare two runs and show the first tool call where they diverged: a different tool, different arguments, or a different answer, plus each run's agent and server versions.

Recordings live in ~/.relayorb/recordings.db. Set RELAYORB_DB to use a different file.

Regression-test MCP servers in CI

Export a known-good session as a fixture and commit it. In CI, relayorb check re-sends the recorded tool calls to the live server, diffs the answers, and exits non-zero on a mismatch.

CI step

# 1. Record a session once, then save it as a fixture
relayorb export fs -o fixtures/fs-session.json

# 2. In CI: replay the recorded tool calls against the live server
#    and fail the build if any answer changed
relayorb check fixtures/fs-session.json -- npx -y @modelcontextprotocol/server-filesystem ./testdata

Need the opposite? relayorb replay fixtures/fs-session.json stands in for the real server so agent tests run offline with the same answers every time.

Guides

Set up MCP servers in your agent and see exactly what they do.

FAQ

What is RelayOrb?: A free, open-source tool that turns real AI agent sessions into tests for MCP servers. It records the messages between an agent (Claude Code, Cursor, Codex, Claude Desktop) and an MCP server, then lets you check new server builds against the recording, replay it so agent tests run offline, or read the raw messages.
Do I need RelayOrb just to see what my agent did?: Usually not. Claude Code, Cursor, and other agent apps already show tool calls. RelayOrb is for when you need the raw protocol messages, a repeatable test, or an offline replay.
How do I see the raw MCP messages my agent sent?: Wrap the MCP server command with relayorb record -- in your agent's config, use the agent, then run relayorb show <name>. You get every tool call with its arguments, result, latency, and errors.
How do I test an MCP server?: Record a real session, export it as a JSON fixture, and run relayorb check <fixture> -- <server command> in CI. It re-sends the recorded calls and fails if any answer changed.
Which MCP clients does RelayOrb work with?: Any client that starts MCP servers over stdio, including Claude Code, Claude Desktop, Cursor, OpenAI Codex, and VS Code.
Does RelayOrb send my data anywhere?: No. It has no account, no cloud, and no telemetry. Recordings stay in a local SQLite file at ~/.relayorb/recordings.db.
Is RelayOrb free?: Yes. It is open source under the Apache-2.0 license, with prebuilt binaries for macOS, Linux, and Windows.