Quickstart: Connect Your AI Assistant to CloudTalk

This guide connects an AI assistant to your CloudTalk account. By the end, the assistant can search your calls, read transcripts, and act on your account. See the Overview for everything it can do.

Prerequisites

A CloudTalk account on the Essential plan or higher; MCP isn’t available on Starter. Check your plan under Account → Billing, or compare plans.
An API Access Key ID and API Access Key Secret. If you haven’t generated these yet, follow the Authentication guide first.

Treat the key pair like a password: anyone holding it can read your call and contact data and act on your account through an assistant. Revoke it from the Dashboard at any time.

Encode Your API Key

The MCP server uses HTTP Basic authentication. Combine your key pair into one header value:

printf '%s:%s' 'YOUR_KEY_ID' 'YOUR_KEY_SECRET' | base64 | tr -d '\n'

tr -d '\n' matters: on Linux, base64 wraps long output across lines, and a line break inside the header value produces a 401.

Connect Your Client

The server URL is the same for every client:

https://mcp.cloudtalk.io

Claude Code
Claude.ai and Desktop
Cursor
ChatGPT
Other clients

claude mcp add --scope user --transport http -H "Authorization: Basic <BASE64>" -- cloudtalk https://mcp.cloudtalk.io

See Claude Code MCP documentation.

These share one connector mechanism — Claude reaches the server from Anthropic’s cloud, not from your machine, so the setup is identical in the browser and in the desktop app. You add the connector here, not on a phone; once it exists it is available in the Claude mobile apps too. Which Claude plans can add one, and any limits on how many, are Anthropic’s to state — see About custom connectors.

Check that the dialog has a Request headers section before you start. Anthropic’s request-header authentication is in beta and available to a limited set of organizations. If you do not see that section, your Claude organization does not have access yet and step 4 cannot be completed — being an organization owner does not grant it, because the setting is Anthropic’s rather than CloudTalk’s.Until it is enabled, connect through Claude Code or Cursor instead: both run on your own machine and send the header themselves, so neither depends on the beta. Access to the field is Anthropic’s to grant; CloudTalk cannot enable it for you.

On a personal plan: Customize → Connectors, then + → Add custom connector. On Team and Enterprise an organization owner does it in Organization settings → Connectors → Add, hovers Custom and picks Web; members then click Connect. If you are not an owner, you will not see the option at all.
Give it a Name and set Remote MCP server URL to https://mcp.cloudtalk.io, then Continue.
Change Authentication to None. This is the step that decides whether the connector works. Claude probes the server first and pre-selects Always required, marked Detected — accept that and the connection fails with “Couldn’t reach CloudTalk MCP. You can check the server URL and verify the server is running.” Nothing is wrong with the URL or the server: Claude is looking for an OAuth authorization server, CloudTalk MCP publishes none, and it reports the absence as an unreachable server. None is the right option and Claude’s own description of it says so — “for servers with open access, or for servers that use an API key instead of OAuth”. Picking it is also what makes the header below the connector’s credential rather than a supplement to an OAuth token, and it hides the OAuth client section, which does not apply.
Under Request headers — if the section is missing, see the warning above — click + Add header, pick authorization as the header name, and paste Basic <BASE64> from Step 1 as the value. Include the scheme — Claude’s own hint says the value is sent exactly as entered, so Basic with the trailing space must be part of what you paste. Leave Required checked.
Click Add, then toggle the connector on and start a new chat.

Header values are stored write-only — Claude never shows them again, so you cannot read back what is there to check it. Anthropic’s docs also state that authentication settings cannot be changed after a connector is added: to rotate the key, remove the connector and add it again with the new value.

The header is stored on the connector, not per person, so everyone who can use that connector acts as the CloudTalk company whose key it holds — including its write tools. On Team and Enterprise, that is everyone in the organization. Use a key from the account you mean to share.One CloudTalk account per Claude organization. A connector stores one header value and cannot be changed after it is added, so it reaches exactly one CloudTalk company — and Claude will not let you add a second connector for a second account. It checks the URL as you type it and rejects a duplicate: “A connector with this URL already exists in your organization. Use the existing connector instead of adding it again.” Only the URL is compared, not the name, and the check covers the whole organization, so whoever adds https://mcp.cloudtalk.io first claims it for everyone. If you work across several CloudTalk accounts, use Claude Code and register one server per account — it has no such limit.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cloudtalk": {
      "url": "https://mcp.cloudtalk.io",
      "headers": { "Authorization": "Basic <BASE64>" }
    }
  }
}

See Cursor’s MCP documentation.

MCP is an open protocol supported by many clients. Follow your client’s MCP setup instructions with https://mcp.cloudtalk.io as the server URL and the Authorization: Basic <BASE64> header. The Cursor configuration shape works for most.

To give the assistant a focused tool set for one job, append a profile name to the URL, e.g. https://mcp.cloudtalk.io/analytics. See Profiles.

Verify the Connection

Ask the assistant:

Run the cloudtalk_health_check tool.

A successful run confirms three things at once: your key was accepted, your company is enabled for MCP, and which company and user the key resolved to. Check the company ID matches the account you meant to connect.

An API Access Key belongs to the company, not to a person, so user_id comes back as 0. That is the expected value and means “no specific user” — not user number 0. Tools that act as a particular agent take that agent’s id as a parameter instead.

Ask Your First Question

Try:

Show me yesterday’s missed calls that have no tags.

You don’t call tools by name; ask in natural language and the assistant picks the right ones. More ideas in Common use cases.

Troubleshooting

Symptom	Fix
`401`	Re-encode the key; no line breaks in the base64 value; check the key wasn’t revoked
`403`	MCP isn’t enabled for your account. Confirm you’re on Essential or higher, then contact your CloudTalk representative
`429`	Rate limit. Wait a minute
Tools don’t appear	Restart the client after adding the connector
”A connector with this URL already exists in your organization”	Someone in your Claude organization has already added `https://mcp.cloudtalk.io`. Claude compares the URL, not the name, so a second connector for a second CloudTalk account is refused. Use the existing connector, or Claude Code for more than one account
No Request headers section in the Add custom connector dialog	Request-header authentication is a beta Anthropic enables per organization, and yours does not have it yet. Use Claude Code or Cursor, which send the header from your own machine. Enabling the field is Anthropic’s to do, not CloudTalk’s
”Couldn’t reach CloudTalk MCP” when adding a connector	The connector is set to an OAuth option; CloudTalk MCP has no OAuth metadata, so Claude cannot find an authorization server and reports it as unreachable. Re-add it with Authentication: None and an `authorization` request header
A tool returns “no data”	Run `cloudtalk_health_check` and confirm the company ID is the account you meant

Most errors carry a requestId; quote it when contacting support. A 401 is rejected at the gateway before one is generated, so for a 401 quote your API Key ID instead. It also carries no WWW-Authenticate challenge, so a client that waits for one before asking you for credentials will just see the request fail.

​Prerequisites

​Troubleshooting

Prerequisites

Troubleshooting