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

# MCP Quickstart

> Connect PG:AI to Claude and other MCP clients

This guide gets you connected to the hosted PG:AI MCP server at `https://mcp.getpg.ai`. Most users connect **Claude** with OAuth; developers often use an **API key** in Cursor or scripts.

## Before you start

* A PG:AI account with access to at least one organisation
* For Claude: a plan that supports **Connectors** (Pro, Team, or Enterprise)
* For API key auth: permission to create keys in **Settings → API Keys**

***

## Option A - Claude (recommended)

Claude connects through a **Custom connector** and signs in with your PG:AI identity (OAuth). Your organisation is resolved automatically from your PG:AI user email - you do not paste an org ID into Claude.

### Step 1: Open Connectors in Claude

1. Open [Claude.ai](https://claude.ai) and sign in.
2. Go to **Settings** (profile menu → Settings).
3. Open **Connectors** (sometimes under **Integrations** depending on your plan).

<Info>
  **Screenshot needed:** Claude Settings → Connectors page with the **Add connector** button visible.
</Info>

### Step 2: Add the PG:AI connector

1. Click **Add connector** (or **Add custom connector**).
2. Enter a name, for example **PG:AI**.
3. Enter the server URL:

```
https://mcp.getpg.ai/mcp
```

If your Claude build only supports SSE connectors, use:

```
https://mcp.getpg.ai/sse
```

4. Save the connector.

<Info>
  **Screenshot needed:** The "Add custom connector" form filled in with name **PG:AI** and URL `https://mcp.getpg.ai/mcp`.
</Info>

### Step 3: Sign in with PG:AI

1. Claude will prompt you to authenticate.
2. Complete the PG:AI / Auth0 login with the **same email** as your PG:AI workspace user.
3. Approve access when asked.

<Warning>
  Your PG:AI account email must match your login email. Org membership is resolved server-side - if login succeeds but tools return no data, check that your user exists in the correct organisation in PG:AI.
</Warning>

<Info>
  **Screenshot needed:** OAuth consent / PG:AI login screen during connector authorisation.
</Info>

### Step 4: Enable the connector in a chat

1. Start a **new** chat in Claude.
2. Open the **+** or tools menu near the message box.
3. Enable the **PG:AI** connector for that conversation.

<Info>
  **Screenshot needed:** New chat with the PG:AI connector toggled on in the tools/connectors menu.
</Info>

### Step 5: Verify it works

Try these prompts in order:

| Prompt                                              | Expected behaviour                                            |
| --------------------------------------------------- | ------------------------------------------------------------- |
| *"List my tracked accounts"*                        | Calls `accounts` - returns companies in your territory or org |
| *"Get the company profile overview for Salesforce"* | Calls `company` with `include: ["overview"]`                  |
| *"What templates can I use to generate content?"*   | Calls `templates` - lists canvas and sequence recipes         |

If Claude says it cannot reach PG:AI or authentication failed, see [Troubleshooting](#troubleshooting) below.

### Claude Team / Enterprise

An **admin** can add the same connector once under **Admin settings → Connectors**. Each user still connects with their own PG:AI login so data stays scoped to their organisation membership.

***

## Option B - API key (Cursor, scripts, other clients)

Use this when OAuth is not available (for example Cursor or local testing).

### Step 1: Create an API key

<Steps>
  <Step title="Open Settings">
    In PG:AI go to **Settings → API Keys**
  </Step>

  <Step title="Create a key">
    Click **Create API Key**. Name it (e.g. "Cursor MCP"). Enable MCP scopes if prompted.
  </Step>

  <Step title="Copy the key">
    Copy the key immediately - it starts with `pgai_live_` and is only shown once.
  </Step>
</Steps>

<Info>
  **Screenshot needed:** PG:AI Settings → API Keys with **Create API Key** and scope selection visible.
</Info>

<Warning>
  Treat API keys like passwords. Revoke compromised keys in Settings immediately.
</Warning>

### Step 2: Configure Cursor

Create or edit `.cursor/mcp.json` in your project (or add via **Cursor Settings → MCP**):

```json theme={null}
{
  "mcpServers": {
    "pgai": {
      "url": "https://mcp.getpg.ai/mcp",
      "headers": {
        "x-api-key": "pgai_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

You can also use `Authorization: Bearer pgai_live_YOUR_KEY_HERE` instead of `x-api-key`.

Reload Cursor (**Cmd/Ctrl + Shift + P** → **Developer: Reload Window**). You should see **pgai** as a connected MCP server.

### Step 3: Verify with tools/list

Any MCP client can list tools with a JSON-RPC `tools/list` call. Example with curl:

```bash theme={null}
curl -s -X POST https://mcp.getpg.ai/mcp \
  -H "x-api-key: pgai_live_YOUR_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

You should see tools such as `company`, `search`, `accounts`, and `templates`.

***

## Connection details (reference)

| Setting             | Value                                                           |
| ------------------- | --------------------------------------------------------------- |
| Streamable HTTP URL | `https://mcp.getpg.ai/mcp`                                      |
| SSE URL             | `https://mcp.getpg.ai/sse`                                      |
| OAuth metadata      | `https://mcp.getpg.ai/.well-known/oauth-protected-resource`     |
| API key header      | `x-api-key: pgai_live_…` or `Authorization: Bearer pgai_live_…` |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude says authentication failed">
    * Confirm you completed OAuth with the same email as your PG:AI user.
    * Try removing and re-adding the connector.
    * For Team/Enterprise, confirm an admin enabled custom connectors.
  </Accordion>

  <Accordion title="Tools return 401 or authentication required">
    * API key: check the key starts with `pgai_live_` and was not revoked.
    * Claude: ensure the connector is **enabled for the current chat**.
  </Accordion>

  <Accordion title="Connector added but Claude never calls PG:AI">
    * Enable the connector in the chat's tools menu (not only in Settings).
    * Ask a PG:AI-specific question: *"Use PG:AI to list my accounts"*.
  </Accordion>

  <Accordion title="templates returns an error">
    Template discovery depends on the Data Hub and Xano template routes. If you see a UUID validation error, contact support - this is a known routing issue being fixed on the backend.
  </Accordion>

  <Accordion title="Cursor does not show pgai">
    * Reload the window after editing `mcp.json`.
    * Check JSON syntax and that the URL has no trailing slash issues.
  </Accordion>

  <Accordion title="Async jobs never finish">
    Generation and enrichment are asynchronous. After `template_generate`, `companies_add`, or `contact_find_email_phone`, poll `get_operation_status` every few seconds until `status` is `completed` or `failed`.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={3}>
  <Card title="Tools reference" icon="wrench" href="/platform/mcp/tools">
    All 22 tools and parameters
  </Card>

  <Card title="Examples" icon="message" href="/platform/mcp/examples">
    Prompts for research, contacts, and generation
  </Card>

  <Card title="Resources" icon="database" href="/platform/mcp/resources">
    Passive company and territory lists
  </Card>
</CardGroup>