Quickstart

Connect the Builder MCP to your MCP client — Cursor, Claude Code, Claude Desktop, or Codex — and you can build PolyAI agents from your IDE in minutes.

Prerequisites

Get access to a PolyAI workspace

You build agents inside a PolyAI workspace, so you need access to one first.

Enterprise customers — PolyAI provisions your workspace during onboarding; your PolyAI representative sets it up and grants you access. Enterprise workspaces are region-specific (US, UK, or EU).
Getting started via the website — sign up at poly.ai to create a self-serve workspace, which lives in the Studio region.

Get an API key

Create a workspace-scoped API key from the API Keys tab on your workspace homepage in Agent Studio (see API keys). Copy the value when it’s shown — the full key only appears once.

The API Keys tab in Agent Studio, showing the list of keys and the 'API key' button to create a new one

Treat the key like a password. Don’t commit it or put it in client-side code.

Find your account ID

Open Agent Studio. Your account ID is the first path segment in the URL:

https://studio.{region}.poly.ai/{account_id}/{project_id}/agent

For example, https://studio.uk.poly.ai/acme-uk/acme-team-4/agent → account_id=acme-uk.

“Account ID” and “Workspace ID” are the same thing. Agent Studio’s UI calls this the Workspace ID and shows it in a prefixed form (ws-xxxxxxxx). The API parameter is named accountId (Agents and Data APIs) or account_id (Conversations, Chat, Webhooks, and most other APIs) — same value, different casing convention depending on which API family you’re calling. Both the slug form from the URL (acme-uk) and the prefixed form (ws-xxxxxxxx) work in API calls.

1. Set your key and endpoint

export POLYAI_API_KEY="your_api_key_here"
export POLYAI_MCP_URL="https://api.us.poly.ai/builder-mcp"   # use your region — see below

Region	Endpoint
US	`https://api.us.poly.ai/builder-mcp`
UK	`https://api.uk.poly.ai/builder-mcp`
EU	`https://api.eu.poly.ai/builder-mcp`
Studio	`https://api.studio.poly.ai/builder-mcp`

Match the region to the workspace you build in. Connecting to the wrong region authenticates against the wrong workspace. See Authentication for how regions map to workspaces.

2. Add the server to your client

Cursor
Claude Code
Claude Desktop
Codex

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "polyai": {
      "url": "https://api.us.poly.ai/builder-mcp",
      "headers": { "X-API-KEY": "your_api_key_here" }
    }
  }
}

Restart Cursor, then open the MCP settings to confirm the PolyAI tools loaded.

claude mcp add --transport http polyai "$POLYAI_MCP_URL" \
  --header "X-API-KEY: $POLYAI_API_KEY" \
  --header "Accept: application/json, text/event-stream"

Verify with claude mcp list, then ask Claude to list its PolyAI tools.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "polyai": {
      "url": "https://api.us.poly.ai/builder-mcp",
      "headers": { "X-API-KEY": "your_api_key_here" }
    }
  }
}

Restart Claude Desktop. The PolyAI tools appear in the tools menu.

Add to your Codex MCP config:

[mcp_servers.polyai]
url = "https://api.us.poly.ai/builder-mcp"
headers = { "X-API-KEY" = "your_api_key_here" }

Most clients set the Accept: application/json, text/event-stream header for you. If a client can’t connect, add it explicitly — the server uses the streamable HTTP transport.

3. Verify

Ask your client to list its available tools, or test the endpoint directly:

curl -s -X POST "$POLYAI_MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-API-KEY: $POLYAI_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | grep '^data: ' | sed 's/^data: //' | jq '.result.tools | length'

A number greater than zero means the server is reachable and your key is valid.

Next steps

What Builder MCP can do

Browse the tools, grouped by agents, data, and alerts.

Build, test & deploy

Walk through the full lifecycle from branch to production.

Get started

Builder MCP

Agent Studio MCP integrations

Prerequisites

1. Set your key and endpoint

2. Add the server to your client

3. Verify

Next steps

What Builder MCP can do

Build, test & deploy

​Prerequisites

​1. Set your key and endpoint

​2. Add the server to your client

​3. Verify

​Next steps

What Builder MCP can do

Build, test & deploy

Prerequisites

1. Set your key and endpoint

2. Add the server to your client

3. Verify

Next steps