Rystic MCP

Rystic MCP server

rystic mcp is a local MCP server that lets your coding agent run Rystic simulators of real APIs (Stripe, GitHub, Slack and more) on your machine. Through MCP tools the 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, and saves the run as a test case.

The server speaks MCP over stdio: your client launches rystic mcp as a subprocess. It ships inside the rystic CLI.

Install

Mac or Linux, 64-bit.

curl -fsSL https://www.rystic.ai/install.sh | sh

The install ends by signing you in through the browser. A new account starts on the Free plan. For CI or a machine without a browser, create an API key and run rystic login rys_….

Then add the server to your client:

rystic mcp install --client claude-code   # or cursor, codex, vscode, windsurf

Restart the client and approve the rystic server when it asks.

Install as a plugin

The repository is also a plugin for each client below. Each plugin starts rystic mcp, so install the CLI first. When Claude Code cannot find rystic on its PATH, the Claude Code plugin says how to install it, or which folder to add to PATH, as a session starts or resumes.

Client	Command
Claude Code	claude plugin marketplace add Rystic-Inc/rystic, then claude plugin install rystic@rystic
Codex	codex plugin marketplace add Rystic-Inc/rystic
Gemini CLI	gemini extensions install https://github.com/Rystic-Inc/rystic
Antigravity CLI	agy plugin install https://github.com/Rystic-Inc/rystic

Configure by hand

Claude Code (.mcp.json) and Cursor (.cursor/mcp.json):

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

VS Code (.vscode/mcp.json):

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

Codex (.codex/config.toml):

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

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

Tools

Tool	What it does
list_twins	the simulators running on this machine
start_twin	starts a simulator, optionally with a scenario, and returns its URL
stop_twin	stops a simulator
list_scenarios	the named starting worlds a simulator ships
load_scenario	wipes state and loads a scenario
seed	merges records into state
set_clock	pins the simulator's clock
advance_clock	moves the clock forward or back
reset	empties state and clears the logs
inspect_state	reads the whole state or a named view
list_calls	the API calls served since the last reset
list_sent	webhooks, emails and other outbound effects
diff_state	rows created, changed and deleted since the baseline
save_test_case	saves the run as a regression test

The tool names say "twin", meaning a simulator.

What leaves your machine

The plugin itself sends nothing: it starts rystic mcp on your machine. The rystic CLI calls www.rystic.ai to sign in, check for updates and download a simulator the first time you start it, and registry.rystic.ai when it runs a simulator in Docker. On the Free and Pro plans a running simulator checks in with lease.rystic.ai at start, every 30 seconds and on exit, carrying your API key and the windows in which it was in use, never your requests, data or hostname. Full list: https://www.rystic.ai/docs/cli#what-leaves-your-machine

Run in a container

The Dockerfile builds an image that runs rystic mcp on stdio. It installs the Linux build of the rystic CLI that www.rystic.ai names for the image's platform and checks its SHA-256 before installing it.

docker build -t rystic-mcp .
docker run -i --rm rystic-mcp

The image installs the newest CLI when it is built. Add --build-arg RYSTIC_VERSION=<version> to pin a release, or --no-cache to pick up a newer one on a rebuild.

Building pulls the Debian base image from Docker Hub, installs packages from Debian's mirrors and downloads the CLI. Starting the server and listing its tools need no network or sign-in. A simulator the server starts inside the container is reachable only from inside it, and needs a signed-in CLI there, so for everyday use install the CLI on your machine as above.

Cline

Cline can install the server for you by following llms-install.md, which covers installing the CLI, signing in and adding the server to Cline's MCP settings.

Documentation

Full reference: https://www.rystic.ai/docs/mcp-server

License

MIT. See LICENSE.