# MCP servers

Connect Claude, ChatGPT, Cursor and other AI assistants to your Vocenya account and to these docs with the Model Context Protocol.

Vocenya runs three [Model Context Protocol](https://modelcontextprotocol.io) servers over streamable HTTP. Point an AI assistant at them and it can work with your account or answer questions from these docs, without you writing any code.

| Server | URL | Authentication | What it does |
| --- | --- | --- | --- |
| Platform | `https://vocenya.com/mcp/platform` | API key | Your own account: calls, leads, bookings, chats, outbound calls and the Do Not Call list. |
| Docs | `https://vocenya.com/mcp/docs` | None | Read-only search over these developer docs and the API reference. |
| Site | `https://vocenya.com/mcp/site` | None | Read-only facts about Vocenya: pricing, products, industries and guides. |

## Platform MCP server

The platform server works on one business account: the one whose API key you connect with (or that an owner chose when connecting an app with [OAuth](#connect-with-oauth-no-key)). It uses the same [API keys and scopes](https://vocenya.com/docs/authentication) as the REST API, and shares the key's [rate limit](https://vocenya.com/docs/rate-limits). Each tool checks its own scope, so a key with only `leads:read` can list leads but not queue calls.

| Tool | What it does |
| --- | --- |
| `list_calls` | List phone calls the AI receptionist, GH Live agents or the team handled for this business, newest first. Filter by when the call started, its outcome (completed, missed, failed, blocked, ringing, in_progress), direction, and whether it was spam. Returns ids, numbers, timestamps, duration and, unless the account is in HIPAA mode, the AI summary. Needs the calls:read scope. |
| `get_call` | Get one phone call by id, with the leads captured on it. Unless the account is in HIPAA mode it also returns the AI summary and the transcript. Needs the calls:read scope. |
| `list_leads` | List leads (callers, chat visitors and form inquiries who left their details) for this business, newest first. Filter by phone number, email or when the lead was captured. Needs the leads:read scope. |
| `get_lead` | Get one lead by id: contact details, the reason they got in touch, urgency, and the call, chat or outbound call it came from. Needs the leads:read scope. |
| `create_lead` | Add a lead to this business, for example an inquiry from another system. It shows up in the Vocenya portal and syncs to a connected CRM. To have the AI call the person back right away (speed-to-lead), set callback_consent_text to the exact wording the person agreed to; that also needs the outbound:write scope, and the call still follows Do Not Call, consent and calling-hours rules. Needs the leads:write scope. |
| `list_bookings` | List appointments the AI booked into the business calendar, most recently booked first. Filter by appointment time. Needs the bookings:read scope. |
| `queue_outbound_call` | Ask the AI receptionist to call a person who has given consent for AI calls. Every call goes through the compliance check first: numbers on a Do Not Call list, numbers without AI-call consent on record, HIPAA marketing calls, accounts without outbound calling and trial accounts whose included AI minutes are used up are refused with a reason. Calls outside 8am-8pm local time, over the daily limit or while the number is already on a call are queued and ring later; the result says when. Nothing can bypass these rules. Needs the outbound:write scope. |
| `add_do_not_call` | Add a phone number to this business's Do Not Call list so the AI never calls it. Set opted_out when the person themselves asked not to be called: that is recorded permanently and revokes their consent. Needs the dnc:write scope. |
| `block_caller` | Block a phone number, or every number starting with a prefix (like 512555*), from calling this business: their inbound calls are turned away before the AI receptionist answers. For spam and robocallers; use add_do_not_call for numbers the business must not call. Needs the dnc:write scope. |
| `list_chats` | List website live chat conversations, newest first: who is handling each one (ai, with_agent, with_owner or closed), the page it started on, the lead it produced and, unless the account is in HIPAA mode, the handoff summary. Needs the chats:read scope. |

Outbound calls queued over MCP follow every [outbound rule](https://vocenya.com/docs/outbound-calls). Accounts in HIPAA mode never return transcripts, AI summaries or chat messages.

Create a key for your assistant under [Developers](https://vocenya.com/app/developers), with only the scopes it needs, and set it as `VOCENYA_API_KEY`.

### Claude Code

```bash
claude mcp add --transport http vocenya https://vocenya.com/mcp/platform \
  --header "Authorization: Bearer $VOCENYA_API_KEY"
```

### Cursor

In `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "vocenya": {
      "url": "https://vocenya.com/mcp/platform",
      "headers": {
        "Authorization": "Bearer ${env:VOCENYA_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Claude Desktop reaches servers that need a header through the `mcp-remote` bridge. In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vocenya": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vocenya.com/mcp/platform", "--header", "Authorization:${VOCENYA_AUTH}"],
      "env": {
        "VOCENYA_AUTH": "Bearer paste-your-key-here"
      }
    }
  }
}
```

### Other clients

Any MCP client that supports streamable HTTP and custom headers works: use the URL above and send `Authorization: Bearer <your key>`.

### Connect with OAuth (no key)

Clients that sign in with OAuth, such as Claude connectors, can connect without a key: add `https://vocenya.com/mcp/platform` as a custom connector. The client registers itself, then sends an account owner to a Vocenya sign-in and consent screen to choose the account, live or test data, and the permissions (the same scopes as API keys). The app's access works exactly like a key with those scopes, including HIPAA mode. Owners see and disconnect connected apps under [Developers](https://vocenya.com/app/developers).

The server supports OAuth 2.1 authorization code with PKCE (S256) and dynamic client registration. A request without a credential gets `401` with a `WWW-Authenticate` header pointing at the protected resource metadata.

## Docs MCP server

The docs server lets an assistant look things up in these docs while it writes your integration, so it uses real endpoints, parameters and limits instead of guessing. It is public and read-only, needs no key and is limited to 60 requests a minute per IP address. Its answers are generated from the same source as these pages, so they always match.

| Tool | What it does |
| --- | --- |
| `search_docs` | Search the Vocenya developer docs: guides (authentication, webhooks, pagination, outbound calling rules, live chat, MCP) and every API endpoint. Returns the best matches with their page URL; read one with get_doc_page or get_endpoint. |
| `get_doc_page` | Get one page of the Vocenya developer docs as Markdown, exactly as published. Slugs: "index", a guide like "quickstart", "authentication", "webhooks", "webhook-events", "outbound-calls", "live-chat" or "mcp", "reference" for the API overview, or "reference/leads" for a resource's endpoints. Use search_docs to find a slug. |
| `list_endpoints` | List the endpoints of the Vocenya REST API with their method, path, summary and required scope, grouped by resource. Pass a tag (resource) like "Leads" or "Webhooks" to list one resource. Get the details of one with get_endpoint. |
| `get_endpoint` | Get one Vocenya API endpoint in full, as Markdown: its scope, path and query parameters, request body, responses, response attributes and code samples in cURL, Node, PHP and Python. Example: method "POST", path "/leads". |

### Claude Code

```bash
claude mcp add --transport http vocenya-docs https://vocenya.com/mcp/docs
```

### Cursor

```json
{
  "mcpServers": {
    "vocenya-docs": {
      "url": "https://vocenya.com/mcp/docs"
    }
  }
}
```

### Claude and Claude Desktop

Add a custom connector under Settings → Connectors with the URL `https://vocenya.com/mcp/docs`. No authentication is needed.

### ChatGPT

Add a custom connector in ChatGPT's developer mode with the URL `https://vocenya.com/mcp/docs` and no authentication.

## Without MCP

Every docs page is also plain Markdown: add `.md` to its URL, or use the **Copy for LLM** menu on the page. [llms.txt](https://vocenya.com/docs/llms.txt) lists every page, and [llms-full.txt](https://vocenya.com/docs/llms-full.txt) has the whole docs in one file.