Drive simulators from your coding agent

rystic mcp is a local MCP server. Through it your coding agent starts a simulator, loads a scenario, seeds records, moves the clock, reads state and the calls and webhooks the simulator saw, diffs state against where it started, rolls back to a snapshot, saves the run as a test case and grades a later run against it, without writing a curl line.

Requires a current rystic CLI. If rystic help mcp reports an unknown command, run rystic self-update. New to Rystic? Install the CLI and sign in first.

The server speaks MCP over stdio: the client launches rystic mcp as a subprocess. Each tool is a thin wrapper over a CLI command or a control-plane route, so it answers what that command or route answers on your plan. A simulator it starts keeps running after the client exits; stop_twin or rystic stop ends it. The tool names say “twin”, meaning a simulator, and take the product names rystic list prints, such as stripe-twin.

Install

In Cursor or VS Code, one click adds the server: Add to Cursor, Add to VS Code or Add to VS Code Insiders. The editor opens and asks before it adds the entry. Like --print, the entry’s command is plain rystic, so the CLI must be on the editor’s PATH and signed in. When it is not on the PATH, use the command below.

One command writes the server entry into your client’s config:

rystic mcp install --client claude-code
# created /p/.mcp.json (claude-code, project scope)
# next: restart Claude Code in this directory and approve the project's rystic server when it asks

The entry’s command is the absolute path of the rystic binary you ran, so the client finds it even when rystic is not on its PATH. An existing config file is merged: other servers and keys stay. A file that is not valid JSON, comments and trailing commas included, is refused and left unmodified. A new user-scope file is created readable only by you (mode 0600).

rystic mcp install --client <claude-code|cursor|codex|vscode|windsurf> [--scope project|user] [--name rystic] [--command <path>] [--force] [--dry-run] [--print] [--json]
                   [--twin <simulator>] [--instance <name>] [--read-only] [--tools a,b,c]

Running it again with nothing to change, or with a different entry already there:

unchanged /p/.mcp.json (claude-code, project scope): "rystic" is already installed
rystic: /p/.mcp.json: already has a different "rystic" server; pass --force to replace it, or --name to add another (not modified)

It exits 2 on a bad flag, 9 on a conflicting entry without --force, and 1 when the existing file cannot be read or is not valid.

The last line of a write names the next step:

VS Code’s user scope is not written by rystic. code --add-mcp takes one entry with a name, not the whole file: the rystic entry from rystic mcp install --client vscode --print with "name": "rystic" added.

code --add-mcp '{"name":"rystic","type":"stdio","command":"rystic","args":["mcp"]}'

Or paste that entry, without name, under "servers" in the file MCP: Open User Configuration opens.

Configure by hand

Each block is a complete config file holding the rystic entry. Merge the entry into a file you already have.

Claude Code

{
  "mcpServers": {
    "rystic": {
      "type": "stdio",
      "command": "rystic",
      "args": [
        "mcp"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "rystic": {
      "type": "stdio",
      "command": "rystic",
      "args": [
        "mcp"
      ]
    }
  }
}

Codex

[mcp_servers.rystic]
command = "rystic"
args = ["mcp"]

VS Code

{
  "servers": {
    "rystic": {
      "type": "stdio",
      "command": "rystic",
      "args": [
        "mcp"
      ]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "rystic": {
      "command": "rystic",
      "args": [
        "mcp"
      ]
    }
  }
}

If the client cannot find rystic, set command to its absolute path (command -v rystic prints it).

Scope the server

By default rystic mcp serves every tool on every simulator running on this machine. Four flags narrow it:

rystic mcp [--twin <simulator>] [--instance <name>] [--read-only] [--tools a,b,c]

A bad scope flag exits 2 and names the valid choices. A scoped server’s instructions and its guide describe only what it serves, and a prompt that needs a tool it hides is hidden too. rystic mcp install takes the same flags and writes them into the client’s entry.

Call order

At startup the server hands the client instructions with the order of calls:

1. list_twins for the running instances, or start_twin, which returns the URL.
2. load_scenario, or seed, to set the starting state.
3. Your own code acts against that URL. The simulator answers as the real API does; you do not call it through MCP.
4. inspect_state, list_calls, list_sent and diff_state to read what happened.
5. save_test_case to keep the run, or check_test_case to grade it against a saved case.

start_twin, load_scenario, reset and restore_twin set the baseline diff_state compares against; set_clock and advance_clock control time; snapshot_twin and restore_twin let an agent try one path, roll back and try another. The guide resource walks each step.

Tools

Every tool except list_twins and start_twin takes instance: the instance’s name, its simulator’s name when that simulator runs one instance, or <twin>/<name>. save_test_case and check_test_case take instances, one per simulator, in its place for a case across simulators. list_twins names them.

Each tool declares MCP annotations. Read-only tools change no state. Destructive tools replace or drop state; idempotent ones are safe to repeat with the same arguments. Every tool is closed-world except start_twin, which may download a simulator release and checks your license.

diff_state compares against the state the instance had when start_twin started it, load_scenario loaded a scenario, reset reset it or restore_twin restored a snapshot. seed leaves that baseline in place, so seeded rows read as created. For an instance started outside the server, with rystic run say, the first diff_state stores the current state as the baseline and answers "baseline": "first_seen" with an empty diff.

Pages, filters and links

inspect_state, list_calls, list_sent and diff_state answer one page at a time: at most limit entries (default 50, at most 500) and about 20 KB. Pass a page’s next_cursor back as cursor for the next one. A cursor belongs to the baseline it was read against: after a reset, load_scenario or new baseline it is refused, and reading starts again without one.

Every page carries truncated. It is true when more pages remain or an entry was cut, and then hint names the exact call that gets the rest.

format sets how much of each entry a page carries:

In either format an entry over 12 KB is cut and marked.

Filters narrow a page; matched counts the entries they match across every page:

list_calls and list_sent also report total, every entry since the last reset. In list_sent, delivery sums up webhook delivery with its newest 20 attempts in results, and results_total counts every attempt the simulator reports. tail, which starts the page at the last N entries, still works but is deprecated in favor of cursor.

A state larger than one page also comes with state_uri and a resource link to rystic://instances/{twin}/{name}/state, the whole state uncut. A named view that is a file, or larger than a page, comes back as its size and the URL to fetch it from.

Snapshots

snapshot_twin with a name saves the instance’s state, clock, id counters and pending scheduled events and, when your plan includes network shaping, the network profile. A snapshot of the same name is replaced, and the result’s overwrote says so. Names take letters, digits, ., _ and -, at most 64. Without a name it lists the instance’s snapshots.

restore_twin resets the instance, then lands the snapshot, so ids minted after the restore continue where the snapshot left off. The restored state becomes diff_state’s baseline. A snapshot taken on another version of the simulator is refused with snapshot_version_mismatch.

The CLI keeps snapshots on this machine, per simulator and instance name. They survive stop_twin and a restart of the same instance on the same version.

A snapshot does not hold, so a restore does not bring back:

• the idempotency cache, so a replayed request makes a new object;
• the request-id counter;
• the calls and sent logs, which start empty;
• the webhook delivery queue;
• credential bindings;
• upload sessions;
• the rate limiter;
• the clock’s wall offset;
• scheduled events in full: only the pending events of the scenario’s own schedule come back, less any that uses a value a fired event bound, and a schedule loaded on its own replays from its start;
• built-in records deleted before the snapshot, which the reset brings back;
• whether a scenario installed the network profile: once restored, it stays through later resets.

snapshot_twin refuses an instance with a pending event that acts as a named caller (snapshot_unsupported) and a state too large to restore (snapshot_too_large). When the simulator refuses a snapshot after the reset, restore_twin fails with restore_failed and leaves the instance reset. On an older simulator release, every restore_twin result carries a warning: ids minted after the restore can collide with restored records, and per-account records can come back duplicated.

Save a run as a test case

save_test_case turns the run an agent just made into a regression test. It writes a grid cell directory, the same shape rystic grid writes: cell.json and, per simulator, twins/<grid name>/before.json, after.json, calls.json and egress.json, numbers exact. The grid name is the simulator’s name without -twin (linear for linear-twin), as rystic grade and the eval grid name it. Then it drafts the eval’s deterministic checks with rystic grade --draft into the cell’s eval.yaml, so rystic grade <cell_dir> passes on this run and fails on a later run that differs.

It returns {name, cell_dir, eval, draft, twins, notes}; each twins entry carries instance, twin, scenario, baseline, baseline_taken_at, seeded and counts (created, changed, deleted).

• Before is the instance’s baseline, from start_twin, load_scenario, reset, restore_twin or a first diff_state. Records seeded through seed after the baseline count as setup, not as the run’s. An instance with no baseline is refused with no_baseline.
• After is the state now, with the calls and sent log since the last reset.
• Rows a scenario’s own timeline seeds during the run count as the run’s changes.
• The draft expects each row the run created or changed, forbids any other creation, change, caller or method, and allows each deletion the run made. It is a starting point: trim the checks to what the task requires before keeping them.

Check a later run

check_test_case grades a new run against a saved case, as rystic grade does, with no model. After save_test_case, reset or load_scenario the instance, run the agent again, then call check_test_case with case set to the cell_dir or eval path save_test_case returned, or any eval file, as an absolute path. It captures the run since the baseline into a new cell, under out_dir or a new temp directory, grades it and writes its verdict.json.

A case directory’s checks/ YAML files are graded too. A script check is skipped, not run. The case’s world must name exactly the instances’ simulators, by full name (linear-twin) or grid name (linear).

Prompts

The server offers two prompts, which a client lists as prompts or slash commands:

Each walks the agent through start_twin, load_scenario or seed, the act step, list_sent, list_calls and diff_state, then save_test_case. twin takes a short name, stripe for stripe-twin. A simulator that is not running, installed or in your plan is refused with unknown_twin, and a scenario a running instance does not ship with unknown_scenario. Under --twin, the prompts take no twin argument.

Clients that support completion fill the arguments in:

• twin completes from the running simulators first, then the installed ones and those your license names, without a network call.
• scenario completes from a running instance of the simulator named in twin. With none running, it offers nothing.

Resources

{twin} is the full simulator name, such as stripe-twin, and {name} the instance’s name. Both template arguments complete from the running instances.

Example session

The agent’s prompt: “Test that our checkout code charges the customer once and sends one receipt webhook.”

start_twin {"twin": "stripe-twin", "scenario": "design_studio", "name": "stripe"}
→ {"instance": "stripe", "ref": "stripe-twin/stripe", "url": "http://localhost:53124", "port": 53124, "runner": "native", "baseline": "stored", …}

# the agent points its Stripe client at http://localhost:53124 and runs the checkout test

list_calls {"instance": "stripe", "method": "POST"}
→ {"calls": [the POST /v1/charges the test made, with its caller], "matched": 1, "truncated": false, …}

list_sent {"instance": "stripe"}
→ one charge.succeeded event

diff_state {"instance": "stripe"}
→ {"baseline": "start_twin", "counts": {"created": 1, "changed": 0, "deleted": 0}, "resources": […], "truncated": false, …}

advance_clock {"instance": "stripe", "duration": "48h"}
→ {"instance": "stripe", "clock": "…"}

save_test_case {"instance": "stripe", "name": "checkout-charges-once", "prompt": "Charge the customer once and send one receipt webhook."}
→ {"name": "checkout-charges-once", "cell_dir": "…/checkout-charges-once-…", "draft": "…", "twins": [{"instance": "stripe", "twin": "stripe-twin", "scenario": "design_studio", "counts": {"created": 1, "changed": 0, "deleted": 0}, …}], …}

# later, after a code change: load the scenario again, rerun the checkout test, grade the new run

load_scenario {"instance": "stripe", "name": "design_studio"}
check_test_case {"instance": "stripe", "case": "…/checkout-charges-once-…"}
→ {"result": "pass", "cell_dir": "…", "checks": [{"id": "nothing_destructive", "result": "pass", …}, …], …}

stop_twin {"instance": "stripe"}

Results and errors

Every tool declares an outputSchema describing its result shapes and the error object, and every result carries structuredContent that matches it, error results included. A successful result’s text content carries the same JSON, for a client that reads only text.

A failed call is an error result (isError: true), never a protocol error. Its structured content is {"error": {"code", "message", "cause", "fix", "retryable", …}}, and its text carries the same fields as lines. Extra fields appear where the code needs them, such as retry_after_ms, upgrade_url, twin_errors or snapshots. A malformed call is a bad_argument naming the argument: a wrong type, an unknown or missing argument, arguments that are not an object, a string over 64 KiB, or nesting over 64 levels.

A stdin line that is not one JSON-RPC message gets a JSON-RPC error, and the session goes on. That covers invalid JSON, a line nested over 10,000 levels, a line over 32 MiB, and any batch. Batches are not supported, so send each message on its own line. The error’s code is -32700 (parse error) or -32600 (invalid request). It carries the request’s id when the line names one and null otherwise, and each request in a batch gets its own error. The server logs each refused line to stderr. These are protocol errors, separate from the tool errors in the table below.

retryable says whether the same call, unchanged, may succeed later, and retry_after_ms, when present, how long to wait first. The table gives each code’s default. An error after a write that may have taken effect, such as a seed or advance_clock whose answer was lost, is not retryable, and its fix says how to check before repeating it. Tools that are safe to repeat (reset, load_scenario, set_clock) keep the default. rystic mcp -errors prints this table.

The docs MCP is a different server

Add both: the docs MCP answers how a simulator behaves, rystic mcp runs one. Agent quick start → Machine-readable surfaces shows the one-line install for the docs MCP.