Skip to main content
Get started
DocumentationBuilder MCP + CLI Overview
Builder MCP + CLI

Builder MCP + CLI Overview

This page has been cleared and is ready for updated Builder Studio documentation.

BuilderStudio currently exposes two MCP connection surfaces. Use workspace-scoped builder_ API keys from Security → Workspace API Keys for the main BuilderStudio MCP endpoint at /api/mcp. Published user MCP servers use separate /api/user-mcp/<workspaceId>/<slug> endpoints and, when bearer auth is enabled, a separate owner-managed published-server bearer path, often a umcp_ key when the server owner issues one. Workspace builder_ keys do not unlock those endpoints.

How the flow works

  1. Create a workspace API key

    Create a builder_ key from Security → Workspace API Keys when you want to connect Claude Code, Cursor, or Codex to the main BuilderStudio MCP endpoint.

  2. Register BuilderStudio in your client

    Use the snippets in Dashboard setup. Cursor uses.cursor/mcp.json, Claude Code uses an HTTP add command, and Codex can use either codex mcp add or the custom MCP form.

  3. Call workspace tools

    Once connected, your agent can list canvases, inspect runs, trigger workflows, and use the BuilderStudio tool surface that your builder_ key scopes allow.

API key scopes

ScopeUse case
read:canvasesList canvases, inspect nodes, read run state, and power non-destructive tools.
run:workflowsTrigger executions, poll run state, and use workflow-running MCP tools.
write:canvasCreate canvases and mutate nodes, edges, and other canvas structure.
manage:integrationsCreate, edit, list, and revoke workspace integration credentials.
delete:canvasDelete canvases through the workspace MCP after explicit confirmation.

Endpoint split

EndpointKey typeWhat it is for
/api/mcpbuilder_Main BuilderStudio workspace tools and orchestration actions.
/api/user-mcp/<workspaceId>/<slug>Separate published-server bearer auth, often umcp_ when bearer auth is enabled, otherwise nonePublished user MCP servers exposed from BuilderStudio canvases. Public servers need no bearer token; protected servers use a separate published-server credential path.
Published server keys
Published user MCP servers do not reuse workspace builder_ keys. Protected published endpoints use a separate owner-managed published-server bearer path, typically a umcp_ key when the server owner issues API keys. Workspacebuilder_ keys do not unlock direct external client access to those published endpoints. If you own the server, manage its published API keys from the canvas MCP Server panel's API Keys tab. If you do not own it, ask the server owner for the published-server bearer token or exact outbound Authorization header value that endpoint expects. BuilderStudio does not issue self-serve marketplace tokens for protected published servers yet. Adding a marketplace server to a workspace registry is a BuilderStudio-internal install step. For bearer-protected published servers, use the marketplace install flow to save the server owner's bearer token as outbound headers during install, or add and rotate it later on Agent node > MCP Servers > Auth headers. BuilderStudio does not issue self-serve marketplace bearer tokens for protected published servers.

Was this page helpful?