Agents: Claude Code, Cursor, Codex
One line to connect
Section titled “One line to connect”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
claude mcp add forkstage -- npx -y @forkstage/mcpCursor: 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.
What the agent gets
Section titled “What the agent gets”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.
A first task to give it
Section titled “A first task to give it”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”forkstage run -- claudecreates 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.
What the agent cannot do
Section titled “What the agent cannot do”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.