Skip to main content
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

1

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.
2

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.
3

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
RegionEndpoint
UShttps://api.us.poly.ai/builder-mcp
UKhttps://api.uk.poly.ai/builder-mcp
EUhttps://api.eu.poly.ai/builder-mcp
Studiohttps://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

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.
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.
Last modified on July 9, 2026