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

# MCP Server

> Connect Allo to AI assistants like Claude, Cursor, and VS Code using the Model Context Protocol

Connect Allo to any AI assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Search calls, read transcripts, send SMS, manage tags, and analyze team performance — directly from your AI tool.

<Card title="Using Claude.ai instead?" icon="link" href="/en/integrations/claude-connector">
  Connecting from Claude.ai web or desktop? See the Claude Connector guide — no API key needed.
</Card>

## Prerequisites

<Steps>
  <Step title="Get an API key">
    Go to [Settings > API](https://web.withallo.com/settings/api) and click **Create API Key**.

    Select the scopes your workflow needs. For full MCP access, enable all scopes. For read-only access, select only the `READ` scopes.

    Copy the key — it won't be shown again.
  </Step>

  <Step title="Choose your AI client">
    Follow the setup instructions for your client below.
  </Step>
</Steps>

<Warning>
  Only **admins** and **owners** can create API keys. Team members cannot generate keys.
</Warning>

## Connect your AI client

### Claude Code

Run this command in your terminal:

```bash theme={null}
claude mcp add Allo --transport http https://mcp.withallo.com/mcp \
  --header "Authorization: YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your Allo API key.

### Claude Desktop

Open **Settings > MCP** in Claude Desktop and add a new server with this configuration:

```json theme={null}
{
  "mcpServers": {
    "Allo": {
      "url": "https://mcp.withallo.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor

Open **Settings > MCP** in Cursor, click **Add new MCP server**, and select **Type: HTTP**.

Alternatively, add this to your `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "Allo": {
      "url": "https://mcp.withallo.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

Add this to your `.vscode/mcp.json` file (create it if it doesn't exist):

```json theme={null}
{
  "servers": {
    "Allo": {
      "type": "http",
      "url": "https://mcp.withallo.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}
```

### Windsurf

Open **Settings > MCP** in Windsurf and add:

```json theme={null}
{
  "mcpServers": {
    "Allo": {
      "serverUrl": "https://mcp.withallo.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}
```

### Other clients

Any MCP-compatible client can connect to Allo using:

* **Server URL:** `https://mcp.withallo.com/mcp`
* **Transport:** HTTP
* **Authentication:** `Authorization` header with your API key

Refer to your client's documentation for how to configure remote MCP servers with custom headers.

## Available tools

Once connected, your AI assistant can use these 16 tools:

| Tool                                | What it does                                                                                                         |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `allo_get_me`                       | Discover your API key's scopes, available endpoints, and team info                                                   |
| `allo_list_users`                   | List team members with roles and status                                                                              |
| `allo_list_numbers`                 | List phone numbers with capabilities (voice, SMS)                                                                    |
| `allo_list_tags`                    | List all tags configured on your team                                                                                |
| `allo_list_conversations`           | List conversations grouped by contact, sorted by recent activity                                                     |
| `allo_search_conversation_items`    | Search calls and SMS with filters: keyword, type, direction, tags, date range                                        |
| `allo_get_conversation_item`        | Get full details of a call or SMS, including transcript                                                              |
| `allo_batch_get_conversation_items` | Fetch up to 100 items in a single request                                                                            |
| `allo_mark_conversation`            | Mark conversations as read, unread, archived, or unarchived                                                          |
| `allo_add_call_tags`                | Add tags to a call                                                                                                   |
| `allo_remove_call_tag`              | Remove a tag from a call                                                                                             |
| `allo_send_sms`                     | Send an SMS from one of your Allo numbers                                                                            |
| `allo_get_team_analytics`           | Get team KPIs: total calls, talk time, answer rate, per-user breakdown                                               |
| `allo_get_team_outbound_analytics`  | Get outbound metrics: dial funnel, time series, heatmap, leaderboard                                                 |
| `allo_get_dialing_queue`            | Read the user's Power Dialer queue: settings, ordered numbers, and per-entry call state                              |
| `allo_add_to_dialing_queue`         | Append numbers to the user's Power Dialer queue (creates the queue on first call); accepts optional contact metadata |

## Required scopes

Each tool requires specific API key scopes. Select the scopes matching the tools you need:

| Scope                      | Tools                                                              |
| -------------------------- | ------------------------------------------------------------------ |
| `CONVERSATIONS_READ`       | List conversations, search, get item, batch get, mark conversation |
| `USERS_READ`               | List users, get me                                                 |
| `PHONE_NUMBERS_READ`       | List numbers                                                       |
| `TAGS_READ`                | List tags                                                          |
| `TAGS_WRITE`               | Add tags, remove tag                                               |
| `SMS_SEND`                 | Send SMS                                                           |
| `DIALING_QUEUE_READ_WRITE` | Read and append to the Power Dialer queue                          |

<Note>
  For full access to all 16 tools, select all scopes when creating your API key.
</Note>

## Example prompts

Once connected, try asking your AI assistant:

* "Show me all missed calls from this week"
* "What was my team's answer rate last month compared to the month before?"
* "Find all calls tagged 'demo' from the past 30 days and summarize the transcripts"
* "Send an SMS to +33612345678 from my main number saying we'll call back in 10 minutes"
* "Who on my team made the most outbound calls this week?"
* "List all unread conversations and mark them as read"
* "Tag the last 5 inbound calls as 'support'"
* "Show me what's in my Power Dialer queue right now"
* "Add these numbers to my Power Dialer queue: +14155551234, +33612345678"

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed or unauthorized">
    Verify your API key is correct and has not been revoked. Go to [Settings > API](https://web.withallo.com/settings/api) to check your active keys. If needed, create a new key.
  </Accordion>

  <Accordion title="Tool returns a permission error">
    Your API key is missing a required scope. Check the [required scopes](#required-scopes) table above and create a new key with the needed scopes.
  </Accordion>

  <Accordion title="Tools not appearing in my AI client">
    Make sure the MCP server is connected and active. Restart your AI client and verify the server URL is exactly `https://mcp.withallo.com/mcp`. Some clients require a restart after adding a new MCP server.
  </Accordion>
</AccordionGroup>

## Need help?

<CardGroup cols={2}>
  <Card title="API authentication" icon="key" href="/en/v2/api-reference/guides/authentication">
    Full API key and scopes documentation
  </Card>

  <Card title="Contact support" icon="headset" href="mailto:support@withallo.com">
    Get help from the Allo team
  </Card>
</CardGroup>