Terminal
Terminal/Skill
Connects an outside coding agent such as Claude Code or Cursor to Warp Factory MCP by installing the oz CLI and registering the server.
By Warp
Works with
npx skills add warpdotdev/warp-factories-skills --skill factory-setupBootstrap Warp Factory access for a coding agent that is not Warp itself: install/authenticate the oz CLI, register the hosted Factory MCP server, verify the connection, and hand off to the canonical operating skill. This is a one-time setup skill, not the operating playbook.
This skill:
list_factories works, canonical skill readable).This skill does not:
skill://warp/factory-mcp/SKILL.md on the MCP connection itself and is the authoritative source once connected.The Factory MCP is always mounted at {server_root}/api/v1/mcp/factory. Third-party harnesses do not know Warp's server root on their own, so make it explicit up front:
| Server root | CLI binary | MCP URL |
|---|---|---|
https://app.warp.dev | oz | https://app.warp.dev/api/v1/mcp/factory |
FACTORY_MCP_URL, use it verbatim instead of building one.WARP_SERVER_ROOT instead, build the URL as {WARP_SERVER_ROOT}/api/v1/mcp/factory.https://app.warp.dev — do not ask the user to pick a server root, and do not point them at any other host.Warp's CLI ships as oz through soft launch; it is renamed to warp at GA. Mention this once so the user isn't confused if they see the CLI called warp elsewhere later.
oz: the install command is not finalized yet.
PLACEHOLDER — do not invent a command here. Ask the user how they installed/would install
oz, or point them athttps://docs.warp.devfor the current instructions. Do not guess a package name, curl-pipe URL, or script.
Once the CLI is available and logged in (oz login), mint an API key for the harness to use:
oz api-key create --expires-in 30d "factory-setup"
Treat the printed key as a secret: export it to an environment variable (e.g. WARP_API_KEY) and use that variable everywhere below. Never paste it into a config file that gets committed, and never print it back to a shared terminal or log.
API key + Authorization: Bearer is the supported auth path and works on every harness. Use it everywhere below. OAuth is not available for third-party clients today: Factory MCP does not support dynamic client registration, and no per-harness OAuth client is registered for external use — so a client's built-in "connect with OAuth" flow will fail. If a harness tries OAuth on its own and fails, fall back to the API key rather than debugging the OAuth flow.
Substitute {mcp_url} = {server_root}/api/v1/mcp/factory from Step 1, and $WARP_API_KEY from Step 2.
claude mcp add --transport http warp-factory {mcp_url} \
--header "Authorization: Bearer $WARP_API_KEY"
Flag names can shift between Claude Code versions — run claude mcp add --help first if this fails. Verified against @anthropic-ai/claude-code (mcp add --transport http ... --header "...") as of this writing.
Do not use claude mcp login / --client-id here — see the OAuth note in Step 2.
codex mcp add warp-factory --url {mcp_url} --bearer-token-env-var WARP_API_KEY
This writes a [mcp_servers.warp-factory] block to ~/.codex/config.toml with url and bearer_token_env_var; Codex reads the bearer token from that environment variable at connect time, so make sure WARP_API_KEY is exported in the same shell/session Codex runs in. Verified against @openai/codex (mcp add <name> --url ... --bearer-token-env-var ...).
Do not use --oauth-client-id / codex mcp login here — see the OAuth note in Step 2.
Cursor has no MCP CLI; edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped):
{
"mcpServers": {
"warp-factory": {
"url": "{mcp_url}",
"headers": {
"Authorization": "Bearer ${env:WARP_API_KEY}"
}
}
}
}
Cursor resolves ${env:VAR} references in headers from its own process environment at connect time — never inline the raw key in this file, since a project-scoped .cursor/mcp.json is easy to commit or expose. Make sure WARP_API_KEY is actually set in Cursor's launch environment: a shell-only export in .bashrc/.zshrc is not always inherited by a desktop app launched outside that shell, so prefer launching Cursor from a terminal where echo $WARP_API_KEY already prints the value, or set it somewhere Cursor's launcher reliably reads (e.g. /etc/environment on Linux). Restart Cursor after editing, then check Settings → Tools & MCP for a green connection.
Use the headers block above, not an auth block: Factory MCP has no dynamic client registration, so Cursor's discovery/DCR fallback will fail — see the OAuth note in Step 2.
Any client that supports streamable HTTP with custom headers can connect directly: point it at {mcp_url} with header Authorization: Bearer $WARP_API_KEY. There is no special Warp-specific transport.
From the harness with the MCP server attached:
List tools (tools/list or the client's equivalent) and confirm the Factory tools are present: list_factories, create_factory, list_tasks, search_task, get_task, message_foreman, get_conversation, send_task, complete_task, list_notification_routes.
Call list_factories. Success is any response without an auth error — an empty list just means the principal has no factories yet, which is fine.
Read the resource skill://warp/factory-mcp/SKILL.md. A successful read proves the handoff to the operating skill works. Day-2 Factory use depends on this operating skill, so if the harness can't do resources/read itself (some tool-only clients don't), don't just tell the user to "fetch it manually" — fetch it yourself with one standalone JSON-RPC call against the same authenticated endpoint (verified: this works without a prior initialize handshake) and put the returned text somewhere the agent will read it before starting real Factory work:
curl -s {mcp_url} \
-H "Authorization: Bearer $WARP_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"skill://warp/factory-mcp/SKILL.md"}}'
The skill text is in result.contents[0].text of the returned JSON.
If any step fails, stop and report the exact error instead of guessing a fix — see Troubleshooting below.
Setup is complete once Step 4 passes; this step is optional follow-up, not the success bar.
list_factories to find its factory_uid and, if they want, save it as their default per the operating skill's ~/.warp/factory/config.json contract (skill://warp/factory-mcp/references/factory-config.md).create_factory needs team_uid, name, code_forge, and at least one repositories entry (owner/repo); integrations is optional. Avatars are REST-only, not settable over MCP.Once verified, tell the user setup is done. Day-2 operation — finding tasks, delegating work, pulling a task down locally, coordinating with the foreman, handing work back — is governed entirely by the canonical skill the server exposes at skill://warp/factory-mcp/SKILL.md. Read and follow that skill for anything after this point; do not reimplement its operating rules here.
resources/read for the skill URI fails or is unsupported: some clients don't implement MCP resources. The tool surface still works, but fetch the canonical skill yourself with the standalone curl call in Step 4 rather than leaving the user without it.