Connect
- Remote
- Local
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, likeenvironment_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:
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 = 3600under[mcp_servers.replicas]in~/.codex/config.toml. - Clients that don’t support progress notifications wait up to 50 seconds per call.
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.