Builder Code MCP server

Connect your AI tools to Builder Code using the Model Context Protocol (MCP), an open standard that lets AI clients create and iterate on projects, inspect work, and use your design systems.

Note: The Builder Code MCP server operates on the Builder Code projects, branches, and design systems in the organization you select during authentication.

What to know

The server uses streamable HTTP at https://mcp.builder.io/mcp/fusion.
Authentication uses OAuth 2.0. Your MCP client opens Builder so you can sign in and select an organization.
Builder Code agent work runs asynchronously. Start a run, then check its status until it completes or fails.
The server can create a project, iterate on an existing project, or continue work on a specific branch.

Connect from MCP-compatible clients

Access the Builder Code MCP server from any MCP-compatible client, including AI coding assistants, IDE extensions, and LLM-based tools.

Authentication

The Builder Code MCP server uses OAuth 2.0 with dynamic client registration. The first time you use the server, your client opens a browser and redirects you to Builder. Sign in and select the organization that contains the Builder Code projects you want to access.

Your client stores the resulting authorization and uses it for later requests.

Configure your client

Most MCP clients use a JSON configuration file to define connections. Add an entry for the Builder Code MCP server using the following details:

Server type: streamable HTTP
Endpoint URL: https://mcp.builder.io/mcp/fusion

Example configuration:

{ "mcpServers": { "builder-fusion": { "url": "https://mcp.builder.io/mcp/fusion", "transport": "http" } } }

Consult your MCP client's documentation for the configuration file location and client-specific settings.

Claude Desktop configuration

Add the following to your claude_desktop_config.json file:

{ "mcpServers": { "builder-fusion": { "url": "https://mcp.builder.io/mcp/fusion", "transport": "http" } } }

GitHub Copilot configuration

Add the following to your MCP configuration file:

{ "mcpServers": { "builder-fusion": { "url": "https://mcp.builder.io/mcp/fusion", "tools": ["*"] } } }

Verify your connection

After connecting, test the server with prompts such as:

Which Builder organization am I connected to?
Show me my most recently updated Builder Code projects.
What Builder Code branches am I currently working on?
Which design systems are available?

After a successful connection, your client retrieves and displays information from your Builder Code organization.

Use the Builder Code MCP server

The Builder Code MCP server provides tools for starting agent work, monitoring runs, finding projects and branches, reviewing prior prompts, and grounding generation in your design systems.

Each tool listed below includes details on inputs and outputs, as well as example prompts. Use parameters within your prompt when specificity is needed.

Run the Builder Code agent

Start a Builder Code agent run with a natural-language prompt. This action requires the builder:agents:run scope.

Input

The prompt is the only required input. Omit a project ID to create a new project, or provide one to iterate on an existing project. With a project ID, provide a new branch name to name the branch the run creates, or a branch name to continue an existing branch instead. Builder ignores a branch name without a project ID and rejects a new branch name without one.

Example Prompt

Create a new Builder Code project for a responsive analytics dashboard with revenue, conversion, and retention views.

Parameter	Type	Required	Description
`prompt`	string	Yes	The natural-language prompt for the agent. Must contain at least one character after trimming whitespace.
`projectId`	string	No	The project to iterate on. Omit it to create a new project.
`branchName`	string	No	An existing branch to continue. Only used when `projectId` is also provided. To name a new branch, use `newBranchName`.
`newBranchName`	string	No	The name for the branch the run creates, as the full git branch name, such as `feat/thumbs-up`. Requires `projectId` and can't be combined with `branchName`. Builder rejects a name whose Git branch already exists. Omit it to have Builder generate a name.
`attachments`	array	No	File attachments and other context to include with the prompt.
`idempotencyKey`	string	No	A unique string that prevents a repeated request from starting a second run.

Output

The tool returns right away instead of waiting for the agent to finish. The response includes a run ID, the run status (submitted, working, completed, or failed), and details about the run, such as the project, branch, and timestamps. Once the run is working, the response also includes a preview URL. If the run fails, it includes an error code and message. Use the run ID to check progress.

Field	Type	Description
`runId`	string	The ID of the run. Use it to check the run's progress.
`status`	string	One of `submitted`, `working`, `completed`, or `failed`.
`ownerId`	string	The ID of the run's owner.
`userId`	string	The ID of the user associated with the run. Optional.
`projectId`	string	The project the run belongs to. Optional.
`branchName`	string	The branch the run is working on. Optional.
`url`	string	The preview URL, set once the run is working. Optional.
`prompt`	string	The prompt the run was started with.
`idempotencyKey`	string	The idempotency key sent with the request, if any. Optional.
`createdAt`	string	When the run was created, as an ISO timestamp.
`updatedAt`	string	When the run was last updated, as an ISO timestamp.
`error`	object	Included when the run fails. Contains an error `code` and `message`. Optional.

Get a Builder Code run

Get the latest snapshot of a run by its run ID, which is returned when you start a run. The run ID is the only input.

Input

Example Prompt

Check the latest status of the Builder Code run you just started and show me the preview when it is complete.

Parameter	Type	Required	Description
`runId`	string	Yes	The ID of the run, returned when you start a run.

Output

The result includes the same details returned when the run starts, such as the status, project, branch, prompt, and timestamps. A run can be submitted, working, completed, or failed. Once the run is working, the result includes a preview URL, and failed runs include an error code and message.

Check the run periodically until it reaches a completed or failed state.

If the run does not exist or belongs to a different Space, the tool returns a run_not_found error.

Field	Type	Description
`runId`	string	The ID of the run. Use it to check the run's progress.
`status`	string	One of `submitted`, `working`, `completed`, or `failed`.
`ownerId`	string	The ID of the run's owner.
`userId`	string	The ID of the user associated with the run. Optional.
`projectId`	string	The project the run belongs to. Optional.
`branchName`	string	The branch the run is working on. Optional.
`url`	string	The preview URL, set once the run is working. Optional.
`prompt`	string	The prompt the run was started with.
`idempotencyKey`	string	The idempotency key sent with the request, if any. Optional.
`createdAt`	string	When the run was created, as an ISO timestamp.
`updatedAt`	string	When the run was last updated, as an ISO timestamp.
`error`	object	Included when the run fails. Contains an error `code` and `message`. Optional.

List projects

List Builder Code projects in the authenticated organization, ordered by most recently updated. All inputs are optional.

Input

Use a search term to filter projects by name. The search is case-insensitive and matches any part of the project name.

Example Prompt

Find Builder Code projects with 'checkout' in the name and show the 10 most recently updated results.

Parameter	Type	Required	Description
`search`	string	No	A search term used to filter projects by name. The search is case-insensitive and matches any part of the name.
`limit`	number	No	The maximum number of projects to return. Defaults to 100.
`offset`	number	No	The number of projects to skip. Defaults to 0. Use the `nextOffset` from a previous response to get the next page.

Output

Results are paginated. By default, the tool returns up to 100 projects, starting from the first. Set a limit to change the page size and an offset to skip ahead, or use the next offset returned by the previous request, to retrieve more projects.

Each project in the results includes its ID, name, and Builder editor URL, plus optional details such as a screenshot, main branch, last updated time, and creator. The response also includes the total number of matching projects and whether more results are available.

Field	Type	Description
`projects`	array	The matching projects.
`projects[].projectId`	string	The ID of the project.
`projects[].name`	string	The name of the project.
`projects[].url`	string	The Builder editor URL for the project.
`projects[].screenshot`	string	A screenshot of the project. Optional.
`projects[].mainBranchName`	string	The name of the project's main branch. Optional.
`projects[].updatedAt`	number	When the project was last updated. Optional.
`projects[].createdBy`	string	The ID of the user who created the project. Optional.
`projects[].createdByName`	string	The name of the user who created the project. Optional.
`total`	number	The total number of projects that match.
`offset`	number	The offset used for this page of results.
`limit`	number	The page size used for this request.
`hasMore`	boolean	Whether more results are available.
`nextOffset`	number	The offset to use to retrieve the next page. Only present when more results are available. Optional.

Get a project

Retrieve one project by its project ID. The project ID is the only input, and it is required.

Input

Use this after listing projects when you need enough context to choose a project or open it in Builder.

Example Prompt

Get the details for the checkout project and give me its Builder editor URL and main branch.

Parameter	Type	Required	Description
`projectId`	string	Yes	The ID of the project to retrieve.

Output

The result includes the same details as each project in the project list: the name and Builder editor URL, plus optional details such as a screenshot, main branch, last updated time, and creator.

Field	Type	Description
`projectId`	string	The ID of the project.
`name`	string	The name of the project.
`url`	string	The Builder editor URL for the project.
`screenshot`	string	A screenshot of the project. Optional.
`mainBranchName`	string	The name of the project's main branch. Optional.
`updatedAt`	number	When the project was last updated. Optional.
`createdBy`	string	The ID of the user who created the project. Optional.
`createdByName`	string	The name of the user who created the project. Optional.

List branches

List branches in a project so you can choose work to inspect or continue.

Input

Use a search term to find branches by name, friendly name, description, category, Git branch, and other branch metadata.

Set createdByMe to show only branches created by the authenticated user. The project ID is required unless createdByMe is true, in which case you can omit it to find your active work across the organization.

Example Prompt

What Builder Code branches am I working on across the organization? Show anything related to checkout.

Parameter	Type	Required	Description
`projectId`	string	Conditional	The ID of the project to list branches from. Required unless `createdByMe` is true.
`search`	string	No	A search term matched against branch names, friendly names, descriptions, categories, Git branches, and other branch metadata.
`createdByMe`	boolean	No	When true, returns only branches created by the authenticated user. This lets you omit `projectId` to search across the organization.

Output

Each branch in the results includes its name, project, and Builder editor URL, plus optional details such as its friendly name, description, category, pull request status, whether the agent is running, waiting, or idle, and when it was last active.

The text summary of the results lists at most 50 branches, so narrow your search if you have more.

Field	Type	Description
`branches`	array	The matching branches. The text summary of the results lists at most 50.
`branches[].name`	string	The name of the branch.
`branches[].projectId`	string	The ID of the project the branch belongs to.
`branches[].projectName`	string	The name of the project. Optional.
`branches[].friendlyName`	string	A human-readable name for the branch. Optional.
`branches[].description`	string	A description of the branch. Optional.
`branches[].category`	string	One of `feature`, `fix`, `research`, or `other`. Optional.
`branches[].state`	string	One of `active`, `archived`, or `deleted`. Optional.
`branches[].prStatus`	string	The status of the branch's pull request. One of `open`, `draft`, `merged`, `closed`, or `approved`. Optional.
`branches[].prUrl`	string	The URL of the branch's pull request. Optional.
`branches[].agentState`	string	The state of the agent on the branch. One of `running`, `waiting`, or `idle`. Optional.
`branches[].hasUnpushedChanges`	boolean	Whether the branch has changes that have not been pushed. Optional.
`branches[].createdBy`	string	The ID of the user who created the branch. Optional.
`branches[].createdByName`	string	The name of the user who created the branch. Optional.
`branches[].lastActivityAt`	number	When the branch was last active, as epoch milliseconds. Optional.
`branches[].updatedAt`	number	When the branch was last updated, as epoch milliseconds. Optional.
`branches[].screenshot`	string	A screenshot of the branch. Optional.
`branches[].url`	string	The Builder editor URL for the branch.

Get a branch

Retrieve one branch by its project ID and branch name. Both are required.

Input

Use this when you know which branch you want to inspect or continue.

Example Prompt

Open the mobile-checkout branch in the checkout project and show me its Builder editor URL.

Parameter	Type	Required	Description
`projectId`	string	Yes	The ID of the project that contains the branch.
`branchName`	string	Yes	The name of the branch.

Output

The result includes the same details as each branch in the branch list: the name, project, and Builder editor URL, plus optional details such as its friendly name, description, category, pull request status, and agent state.

Field	Type	Description
`name`	string	The name of the branch.
`projectId`	string	The ID of the project the branch belongs to.
`projectName`	string	The name of the project. Optional.
`friendlyName`	string	A human-readable name for the branch. Optional.
`description`	string	A description of the branch. Optional.
`category`	string	One of `feature`, `fix`, `research`, or `other`. Optional.
`state`	string	One of `active`, `archived`, or `deleted`. Optional.
`prStatus`	string	The status of the branch's pull request. One of `open`, `draft`, `merged`, `closed`, or `approved`. Optional.
`prUrl`	string	The URL of the branch's pull request. Optional.
`agentState`	string	The state of the agent on the branch. One of `running`, `waiting`, or `idle`. Optional.
`hasUnpushedChanges`	boolean	Whether the branch has changes that have not been pushed. Optional.
`createdBy`	string	The ID of the user who created the branch. Optional.
`createdByName`	string	The name of the user who created the branch. Optional.
`lastActivityAt`	number	When the branch was last active, as epoch milliseconds. Optional.
`updatedAt`	number	When the branch was last updated, as epoch milliseconds. Optional.
`screenshot`	string	A screenshot of the branch. Optional.
`url`	string	The Builder editor URL for the branch.

Get message history

Review the prompts previously sent to a branch, ordered from oldest to newest. Use this context to understand what the branch is intended to do before asking the Builder Code agent to continue it.

Input

The project ID and branch name are required. Set a limit to control how many messages are returned. The default is 50 and the maximum is 200.

Example Prompt

Summarize the recent message history for the mobile-checkout branch before we make another change.

Parameter	Type	Required	Description
`projectId`	string	Yes	The ID of the project that contains the branch.
`branchName`	string	Yes	The name of the branch.
`limit`	number	No	The maximum number of messages to return. Defaults to 50 and is capped at 200.

Output

The result includes the project ID, the branch name, and the list of messages. Each message includes the text of the user prompt and, when available, a title.

Only user prompts are returned, not the agent replies. When older messages are truncated, the first message is always kept for context.

Field	Type	Description
`projectId`	string	The ID of the project that contains the branch.
`branchName`	string	The name of the branch.
`messages`	array	The user prompts previously sent to the branch, ordered from oldest to newest.
`messages[].userPrompt`	string	The text of the user prompt.
`messages[].title`	string	A title for the message. Optional.

List design systems

List the design systems available in the authenticated organization.

Input

This action takes no inputs.

Your AI client can use these results to identify the components and design guidance that should ground a Builder Code agent run. Mention the relevant design system in your build prompt when you want the generated UI to follow it.

Example Prompt

Which design systems are available for this organization, and which one should I use for our storefront project?

Output

Each design system in the results includes its ID, plus optional details such as its name, version, scope, and status. The results also include global design systems.

Field	Type	Description
`designSystems`	array	The design systems available in the authenticated organization, including global design systems.
`designSystems[].id`	string	The ID of the design system.
`designSystems[].name`	string	The name of the design system. Optional.
`designSystems[].version`	string	The version of the design system. Optional.
`designSystems[].scope`	string	The scope of the design system, such as global. Optional.
`designSystems[].status`	string	The status of the design system. Optional.

Get authenticated user

Return details about the authenticated user and the organization to which the current token is scoped.

Input

This action takes no inputs.

Use this before starting work to confirm your AI client is connected to the intended Builder account and organization.

Example Prompt

Which Builder user and organization is this Builder Code MCP connection authenticated as?

Output

The result includes details about the user, such as their ID, email, and name, along with the ID and name of the organization. Each token is scoped to exactly one organization.

Field	Type	Description
`userId`	string	The ID of the authenticated user. Optional.
`email`	string	The email address of the authenticated user. Optional.
`name`	string	The name of the authenticated user. Optional.
`org`	object	The organization the current token is scoped to.
`org.id`	string	The ID of the organization.
`org.name`	string	The name of the organization. Optional.

Follow a typical workflow

For a new project, ask your client to list available design systems, then start a Builder Code agent run without a project ID. Check the run until it completes and open the returned preview.

To continue existing work, use the project and branch tools to find the correct branch. Read its message history for context, then start a run with both the project ID and branch name. Check the new run until it completes.

Example Prompt

Find my storefront project and the checkout branch I created, summarize its recent message history, then continue that branch by adding an order confirmation state. Use our storefront design system and tell me when the run is complete.

What's next

Projects from Repositories

Developer Docs

Import from Figma

Was this article helpful?