docs(factories): document Factory MCP

Co-Authored-By: Warp Agent <agent@warp.dev>

Author: hongyi-chen

src/content/docs/factories/factory-mcp.mdx

@@ -1,9 +1,115 @@
 ---
 title: Factory MCP
 description: >-
-  Factory MCP documentation will cover programmatic factory connections in a follow-up PR.
+  Factory MCP connects coding agents to Warp Factories for task intake, local
+  iteration, coordination, and handback.
 sidebar:
   label: "Factory MCP"
+topic: factories
 ---
 
-Factory MCP documentation will land in a follow-up PR.
+Factory MCP connects compatible coding agents and Model Context Protocol (MCP) clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item.
+
+Use Factory MCP when work moves between a cloud factory and an interactive coding session. The factory retains its workflow and task history, while the local agent uses the developer's checkout and tools.
+
+## When to use Factory MCP
+
+* **Send work** - Create a work item from context available to an MCP client.
+* **Continue locally** - Pull an existing work item's context and Git guidance, then return the pushed result.
+* **Inspect and coordinate** - Find work, inspect outputs, message the foreman, and read its conversation.
+* **Create a factory** - Create one when the team, repository, and source-control details are known.
+
+Factory MCP complements integrations from Slack, issue trackers, and GitHub. See [connect your factory](./connect-your-factory) for the available intake paths and [how Warp Factories work](./how-factories-work) for the work-item lifecycle.
+
+## Connect and authenticate
+
+When Factory MCP is available for your account, Warp attaches the built-in server to supported agent sessions and supplies the authenticated connection. This path needs no vendor-specific configuration.
+
+Claude Code, Codex, Cursor, and other public MCP clients connect through remote MCP support. Follow the client's setup instructions, then authenticate with one of these methods:
+
+| Method | How it works |
+| --- | --- |
+| Browser OAuth | The client opens a browser so you can sign in and authorize the client. Public clients use Proof Key for Code Exchange (PKCE), and authorization requires your consent. |
+| [API key](../reference/cli/api-keys/) | Clients that support bearer-token authentication can use a Warp API key. Store the key in the client's secret or credential mechanism rather than committing it to a repository. |
+
+Factory MCP currently has no factory-specific or read-only OAuth scopes. It acts with the existing permissions of the user or cloud agent it authenticates as. Use user credentials for supervised sessions. For third-party clients and unattended automation, use a least-privilege cloud agent; its API key inherits that agent's permissions. Repository access follows user permissions or the team's GitHub App installation. Restrict access to team credentials separately.
+
+Use connection information from Warp or your factory administrator. For client configuration, authentication, and security guidance, see [Model Context Protocol in Warp](../agents/capabilities/mcp/).
+
+## Read the server guidance first
+
+Factory MCP serves a canonical skill, workflow guidance, factory configuration guidance, and tool contracts as MCP resources. Before operating, read `skill://warp/factory-mcp/SKILL.md`. Treat served resources as the source of truth instead of copied schemas or older prompts.
+
+## Work locally and return a task
+
+```mermaid
+sequenceDiagram
+  participant Client as MCP client
+  participant MCP as Factory MCP
+  participant Foreman
+  participant Local as Local repository
+  Client->>MCP: list_factories
+  Client->>MCP: list_tasks or search_task
+  Client->>MCP: get_task(start_working=true)
+  MCP-->>Client: Task context and Git guidance
+  Client->>MCP: message_foreman
+  MCP->>Foreman: Coordinate
+  Client->>MCP: get_conversation
+  MCP-->>Client: Conversation data
+  Client->>Local: Change, validate, commit, and push
+  opt Notifications requested
+    Client->>MCP: list_notification_routes(factory_uid)
+    MCP-->>Client: Selectable user routes
+  end
+  Client->>MCP: send_task(factory_task_uid, selected route)
+  MCP->>Foreman: Return work
+  Client->>MCP: complete_task when terminal
+```
+
+1. **List factories** - Call `list_factories`. Use an explicit or validated saved default factory. If neither exists, ask the user. Never fan `list_tasks` or `get_task` out across factories.
+2. **Find the task** - Use `list_tasks` for one factory or `search_task` across factories. Retain `factory_task_uid` for every later operation.
+3. **Start local work** - Call `get_task` with `start_working=true`. Set `workspace_dir` to an absolute path to an existing local clone. The server returns Git and [worktree](../code/git-worktrees/) guidance but does not change files.
+4. **Conversation** - Use `message_foreman` for progress, questions, and blockers. Use the read-only `get_conversation` for responses. Messaging does not return work or change its stage.
+5. **Implement and push** - Validate the change, then commit and push. Factory workers cannot inspect changes only in a local checkout.
+6. **Return the task** - Call `send_task` with the same `factory_task_uid`, a handback note, and the pushed branch or pull request URL. Optionally pass a selectable `notification_route_uid`. The foreman can override `stage_hint`.
+7. **Complete terminal work** - Call `complete_task` only when no factory work remains. Handback alone does not complete the task.
+
+:::caution
+Pulling a task locally does not claim, lock, or pause it. Factory runs can continue after `get_task(start_working=true)`. Check active runs and coordinate with the foreman to avoid duplicate changes.
+:::
+
+`get_task` also accepts an exact task or run UUID, run URL, GitHub pull request, Slack permalink, Linear issue, or branch. External references and branches require factory scope; a bare branch also requires its repository. On `requires_scope`, select an explicit or validated default factory, or ask the user. On `not_found`, report the searched factory and ask before trying another. On `ambiguous`, use a returned candidate's `factory_task_uid`.
+
+## Send new work or hand back existing work
+
+`send_task` selects its operation from the identifier you provide:
+
+| Operation | Identifier | Note | Artifacts | Effect |
+| --- | --- | --- | --- | --- |
+| New intake | `factory_uid` and `title`; optional ticket reference and URL | Requested outcome and constraints | Initial workspace snapshot when supported | Starts a foreman workstream. Search first when the request might already exist. |
+| Existing-task handback | `factory_task_uid` | What changed, validation performed, and remaining work | Pushed branch or pull request; eligible plans, confirmed files, and screenshots from a source conversation | Continues the existing foreman conversation instead of creating another work item. |
+
+See [Handoff between local and cloud agents](../platform/handoff/) for workspace and conversation transfer outside a factory work item.
+
+Call `list_notification_routes` before setting `send_task.notification_route_uid`. Routes are user-specific and selectable only when returned for the current caller and factory. Available routes can include a Slack self-DM or Linear issue. Delivery of attention-required and terminal updates is best-effort.
+
+## Tool reference
+
+Factory MCP exposes ten tools. The table lists the main purpose and key inputs, not every optional filter or response field. Read the live tool contracts for the complete schema.
+
+| Tool | Purpose | Key inputs |
+| --- | --- | --- |
+| `list_factories` | Lists accessible factories and the context needed to choose one. | No required input. Optionally filter with `team_uid` or continue with `cursor`. |
+| `list_notification_routes` | Lists notification destinations selectable for the caller and factory. | `factory_uid`. |
+| `create_factory` | Creates a factory and returns its identifier and next actions. | `team_uid`, `name`, `code_forge`, `integrations`, and one or more `repositories` in owner/repo form. |
+| `list_tasks` | Lists authoritative work items for one factory, with stages and linked outputs. | `factory_uid`; optional creator, title, stage, date, sort, and pagination filters. |
+| `search_task` | Searches task titles across every factory the caller can access. | `queries`; optionally `limit` and `cursor`. |
+| `get_task` | Resolves a task, then reads status, run history, outputs, and local-work guidance. | Exactly one of `factory_task_uid` or `reference`; references can also require `factory_uid` and `repository`. |
+| `message_foreman` | Sends a coordination message to the task's latest foreman run. | `factory_task_uid` and `message`. |
+| `get_conversation` | Reads a bounded window of the task's foreman conversation. | `factory_task_uid`; optionally `limit` and `before_index` for pagination. |
+| `send_task` | Creates new intake or returns work, with optional best-effort notifications. | Always `note`; new intake needs `factory_uid` and `title`, handback needs `factory_task_uid`, and notifications use `notification_route_uid`. |
+| `complete_task` | Marks a task complete. Repeated completion is idempotent, but a `CANCELLED` task is rejected. | One of `run_id` or `factory_task_uid`. |
+
+## Next step
+
+[Create a factory and send its first work item](./quickstart) with the Warp Factories quickstart.