# MCP Connector (https://docs.hallolara.ai/docs/mcp)

The Hallolara MCP connector lets ChatGPT, Claude, Cursor, and other Model Context
Protocol clients read and configure your Hallolara organization. It follows the same
permissions, plan features, and field names as the Public API.

There are no resource-specific MCP URLs. Give the client one remote connector
URL; it runs MCP discovery, lists the tools available to the credential, and
calls them through the same endpoint.

Connector URL: `https://api.hallolara.ai/mcp`

The transport is stateless JSON-RPC over `POST /mcp`. A client that sends raw
HTTP must include `Accept: application/json, text/event-stream` and
`Content-Type: application/json`; otherwise the request fails with `406` or
`415`. `GET /mcp` and `DELETE /mcp` are not application endpoints.
OAuth-capable clients discover the authorization server through the published
`/.well-known/*` metadata; you do not configure those URLs manually.

## Connect with OAuth [#connect-with-oauth]

OAuth is the recommended setup for interactive AI clients:

1. Add a custom or remote MCP connector and enter the connector URL above.
2. Follow the browser sign-in link. A current dashboard session can continue
   directly to consent; otherwise sign in first.
3. Select the organization, review the requested scopes, and approve.
4. Return to the client and let it discover the available Hallolara tools.

The connector supports `mcp:read` and `mcp:write`. The access token is bound
to the selected organization, but Hallolara reloads the user's current lifecycle,
membership, and role on every request. Role edits, membership removal, and
account deletion therefore take effect without waiting for token expiry.
Disconnect and reconnect to select a different organization.

In ChatGPT developer mode, Claude.ai, and Cursor, use their custom/remote MCP
connector screen and the same URL. Exact menu labels can change; no
client-specific Hallolara endpoint is required.

## Connect with an API key [#connect-with-an-api-key]

For clients that support custom HTTP headers, create a key under **Settings →
API Keys → New key**, choose the narrowest suitable role, and configure:

```text
Authorization: Bearer <your_api_key>
```

Claude Code example:

```bash
claude mcp add --transport http hallolara https://api.hallolara.ai/mcp \
  --header "Authorization: Bearer <your_api_key>"
```

The key is the same organization key accepted by the Public API. It is shown
once: keep it in a secret manager and never paste it into a chat prompt. Delete
the key in the dashboard to revoke the connection.

## Access rules [#access-rules]

Every request must pass all applicable checks:

- The organization needs API access (`api_access`). Whether it is included
  depends on the plan.
- OAuth is limited by the granted read/write scopes and the user's current
  organization role. API keys are limited by the role selected for the key.
- Tool-specific product features still apply. For example, forwarding tools
  require call forwarding, prompt tools require custom prompts, webhook tools
  require tools, and website-chat tools require widgets.
- `tools/list` hides tools the credential cannot use, and every call repeats
  the checks. MCP exposes no delete tools.

The default **Member** role sees only `list_calls`, `get_call`, and
`get_statistics`. Configuring assistants, knowledge, prompts, groups, glossary,
pronunciation, forwardings, or webhook tools requires **Admin** or a custom
role with the corresponding permissions. Reading website chats needs a role
that can view Inbox conversations, such as **Admin**.

The connector exposes tools for assistants, voices and purchased phone numbers,
prompts, knowledge, groups, glossary, pronunciation, forwardings, webhook tools,
call logs, website chats, and statistics. Inputs use the same `snake_case` fields as the
[Public API reference](/docs/public). List, create, and update tools reject
unknown fields.
Knowledge writes trigger asynchronous indexing; poll the returned item's
`sync_status` instead of assuming it is immediately searchable.

Call logs are read-only. `get_call` returns the same call detail as the Public
API, including `mailbox_detection` for an outbound call that was started with
mailbox detection. The connector cannot start calls.

Website chats are read-only too. `list_chats` and `get_chat` return the chats
from your website widget and the messages the visitor saw, as the Public API
does. Visitor messages are text anyone on your website can type, so AI clients
are told to treat them as information, never as instructions. Replying and
taking over stay in the dashboard Inbox.

Every assistant created through the connector holds a phone number until you
delete it in the dashboard, because the connector has no delete tools. To give
a new assistant one of your organization's purchased numbers, pass an `id` from
`list_phone_numbers` as `phone_number_id`; otherwise the platform assigns one.
Organizations that route calls through their own assigned carrier must pass
`phone_number_id`.

Webhook tool secrets and passwords are write-only: Hallolara stores them encrypted
and never returns them. A credential you give an AI client stays in that client's
conversation history, so you can enter it in the dashboard instead. Never put
credentials in webhook headers: headers are stored and returned in plaintext.
Changing the URL of a webhook that has a stored credential requires entering
the credential again, so a credential never moves to a new URL on its own.

## Troubleshooting and revocation [#troubleshooting-and-revocation]

| Status | Meaning | Action |
|---|---|---|
| `401` | Missing, expired, or invalid credential | OAuth clients should authorize; API-key clients should replace the key |
| `402 subscription_required` | The organization lacks `api_access` | Enable the entitlement; do not reconnect OAuth |
| `403` | The current user or organization lifecycle blocks the connection | Resolve the account state |
| `429` | MCP rate limit exceeded | Honor `Retry-After` when present and back off |
| `503` | OAuth is unavailable or the current organization role context cannot be loaded | Retry; API-key access remains available when only OAuth is unconfigured. A lasting `ORGANIZATION_AUTHORIZATION_INVALID` can mean the user is no longer a member: reconnect |

Disconnecting or revoking OAuth invalidates the grant and refresh token. An
access token already issued keeps working until it expires, at most one hour;
removing the user from the organization takes effect at once. API-key
connections remain active until the key is deleted or the organization is
blocked. See [Errors & Rate
Limits](/docs/errors) for response shapes and limits.
