Skip to main content
The Replicas MCP server lets an AI assistant create and control workspaces, and manage the environments, repositories, plugins, automations, and learnings they use. Its tools mirror the API, with the same permissions.

Connect

Add the server URL to your client:
Clients that support OAuth open Replicas to sign in. Approving one creates a personal API key for it, which you can revoke under Personal → API Keys.In Claude or Claude Desktop, add it under Settings → Connectors → Add custom connector. In Claude Code:
For clients without OAuth, send an API key as a header: Authorization: Bearer YOUR_API_KEY.

Tools

Tools are grouped into toolsets. Most take IDs from a list tool, like environment_id from list_environments. list_environments and whoami are always included. create_automation comes with the automations toolset. If your client limits how many tools it loads, choose toolsets in the URL:
For the local server, set REPLICAS_MCP_TOOLSETS=workspaces,chats.

Follow long jobs

get_replica returns activity: whether the agent is working, waiting for input, or idle, its current step, and its last message. wait_for_replica returns when the agent is done, including background tasks it will wake up for, or as soon as it asks a question. While it waits, it reports the current step as progress. Pass timeout_seconds up to 3600 to cover a long job in one call:
  • Claude Code moves a call that runs past 2 minutes to the background, so you can keep working. Claude tells you when the workspace is done.
  • Codex stops tool calls after 300 seconds. To wait longer, set tool_timeout_sec = 3600 under [mcp_servers.replicas] in ~/.codex/config.toml.
  • Clients that don’t support progress notifications wait up to 50 seconds per call.
For callbacks to your own server, create the workspace through the API with webhook_url. Tools follow the same access rules as the API. start_plugin_oauth returns a URL for a person to open. Agents inside workspaces get a smaller set from this server and use the CLI for the rest. Managers also get tools to manage their ships.