Rystic

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.

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

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: the value you pass as RYSTIC_SHA256, or else the one the release names.

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. A version pins a name; to pin the bytes, add --build-arg RYSTIC_SHA256=<sha256> with the archive's checksum, and the build checks the download against your value. The checksum is the rystic_<version>_linux_<arch>.tar.gz line of checksums.txt on the release, with the version written without its leading v, as 0.0.38. One checksum covers one platform, so a build that pins it is for that platform alone.

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.