Skip to content

Document single-prompt Factory MCP onboarding #585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
harryalbert wants to merge 4 commits into
base: main
Choose a base branch
from
+35 −6
Draft

Document single-prompt Factory MCP onboarding #585

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d0632a1
Document single-prompt Factory MCP onboarding
harryalbert Aug 20, 2026
e4114af
Merge branch 'main' into harry/docs-agent-driven-factory-onboarding
harryalbert Aug 20, 2026
1dae3b7
Document coding-agent MCP setup lifecycles
harryalbert Aug 20, 2026
5247fd2
Make Claude MCP scope explicit
harryalbert Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 35 additions & 6 deletions src/content/docs/factories/factory-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title: Factory MCP
description: >-
Connect any coding agent to your team's factories to send in work, continue
tasks locally, and hand results back.
Connect any coding agent to create and operate your team's factories, send in
work, continue tasks locally, and hand results back.
sidebar:
label: "Factory MCP"
---
Expand All @@ -16,7 +16,7 @@ The factory keeps a single record of each task throughout. Whether a change happ
* **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change.
* **Continue a task locally** - Pull a task's context into your own checkout, work with your own tools, and return the result to the same task.
* **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory.
* **Create a factory** - Set up a new factory when you know the team, repositories, and source-control details.
* **Create a factory** - Let your coding agent guide you through choosing a team, code forge, repositories, factory agents, and integrations.

Factory MCP is one of several ways work enters a factory, alongside Slack, GitHub, GitLab, Linear, and Jira. See [connect your factory](/factories/connect-your-factory/) for all intake paths and [how Warp Factories work](/factories/how-factories-work/) for how tasks move through a factory.

Expand All @@ -26,14 +26,38 @@ Factory MCP is one of several ways work enters a factory, alongside Slack, GitHu

There is nothing to configure. When your account has access, Warp connects agent sessions to Factory MCP and handles authentication for you.

### Set up with your coding agent

Paste this prompt into a coding agent that can run commands and configure MCP servers:

```text
Set up a Warp Factory for me. Read https://docs.warp.dev/factories/factory-mcp.md, follow the setup instructions for your coding environment to connect to and authenticate with Factory MCP, then use Factory MCP to onboard me.
```

Your agent will:

1. Check whether Factory MCP is already available.
2. If it is not available, identify the coding environment and add `https://app.warp.dev/api/v1/mcp/factory` using that client's current MCP configuration mechanism.
3. Open the browser-based Warp authorization flow.
4. Verify the Factory MCP tools are available.
5. Use the onboarding guidance published by Factory MCP to help you select a team, repositories, factory agents, and optional integrations before creating the factory.

#### Guidance for coding agents
Before configuring anything, the agent should identify its coding environment and use that client's current MCP management mechanism. If it is unsure how the client manages MCP servers, it should check the client's help or official documentation rather than guess.

* **Warp:** Factory MCP is built in. Use the existing connection instead of adding another server.
* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed, then continue onboarding without asking the user to restate their goal.
* **Codex:** Add Factory MCP as a remote HTTP server, use Codex's built-in OAuth flow, and confirm the server is active through its MCP controls before onboarding. Only ask the user to restart or resume if the configured server is not available to the current session.
* **Other MCP clients:** Add the remote server using the client's supported configuration and authentication flow. If the client cannot load a newly added server into the current session, explain how to restart or resume while preserving the onboarding context when possible.

### In other MCP clients

Factory MCP is a streamable HTTP server at `https://app.warp.dev/api/v1/mcp/factory`. Point any MCP client that supports remote servers at that URL; on first connect, the client opens a browser so you can sign in and approve access.

With Claude Code:

```bash
claude mcp add --transport http warp-factory https://app.warp.dev/api/v1/mcp/factory
claude mcp add --transport http --scope local warp-factory https://app.warp.dev/api/v1/mcp/factory
```

In clients that use the `mcpServers` JSON format, such as Cursor:
Expand Down Expand Up @@ -76,8 +100,9 @@ Factory MCP exposes a small set of tools that your agent calls on your behalf. Y
* "Send this bug to the factory, including my branch."
* "What's the status of the checkout-flow task?"
* "Pull down ENG-123 so we can finish it here."
* "Set up a Warp Factory for me."

The rest of this page describes what happens behind those prompts.
For factory creation, the server-provided onboarding guidance walks the agent through team selection, code-forge authorization, repositories, agent roles, optional integrations, creation, and verification. The rest of this page describes what happens behind these prompts.

## Send new work to a factory

Expand Down Expand Up @@ -110,7 +135,11 @@ Your MCP client fetches the full input schemas from the server, and tool results
| Tool | What it does |
| --- | --- |
| `list_factories` | Lists the factories you can access. |
| `create_factory` | Creates a factory for a team, with its repositories and source-control details. |
| `list_teams` | Lists the teams that can own a new factory. |
| `list_forge_repositories` | Lists repositories available through a team's connected GitHub or GitLab account. |
| `start_connection` | Starts or checks setup for GitHub, GitLab, Slack, Linear, or Jira. |
| `get_connection_status` | Checks whether a browser authorization flow completed. |
| `create_factory` | Creates a factory with the selected repositories, integrations, and optional factory agents. |
| `list_tasks` | Lists the tasks in one factory, with filters such as creator, stage, and date. |
| `search_task` | Searches task titles across all factories you can access. |
| `get_task` | Reads a task's status, run history, and outputs. Accepts a task ID or a reference such as a URL, issue, pull request, or branch. With `start_working=true`, also returns local setup guidance. |
Expand Down
Loading