RelayOrb docs

Install

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

• Installs to ~/.local/bin. Set RELAYORB_INSTALL_DIR to change it, or RELAYORB_VERSION to pin a release.
• npm (any OS): npm install -g @khalidsaidi/relayorb, or npx @khalidsaidi/relayorb without installing.
• Windows: download the zip from GitHub Releases.
• From source: cargo install --git https://github.com/khalidsaidi/relayorb relayorb

Record

Put relayorb record -- in front of any stdio MCP server command, wherever your agent's config starts the server. RelayOrb launches the real server, forwards every byte unchanged in both directions, and saves each JSON-RPC message with its timestamp. Each time the agent starts the server, a new session is recorded.

relayorb record --name fs -- npx -y @modelcontextprotocol/server-filesystem ~/notes

Inspect

relayorb list shows sessions, newest first. relayorb show <session> prints every request with its latency and outcome: ok, error (JSON-RPC error), tool error (isError: true), or no answer. Add --json for the full params and responses. Anywhere a session is expected you can use its --name (the newest session with that name), its id, or a unique id prefix.

relayorb list
relayorb show fs
relayorb show fs --json | jq '.calls[] | {label, status, latency_ms}'

Replay

relayorb replay <session-or-file> acts as the MCP server and answers from the recording, so agents and tests run offline with the same answers every time. Requests are matched by method and params (key order and _meta ignored), then by method and tool name, in recorded order. Anything never recorded gets a JSON-RPC error instead of a hang.

relayorb export fs -o fixtures/fs.json
relayorb replay fixtures/fs.json

Check (CI)

relayorb check <session-or-file> -- <server command> starts the server, repeats the handshake, re-sends each recorded request, and diffs the answers. Exit code 0 means everything matched, 1 means an answer changed, and 2 means the server couldn't start or initialize. Use --ignore-key <name> (repeatable) for fields that change every run, and --timeout <seconds> for slow servers.

relayorb check fixtures/fs.json --ignore-key timestamp -- npx -y @modelcontextprotocol/server-filesystem ./testdata

Diff

relayorb diff <run-a> <run-b> compares two runs call by call and reports the first point where they diverged: a different tool or method, the same tool with different arguments, or the same call getting a different answer. The header shows each run's agent build, server version, and protocol version, taken from the recorded initialize. Use name~1 for the run before the newest one with that name. --all lists every difference, --ignore-key skips noisy fields, and --json gives machine-readable output for grouping many runs. Exit code 0 means the runs match and 1 means they diverge.

relayorb diff notes~1 notes
relayorb diff run-a.json run-b.json --json | jq '.first_divergence'

Command reference

• 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.

• relayorb delete <session>

  Delete a recorded session.

Storage and privacy

Recordings are stored in ~/.relayorb/recordings.db (SQLite). Override it with --db <path> or RELAYORB_DB. RelayOrb makes no network calls of its own. Recordings contain everything the tools received and returned, including file contents and secrets passed as arguments, so review exported session files before sharing or committing them.

RelayOrb supports the stdio transport used by local MCP servers. Streamable HTTP servers aren't supported yet. See the test results for which servers, agents, and platforms have been verified.