> ## Documentation Index
> Fetch the complete documentation index at: https://polyai-mintlify-7055a538.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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

Connect one of PolyAI's authenticated MCP servers 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 drive PolyAI from your IDE in minutes.

Pick the server for the job:

<CardGroup cols={2}>
  <Card title="Builder MCP" icon="wrench" href="/mcp/builder/introduction">
    Build, test, and deploy agents. Uses an **account API key** and the `/builder-mcp` endpoint.
  </Card>

  <Card title="Data MCP" icon="chart-line" href="/mcp/data/introduction">
    Query conversations, transcripts, and metrics. Uses an **account API key** and the `/data-mcp` endpoint.
  </Card>
</CardGroup>

The steps below use Builder MCP. Data MCP connects the same way — swap the endpoint path to `/data-mcp`; the same account API key works for both. See [Data MCP → Get started](/mcp/data/introduction#get-started) for its exact commands.

## 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 an **account API key** from the **API Keys** tab on your workspace homepage in Agent Studio (see [API keys](/secrets/api-keys)). The same key works for both Builder MCP and Data MCP — see [Authentication](/mcp/authentication).

    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-mintlify-7055a538/Gn375iHW6pcLBJ3J/images/secrets/api-keys-overview.png?fit=max&auto=format&n=Gn375iHW6pcLBJ3J&q=85&s=a9bb7256d6a4a863f3dfd90ef920d5ba" 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 and server — see below
```

| Region | Builder MCP                              | Data MCP                              |
| ------ | ---------------------------------------- | ------------------------------------- |
| US     | `https://api.us.poly.ai/builder-mcp`     | `https://api.us.poly.ai/data-mcp`     |
| UK     | `https://api.uk.poly.ai/builder-mcp`     | `https://api.uk.poly.ai/data-mcp`     |
| EU     | `https://api.eu.poly.ai/builder-mcp`     | `https://api.eu.poly.ai/data-mcp`     |
| Studio | `https://api.studio.poly.ai/builder-mcp` | `https://api.studio.poly.ai/data-mcp` |

Match the region to the workspace or account your key belongs to. Connecting to the wrong region authenticates against the wrong place. See [Authentication](/mcp/authentication#pick-your-region) for how regions map.

## 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 — both servers use the streamable HTTP transport.
</Tip>

<Tip>
  Connecting to both servers at once? Add them under distinct names (e.g. `polyai-builder` and `polyai-data`), each with its own endpoint and key.
</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>

  <Card title="Query data with Data MCP" icon="chart-line" href="/mcp/data/introduction">
    Search conversations, read transcripts, and aggregate metrics.
  </Card>

  <Card title="Consume external tools" icon="plug" href="/mcp/agent-studio-integrations">
    Connect a live agent out to a third-party MCP server.
  </Card>
</CardGroup>