MCP tool reference

The tools, prompts, resources and error codes below are generated from the released rystic mcp, as an MCP client lists them. Their text is the CLI’s own, so a “twin” is a simulator and a “world” is a scenario. Connect your coding agent shows how to install the server, scope it and drive a simulator with it.

Tools

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. Open-world tools reach beyond this machine, to download a simulator release, check your license or sign you in.

advance_clock

Move the instance’s clock by whole seconds, forward or (negative) back: give seconds or duration, exactly one. Events fire as the clock passes them. Returns the clock the twin then reads.

check_test_case

Grade the instance’s run since its baseline against a saved test case’s checks, as rystic grade does, with no model: capture the run as save_test_case does, with the twin’s event timeline as world.json, into a new grid cell dir holding the case’s eval, grade it, and write its verdict.json. case is the cell_dir or eval path save_test_case returned, or any eval file; a case dir’s checks/ YAML files are graded too. The case’s world must name exactly the instances’ twins, by twin name or by grid name (the twin name without -twin). Returns result (pass, fail, error, or incomplete when every graded check passed but one was skipped), reason, cell_dir, notes, and per check its id (nothing_destructive, checks[i] in eval order, then checks/<file>[j]), result (pass, fail, error or skipped), detail and, for a failure, the rows behind it. A script check is skipped, never run. To check a new run, reset or load_scenario the instance, run the agent, then call this.

diff_state

Compare the instance’s state now with its baseline, the state it had when start_twin started it, load_scenario loaded a scenario or reset cleared it: rows created, changed (each changed field’s JSON Pointer path, before and after) and deleted, per resource. register narrows it to one register. counts cover every row that differs (in register, when given); resources holds a page of them, in resource, then created, changed and deleted, then key order. concise (the default) gives created and deleted rows with string values over 256 bytes cut, and changed rows as their fields; detailed adds each changed row’s state and cuts only a row over 12 KB. A cut row is marked truncated. A page holds at most limit rows and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest. An instance with no baseline (started outside this server) gets one on the first call, which answers baseline first_seen and an empty diff.

inspect_state

Return the instance’s state (GET /_rystic/inspect) a page at a time: state is resource, then row key, then row, in key order. register narrows it to one register, and key with it to one row; matched counts the rows they match. concise (the default) cuts string values over 256 bytes and lists those rows in cut_rows; detailed cuts only a row over 12 KB. A page holds at most limit rows and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest. A state larger than one page also carries state_uri, a resource link to the whole state uncut. view asks for one of the twin’s named views instead, such as identities, answered as {view, result}; a view that is a file, or larger than a page, comes back as its size and the URL to fetch it from.

list_calls

List the API calls the instance served since its last reset (GET /_rystic/calls), oldest first, a page at a time; method, path_prefix, status and actor filter them. concise (the default) gives each call’s seq, at, method, path, status and actor; detailed gives the twin’s whole record. total counts every call since the reset, matched the kept calls the filters match. A page holds at most limit calls and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest.

list_scenarios

List the named starting worlds the instance’s twin ships (GET /_rystic/scenarios), each with a summary.

list_sent

List what the instance sent since its last reset: webhooks, emails and other outbound effects (GET /_rystic/egress), oldest first, a page at a time. Each event names its effect and type as the twin’s model calls them; no field marks a webhook apart from an email, so filter on effect or type. concise (the default) gives each event’s seq, effect, type and owner; detailed adds the payload. delivery, when present, sums up webhook delivery with its newest 20 attempts in results (results_total counts the attempts the twin reports). total counts every event since the reset, matched the kept events the filters match. A page holds at most limit events and about 20 KB, and an event over 12 KB is cut and marked truncated. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest.

list_twins

List the twin instances running on this machine: each one’s name, twin, version, URL, runner and status from a live probe. Call it first to find the instance the other tools take.

No arguments.

load_scenario

Replace the instance’s state with a named scenario, keeping the twin’s built-in records (POST /_rystic/scenario). The loaded state becomes diff_state’s baseline.

reset

Reset the instance to the twin’s built-in records, dropping scenario and seeded state (POST /_rystic/reset), clearing its calls and sent log. The reset state becomes diff_state’s baseline.

restore_twin

Roll the instance back to a snapshot snapshot_twin saved: reset it, then land the snapshot’s state, clock, id counters, pending scheduled events and network shaping, 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 twin is refused. On a twin release older than the seed round trip, which holds no id counters, every result carries a warning: ids minted after the restore can collide with restored records, and per-account records can come back duplicated. A snapshot does not hold, so a restore does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they 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 world’s own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). A pending default-actor call on a route that needs a credential binding fails the restore after the reset, which leaves the instance reset.

save_test_case

Save the instance’s run since its baseline as a test case: write a grid cell dir (before is diff_state’s baseline, after the state now, with the calls and sent log since the last reset) and draft an eval from it with rystic grade --draft. The draft expects each row the run created or changed, forbids any other creation, change, call actor or method, and allow_deletes each row it deleted; the saved cell passes it. The state after the last seed through this server since the baseline is the run’s before, so seeded rows are setup, not the run’s; rows a scenario timeline event seeds during the run count as the run’s. Returns the draft YAML and cell_dir, whose eval.yaml holds the draft, so rystic grade <cell_dir> passes. Trim the checks to what the task requires before keeping them. An instance with no baseline is refused: reset, load_scenario or diff_state it before the run.

save_world

Save the instance’s state as a scenario file at file, the scenario document rystic run --seed <file> boots and POST /_rystic/seed lands, so a teammate, a CI job or a later run starts a twin in this state. It holds what snapshot_twin holds: the whole state, the clock, the id counters, the pending scheduled events and, when your plan includes network shaping and a profile is installed, that shaping. The file names the twin but no instance, version or model hash; a twin release that cannot take a record refuses the load and lists the records. An existing file, a symlink included, is refused unless force is true, which replaces the file or writes through the symlink. New files are private to your user; replacing a file preserves its permissions. It refuses a pending event that acts as a named caller and a scenario too large for the seed route to take back. On a twin release older than the seed round trip, which holds no id counters, the result carries a warning: ids minted after a load can collide with loaded records. The file does not hold, so loading it does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they 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 world’s own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). It holds no rng_seed and no credentials either, which the twin does not expose; add those keys to the file by hand when a run needs them. A pending default-actor call on a route that needs a credential binding fails the load.

seed

Merge records into the instance’s state (POST /_rystic/seed). body is {register: {key: {field: value}}}; rystic describe <twin> -json shows each register with an example record. Seeding leaves diff_state’s baseline where it is, so seeded rows read as created; save_test_case reads the seeded state as the run’s starting state instead.

set_clock

Pin the instance’s clock to an RFC3339 instant (POST /_rystic/clock); events due by then fire. Returns the clock the twin then reads.

sign_in

Sign in to Rystic, or sign up, in the browser, so start_twin can download twins: call it when a tool fails with license_or_lease. The first call returns a URL and a code at once; show both to the user, who opens the URL, checks that the page shows the same code and approves. Then call sign_in again: it answers pending until the user has approved, then stores the API key where rystic login stores it and answers signed_in. A link lasts 15 minutes; a call after that returns a new one. The API key never appears in a result.

No arguments.

snapshot_twin

Save the instance’s world under name, so restore_twin can roll back to it: try one path, roll back, try another. It holds the whole state, never a page,, the clock, the id counters, the pending scheduled events and, when your plan includes network shaping, that shaping. This CLI stores it per instance; it outlives a restart of the instance on the same twin version. A snapshot of the same name is replaced, and the result says so. Omit name to list the instance’s snapshots. It refuses a pending event that acts as a named caller (a restore cannot rebind its credential) and a world too large for the seed route to take back. A snapshot does not hold, so a restore does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they 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 world’s own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). A pending default-actor call on a route that needs a credential binding fails the restore after the reset, which leaves the instance reset.

start_twin

Start a twin in the background, as rystic run <twin> -d does, and return its instance name and URL; point the code under test at the URL. A twin that is not installed is pulled first, as rystic run pulls one, which can take a minute; a call that carries a progressToken gets the download as notifications/progress, and cancelling the call stops the pull and any twin it started. It takes a free port unless port is given, and stores the state it boots into as diff_state’s baseline. The twin keeps running after this server exits; stop_twin ends it.

stop_twin

Stop a running instance and remove its record and diff baseline, as rystic stop does.

Pages, filters and links

inspect_state, list_calls, list_sent and diff_state return one page at a time, at most limit entries and about 20 KB. Tools gives each one’s filters and what format carries. Pass a page’s next_cursor back as cursor for the next page. 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. matched counts the entries the filters match across every page. In either format an entry over 12 KB is cut and marked.

Prompts

The server offers 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. A scoped server’s guide says only what it serves.

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.