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 Settings → Billing, or compare plans.
One of the two ways to authenticate:
- Sign in with CloudTalk (OAuth): a CloudTalk user with the Admin role. Available in Claude (Claude.ai, Claude Desktop, Claude mobile), Claude Code, ChatGPT and Gemini. Users with any other role are refused at sign-in.
- API Access Key: an API Access Key ID and API Access Key Secret, for every client that can send a request header. If you haven’t generated these yet, follow the Authentication guide first.

	Sign in with CloudTalk	API Access Key
Clients	Claude.ai, Claude Desktop, Claude mobile, Claude Code, ChatGPT, Gemini	Claude Code, Cursor, any client that can send a header; Claude.ai only with request-header connectors
Acts as	The admin who signed in	The company (`user_id` 0)
In a Claude Team or Enterprise organization	Each member signs in with their own CloudTalk account	Everyone shares the one key stored on the connector
To cut off access	Disconnect the connector in your assistant	Revoke the key in the Dashboard

Treat an API 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 (API key only)

Skip this step if you sign in with CloudTalk.With an 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 gets the request refused with a 403.

Connect Your Client

The server URL is the same for every client:

https://mcp.cloudtalk.io

Sign in with CloudTalk:

claude mcp add --scope user --transport http cloudtalk https://mcp.cloudtalk.io

Then run /mcp in Claude Code, pick cloudtalk and choose Authenticate. Your browser opens the CloudTalk sign-in page; sign in as an admin and approve the access on the consent screen.API key:

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.Sign in with CloudTalk:

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. 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.
Keep the Authentication option Claude detects and leave the OAuth client fields empty. Click Add.
Click Connect. Claude opens the CloudTalk sign-in page: sign in as an admin and approve the access on the consent screen. Claude returns you to the chat with the connector on.

On Team and Enterprise, the owner only adds the connector; each member clicks Connect and signs in with their own CloudTalk account.API key:

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. Sign in with CloudTalk instead.

Open the Add custom connector dialog as above.
Give it a Name and set Remote MCP server URL to https://mcp.cloudtalk.io, then Continue.
Change Authentication to None. Claude detects CloudTalk’s OAuth sign-in and pre-selects it; None is the option for “servers that use an API key instead of OAuth”, in Claude’s own words. It makes the header below the connector’s credential and hides the OAuth client section, which does not apply.
Under Request headers, 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.

A 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 connector per URL per Claude organization. Claude 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. With a header, that means one CloudTalk company per Claude organization; with sign-in, each member reaches the company of the account they sign in with.

Cursor connects with an API key. Add to ~/.cursor/mcp.json:

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

See Cursor’s MCP documentation.

ChatGPT connects by signing in with CloudTalk; it cannot send an API-key header.

In ChatGPT, click Plugins in the left menu, or go to Settings → Plugins → Browse directory.
Click Add → Add custom MCP server.
Enter a name such as CloudTalk, set Server URL to https://mcp.cloudtalk.io and Authentication to OAuth.
Tick I understand and want to continue, then click Create as a plugin. If you open Advanced OAuth settings, leave Registration method on Client Identifier Metadata Document (CIMD). The note “DCR is unavailable until a Registration URL is present” is expected: CloudTalk identifies ChatGPT through CIMD, so no client ID or secret is needed.
On the Connect CloudTalk screen, click Continue to CloudTalk. Sign in as an admin (skipped if you’re already signed in) and click Allow on the consent screen.
Click Try in chat to start a chat with the plugin enabled.

Which ChatGPT plans offer custom MCP servers is OpenAI’s to state. Menu names as of October 2026.

Gemini connects by signing in with CloudTalk; it cannot send an API-key header.

In Gemini, open the connected apps settings and add a custom MCP server with https://mcp.cloudtalk.io as the URL. Leave the client ID and secret under Additional settings empty. Whether your Google account can add custom connectors is Google’s to state; a Google Workspace admin may have turned them off.
Click Next. Gemini opens the CloudTalk sign-in page: sign in as an admin and approve the access on the consent screen.

Gemini currently has to sign in again roughly every 10 minutes. It does not request offline access, so CloudTalk issues it no refresh token, and the sign-in lasts only as long as one access token. Claude, Claude Code and ChatGPT stay connected.

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. Sign in with CloudTalk is available to Claude, Claude Code, ChatGPT and Gemini only for now.

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 credentials were accepted, your company is enabled for MCP, and which company and user they resolved to. Check the company ID matches the account you meant to connect.

Signed in with CloudTalk, user_id is your own user. An API Access Key belongs to the company, not to a person, so with a key user_id comes back as 0: that 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`	No credentials reached the server, or your sign-in expired. Sign in again (in Claude Code, `/mcp` → Authenticate); with an API key, check the client sends the `Authorization` header
`403`	With an API key: the key was refused. Re-encode it with no line breaks and check it wasn’t revoked. With either: MCP isn’t enabled for your account. Confirm you’re on Essential or higher, then contact your CloudTalk representative
Sign-in refused	Only CloudTalk users with the Admin role can connect by signing in. Sign in as an admin, or use an API key
`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. Use the existing connector: signed in, each member connects to their own 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. Sign in with CloudTalk instead, or use Claude Code or Cursor with the key
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 or a refused API key is rejected at the gateway before one is generated, so quote your API Key ID, or the email you signed in with, instead. A 401 carries a WWW-Authenticate challenge that points clients to CloudTalk’s sign-in.

​Prerequisites

​Troubleshooting

Prerequisites

Troubleshooting