AI coding agents (MCP)

An agent cannot fix a bug it cannot reproduce, and it reports success when its own tests pass on its own machine. twin mcp gives it the reporter’s environment to work in and to check the fix against.

twin mcp is an MCP server over stdio, built on the official @modelcontextprotocol/sdk.

Setup

The server needs SOLARI_API_KEY in its own environment. Get a key at console.getsolari.com. Only inspect works without it.

Claude Code

claude mcp add twin -e SOLARI_API_KEY=slr_live_... -- npx -y @crypticsaiyan/twincli mcp

Cursor and others

Add this to the client’s MCP configuration (for Cursor, .cursor/mcp.json or the global settings):

{
  "mcpServers": {
    "twin": {
      "command": "npx",
      "args": ["-y", "@crypticsaiyan/twincli", "mcp"],
      "env": { "SOLARI_API_KEY": "slr_live_..." }
    }
  }
}

Node 22 or newer must be on the PATH the client uses to start the server.

Tools

Tool	What it does
inspect	Summarizes a capsule, or lists every difference between two. Offline.
replay	Rebuilds the environment and reruns the command. When the failure reproduces, the machine is kept and its id is returned.
run	Runs a shell command on the kept machine, in the reporter’s environment.
write_file	Writes a file on the kept machine.
verify	Applies a diff or a pushed commit on a fresh machine and reports FIXED, STILL FAILING, DIFFERENT FAILURE, FLAKY or INCONCLUSIVE.
bisect	Finds the minimal difference between a failing and a passing capsule.
release	Stops one kept machine, or every twin machine when no id is given.

A capsule argument is a local path or an https URL such as a GitHub issue attachment, so the issue link is enough to start. Arguments and defaults are in the MCP reference. Results are the text reports the CLI prints. Errors come back as tool errors that start with twin:, so the agent can read them and adjust.

Long tool calls

replay and verify take about 70 seconds or more, and bisect takes longer. twin sends progress notifications while they run, which keeps clients that reset their timeout on progress waiting. In Claude Code you can also raise the timeout, in milliseconds:

MCP_TOOL_TIMEOUT=600000 claude

The agent loop

1. replay the capsule. A REPRODUCED verdict comes back with a machine id.
2. run commands on that machine: read the failing test, print versions, rerun the command with more logging.
3. write_file to try a fix in the reporter’s environment, then run the failing command again. Repeat until it passes.
4. verify the capsule with the final diff as patch. This uses a fresh machine, so leftover state from exploring cannot make it pass.
5. release the kept machine.

A prompt that sets this up:

Issue: https://github.com/apache/echarts/issues/21538
Capsule: https://github.com/user-attachments/files/<id>/new-york.json

Use the twin tools. Reproduce the failure with replay before changing anything,
work on the kept machine with run and write_file, verify your final diff with
verify, then release the machine. Report the verdicts you got.

Caution

Kept machines bill until they have been idle for 15 minutes or are released. When the MCP session ends the server releases the machines that session kept. release with no arguments stops every twin machine on the account, including ones kept from a terminal.

A recorded session

examples/echarts-21538/mcp.txt is the full log of a session against twin mcp on Solari. It was driven by a scripted MCP client (test/e2e/mcp-session.ts, run with pnpm e2e:mcp) and not by an LLM, so it shows exactly what an agent sends and receives.

Call	What happened	Time
inspect	The capsule summary, offline.	0 s
replay	REPRODUCED on the New York capsule. The machine is kept.	71 s
run	The test fails on the kept machine with the numbers from the issue.	4 s
write_file	The fix patch is written to the machine.	1 s
run	The patch is applied and the tests pass, 15 of 15.	5 s
verify	FIXED on a fresh machine.	74 s
release	The kept machine is stopped.	7 s

The session took 162 seconds. An agent can now open a pull request with that diff and say, truthfully, that it reproduced the failure and verified the fix in the reporter’s environment. The GitHub Action checks that claim again on the pull request.

The lru-cache case study has a session with a real Claude Code: replay, test, dependency tree, verify and release.

What the agent can touch

• Commands and files run inside the Solari sandbox, never on the machine that runs the MCP server.
• The sandbox receives the capsule’s recorded values and any env the agent passes to replay, and nothing from the server’s environment. SOLARI_API_KEY stays with the server.
• A kept machine is a root shell on your Solari bill. Treat run as giving the agent a terminal on a disposable VM.
• With one twin machine running, run and write_file can leave out machine. With several, any unique prefix of the id works.