Connect Builder Studio workflows to your AI agent over MCP

AI coding agents are useful because they can reason through work, write code, and call tools. They are much less useful when they have to infer your product process from screenshots or ask you to paste state back into chat. Builder Studio's MCP gateway gives an agent a direct, typed way to inspect canvases and run workflows you already built.

This guide connects a Builder Studio workspace to Claude Code, Cursor, or Codex over the Model Context Protocol. The supported path today is the workspace MCP endpoint: one workspace, one builder_ key, and a tool surface that lets an agent list canvases, read graph state, validate changes, and trigger workflow executions.

Why connect the workspace

A workflow on the canvas is already a durable process: it has nodes, inputs, outputs, connections, execution history, and reviewable state. Connecting the workspace over MCP lets an agent use that process instead of rebuilding it from scratch.

That matters for repeated work. If your team has a canvas for generating launch images, enriching records, checking copy, or running a multi-step media pipeline, the agent can call the real workflow and return the result to the task it is doing. The work stays visible in Builder Studio, while the agent gets a structured interface instead of a browser guessing game.

What the MCP gateway exposes

Builder Studio exposes the current workspace MCP server at:

https://builder.studio/api/mcp

Authentication is bearer-based. Use a workspace API key prefixed builder_, or an approved OAuth bearer token. The key's scopes decide what the connected agent can do.

The important distinction: the current supported surface is the workspace gateway, not a separate per-workflow public server. Your agent connects to Builder Studio once, then uses MCP tools to discover canvases, inspect state, and trigger the workflow you point it at.

Prepare the workflow

Before connecting an agent, make the target workflow tool-shaped:

• Give the canvas a clear name.
• Keep the workflow focused on one job.
• Make the expected inputs obvious.
• Make the final output easy to identify.
• Run it manually once so you know the canvas state is current.

For example, a "branded image" workflow might take a short creative brief, pass it through a Prompt node, run a Generate Image node, and leave the selected image as the result. The agent does not need to know every implementation detail. It needs to find the canvas, understand what it does, and trigger it with the right input.

Create a scoped workspace key

Open workspace settings in Builder Studio and create a workspace API key. Copy it when it is shown; raw keys are not shown again.

Start with the narrow scopes:

• read:canvases lets the agent inspect canvases and related state.
• run:workflows lets the agent trigger and monitor workflow executions.

Add broader scopes only when the job requires them:

• write:canvas lets the agent create or modify canvas state.
• manage:integrations lets the agent manage provider connections and policies.
• delete:canvas is destructive. Leave it off unless the workflow explicitly needs deletion.

For most agent automation, read:canvases plus run:workflows is the right starting point.

Connect your agent

Use the same endpoint and builder_ key across clients. Name the server builderstudio so prompts and tool references stay consistent.

Claude Code

claude mcp add --transport http builderstudio "https://builder.studio/api/mcp" \
  --header "Authorization: Bearer builder_YOUR_KEY_HERE"

Cursor

Add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "builderstudio": {
      "url": "https://builder.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer builder_YOUR_KEY_HERE"
      }
    }
  }
}

Codex

Codex stores the bearer token in an environment variable for streamable HTTP MCP servers:

export BUILDERSTUDIO_API_KEY="builder_YOUR_KEY_HERE"
codex mcp add builderstudio \
  --url "https://builder.studio/api/mcp" \
  --bearer-token-env-var BUILDERSTUDIO_API_KEY

Restart the client after adding the server. The Builder Studio tools should appear in the client's MCP tool list.

Run it safely

Ask the agent to use Builder Studio directly and name the target workflow:

Use the Builder Studio workspace to find the launch-image workflow, run it with this brief, and return the generated image URL plus any execution errors.

The agent should inspect the available canvases, choose the workflow, call the relevant execution tool, and report the structured result. If the workflow fails, the failure remains visible in Builder Studio where your team can debug the node, input, provider, or connection that caused it.

Keep the surface narrow

Treat an agent connection like any other production integration. Give it the scopes it needs, rotate keys when they leave your control, and separate read/run automation from write or integration-management work.

The point is not to hand an agent your whole product. The point is to let it call the workflow you already trust. Builder Studio stays the place where people build and inspect the process; MCP is the typed bridge that lets agents use that process without pretending to be a person in the browser.