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

# MCP Quickstart

> Connect your AI client to HoopAI in 3 steps using the MCP server.

Get your AI assistant connected to HoopAI in under 5 minutes.

## Step 1: Get a Private Integration Token

Go to **Settings → Integrations → Private Integrations** in your HoopAI account.

Click **Create New Integration**, select the required scopes for the tools you want to use, and copy the generated token.

<Tip>
  For full access to all 36 MCP tools, see the [complete scope list](/developer/mcp/platform-mcp-server#required-scopes). For a quick start, enable **View Contacts**, **View Conversations**, and **View Locations** to test basic queries first.
</Tip>

## Step 2: Configure your client

Add the MCP endpoint and your token to your agent configuration. The `locationId` in the header is optional — you can also pass it in prompts.

<Tabs>
  <Tab title="Generic MCP client">
    ```json theme={null}
    {
      "mcpServers": {
        "hoopai-mcp": {
          "url": "https://services.leadconnectorhq.com/mcp/",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "locationId": "YOUR_LOCATION_ID"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    In your MCP settings, add a new server:

    * **URL:** `https://services.leadconnectorhq.com/mcp/`
    * **Transport:** HTTP Streamable
    * **Headers:**
      * `Authorization: Bearer YOUR_API_KEY`
      * `locationId: YOUR_LOCATION_ID`
  </Tab>

  <Tab title="n8n">
    In your n8n workflow, add the **MCP Client** node:

    1. **MCP URL:** `https://services.leadconnectorhq.com/mcp/`
    2. **Transport:** HTTP Streamable *(requires n8n v1.104+)*
    3. **Auth type:** Header-based
    4. **Key:** `Authorization` / **Value:** `Bearer YOUR_API_KEY`
    5. **Location ID:** Add as a header or set in the LLM system prompt:
       ```
       The location id is YOUR_LOCATION_ID
       ```

    See [n8n integration](/developer/mcp/hoopai-proxy) for a full walkthrough.
  </Tab>
</Tabs>

## Step 3: Test with a prompt

Once connected, try these prompts to verify everything is working:

```
Show me my last 10 contacts
```

```
Find all unread conversations and summarize them
```

```
What calendar events do I have tomorrow?
```

```
Search opportunities in my pipeline
```

## Using locationId dynamically

The MCP server supports two patterns for passing your Location ID:

**Option A — Header (recommended for single-account use):**

```json theme={null}
"headers": {
  "Authorization": "Bearer YOUR_API_KEY",
  "locationId": "YOUR_LOCATION_ID"
}
```

**Option B — System prompt (useful for multi-account setups):**

```
The location id is YOUR_LOCATION_ID
```

## Troubleshooting

| Error              | Cause                                  | Fix                                                     |
| ------------------ | -------------------------------------- | ------------------------------------------------------- |
| `401 Unauthorized` | Invalid or expired token               | Re-generate your Private Integration Token              |
| `403 Forbidden`    | Missing scope                          | Add the required scope in Private Integrations settings |
| `400 Bad Request`  | Missing or wrong `locationId`          | Pass `locationId` in headers or prompt                  |
| No tool responses  | Client doesn't support HTTP Streamable | Use the npx proxy package *(coming soon)*               |