Skip to content

Agents: Claude Code, Cursor, Codex

The Forkstage MCP server gives any MCP-capable agent the tools to create and use forks. Install it once per machine (it uses the sign-in from forkstage login):

Claude Code

Terminal window
claude mcp add forkstage -- npx -y @forkstage/mcp

Cursor: Settings → MCP → Add server, command npx, arguments -y @forkstage/mcp. Or in .cursor/mcp.json:

{ "mcpServers": { "forkstage": { "command": "npx", "args": ["-y", "@forkstage/mcp"] } } }

Codex and others: the same npx -y @forkstage/mcp as a stdio MCP server.

Eight tools, each described plainly so the agent knows what it has:

Tool Does
environment_create forks the repository’s stack; returns the address and how to use it
environment_status the forks this machine knows about
environment_exec a command inside a service
environment_http_request an HTTP request to the fork’s address
environment_test the recipe’s tests
environment_logs recent logs
environment_note a line in the proof, in the agent’s words
environment_destroy strikes the fork

The server’s instructions tell the agent: create one at the start of a task, use it to run the app, reproduce the bug and prove the change, destroy it when finished; everything it runs is recorded.

In the sample project:

There is a bug: a book that is already lent can be lent again. Reproduce it in a Forkstage environment, fix it, run the tests inside the environment, and tell me the proof id.

What happens: the agent calls environment_create, hits /books/2/lend twice through environment_http_request and sees the second one succeed, edits BookRepository.lend, runs environment_test, destroys the fork. The proof appears in your dashboard with every step.

The other way: run the agent inside the context

Section titled “The other way: run the agent inside the context”
Terminal window
forkstage run -- claude

creates a fork, starts the command with FORKSTAGE_URL, FORKSTAGE_CONTEXT and friends in its environment (and, for Claude Code, a system-prompt addition describing the fork), and strikes the fork when the command exits. --keep leaves it running.

It cannot reach your real environments: a fork is the only thing it is given. It cannot keep a fork forever: the workspace’s idle and hard stops apply. It cannot hide what it did: the proof is written by Forkstage, not by the agent.