> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect PolyAI's Builder MCP to your MCP client in one command.

Connect the [Builder MCP](/mcp/builder/introduction) to your MCP client — [Cursor](https://cursor.com), [Claude Code](https://www.claude.com/product/claude-code), [Claude Desktop](https://claude.ai/download), or [Codex](https://developers.openai.com/codex/cli/) — and you can build PolyAI agents from your IDE in minutes.

## Prerequisites

<Steps>
  <Step title="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](https://poly.ai) to create a self-serve workspace, which lives in the Studio region.
  </Step>

  <Step title="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](/secrets/api-keys)). Copy the value when it's shown — the full key only appears once.

    <Frame caption="Create a key from the API Keys tab in Agent Studio.">
      <img src="https://mintcdn.com/polyai/XrMtC1rV8-sgJgHo/images/secrets/api-keys-overview.png?fit=max&auto=format&n=XrMtC1rV8-sgJgHo&q=85&s=6274a720218a02525d85365d20600256" alt="The API Keys tab in Agent Studio, showing the list of keys and the 'API key' button to create a new one" style={{ maxWidth: '820px', width: '100%', margin: '0 auto', display: 'block' }} width="2358" height="1388" data-path="images/secrets/api-keys-overview.png" />
    </Frame>

    Treat the key like a password. Don't commit it or put it in client-side code.
  </Step>

  <Step title="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`.

    <Note>
      **"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.
    </Note>
  </Step>
</Steps>

## 1. Set your key and endpoint

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/mcp/authentication#pick-your-region) for how regions map to workspaces.

## 2. Add the server to your client

<Tabs>
  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Tab>

  <Tab title="Claude Desktop">
    Add to your `claude_desktop_config.json`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.
  </Tab>

  <Tab title="Codex">
    Add to your Codex MCP config:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [mcp_servers.polyai]
    url = "https://api.us.poly.ai/builder-mcp"
    headers = { "X-API-KEY" = "your_api_key_here" }
    ```
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

## 3. Verify

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={2}>
  <Card title="What Builder MCP can do" icon="wrench" href="/mcp/builder/capabilities">
    Browse the tools, grouped by agents, data, and alerts.
  </Card>

  <Card title="Build, test & deploy" icon="rocket" href="/mcp/builder/walkthrough">
    Walk through the full lifecycle from branch to production.
  </Card>
</CardGroup>