> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude connector
> Add the Retell AI connector to Claude to build, edit, deploy, test, and analyze voice agents from a chat, with OAuth sign-in and interactive widgets.
The **Retell AI** connector lets you build, edit, deploy, test, and analyze [voice agents](/build/choose-agent-type) from a conversation with Claude. You sign in with your Retell login, and multi-step tasks such as building, deploying, and testing an agent open as interactive widgets inside the chat.
This page covers the Retell AI connector in Claude's connectors directory, which signs in with OAuth. For Cursor, Claude Code, Claude Desktop config files, and other MCP clients that use a Retell API key, see the [Retell MCP server](/get-started/mcp-server).
## When to use it
Use the connector when you want to describe an agent in plain language and have Claude set it up, or make quick changes to an existing agent without opening the dashboard.
Use the [dashboard](https://dashboard.retellai.com) instead when you need settings the widgets don't expose, such as [conversation flow](/build/conversation-flow/overview) agents, knowledge bases, [integrations](/integrations/overview), or credentials for custom functions. The connector builds single-prompt agents. It can't edit conversation flow agents.
### Example
A restaurant owner asks Claude for a receptionist agent for Bella's Bistro that takes reservations and answers questions about the menu and opening hours. Claude opens the build wizard with those details filled in, writes the prompt, lets them pick a voice, and creates the agent. They then put it on the restaurant's Retell number and place a test call to their own phone.
## Before you start
* A Retell account at [dashboard.retellai.com](https://dashboard.retellai.com) with at least one workspace.
* A Claude account. On Free, Pro, and Max plans you connect directly. On Team and Enterprise plans, an organization owner adds the connector under **Organization settings > Connectors** first, and then each member connects with their own Retell login. See [Use connectors](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities). The widgets render in Claude on the web and in Claude Desktop.
* To deploy an agent or place a call, a [Retell phone number](/deploy/purchase-number) in the workspace. Outbound calls also require [KYC](/accounts/kyc), which some accounts pass automatically.
* Usage through the connector is billed to your Retell workspace like any other usage. Test calls and test chats cost the same as live ones. See [Testing pricing](/test/testing-pricing).
## Connect Retell AI to Claude
In Claude, open **Customize > Connectors**, browse the directory, and search for **Retell AI**.
Select **Connect** and sign in with the email you use for the Retell dashboard. The connector uses OAuth 2.0, so Claude never sees your Retell password.
If your login belongs to one workspace, the connector selects it for you. If it belongs to several, Claude shows the list and asks which one to use. The choice is saved for your login and carries over to new chats. To change it later, ask Claude to switch to another workspace by name.
You don't need to configure anything else. The connector finds your workspaces, agents, and phone numbers on its own.
To disconnect, remove the connector in Claude's connector settings. Claude then has no access to your Retell account until you connect again.
## What you can do
* **Build an agent.** A wizard collects the agent's name, purpose, audience, tone, and language, writes a prompt, lets you pick a voice with audio previews, and adds functions such as [call transfer](/build/single-multi-prompt/transfer-call), custom API calls, data extraction, agent swap, [SMS](/deploy/enable-sms), and [press digit](/build/single-multi-prompt/press-digit).
* **Edit an agent.** Change the voice, name, language, or prompt. Prompt changes appear side by side with the current prompt before you apply them. You can also set default values for [dynamic variables](/build/dynamic-variables) and add, change, or remove functions.
* **Deploy an agent.** Assign the agent to one of your Retell numbers for inbound calls, outbound calls, or both. The deploy screen shows which agent is on each number today.
* **Test an agent.** Chat with the agent in text, or have it place a real phone call from one of your numbers after you confirm the details.
* **Analyze calls.** Filter call history, open a call's transcript, recording, and analysis, and see call volume, success rate, sentiment, and latency for an agent.
Calendar booking and other connected apps are set up on the **Integrations** page in the dashboard, not through the connector. After you connect a provider there, you can add its functions to any agent in the dashboard. See [Integrations](/integrations/overview).
The connector doesn't take credentials in the chat. It never asks for a Cal.com key or another integration's credentials. For custom functions, you add HTTP headers and query parameters, which often hold API keys, in the dashboard after the agent is created, and the connector refuses a function URL that contains a password, a key-like parameter (in the query or after `#`), a value that looks like an API key, or a webhook secret in its path (Slack, Discord, Zapier, Make, Telegram, IFTTT, Microsoft Teams). It checks when it creates an agent, when it adds or edits a custom function, and before it fills in a widget. A new dynamic variable value that looks like an API key is refused too, and a function with credentials saved in the dashboard can only be moved, from the chat, to another `https://` address on the same host.
## Usage examples
**Build an agent.** "Build me a receptionist agent for a dental clinic. It should answer questions about hours and insurance and transfer billing questions to the front desk."
Claude opens the build wizard with those details filled in and writes a prompt. You pick a voice and review the functions, and the connector creates the agent in your workspace.
**Edit the prompt.** "Show me the prompt for my receptionist agent and make it more concise."
Claude shows the current prompt next to the shorter version. Nothing changes until you apply it.
**Deploy to a number.** "Put my receptionist agent on my Retell number for inbound calls."
The deploy screen lists your numbers and the agent on each one. If another agent already answers the number you pick, you confirm the replacement before it happens.
**Test with a phone call.** "Have my receptionist agent call my phone at +14155551234 so I can hear it."
Claude shows the agent, the number it calls from, and the number it calls, and waits for you to confirm before Retell dials.
**Review calls.** "How did my receptionist agent do this week? Show me the calls that failed."
The analytics view shows call volume, success rate, duration, and latency, and you can open any call's transcript and recording.
## Which actions ask for confirmation?
Three actions take effect outside Claude, so the connector runs them in two steps. The first step returns a preview and changes nothing. The action only runs after you confirm. You confirm a call in the test widget or in the chat, a deletion in the chat, and a number replacement in the deploy widget.
| Action | What the preview shows | What happens when you confirm |
| - | - | - |
| Place an outbound call | The agent, the number it calls from, and the number it calls | Retell dials the number. The person who answers talks to your agent. |
| Delete an agent | The agent's name and any phone numbers routed to it | The agent is deleted permanently, and those numbers are left without an agent. |
| Deploy to a number another agent already uses | The agent on the number today, with each agent's share of calls if the number splits them | Your agent replaces it on that number immediately. |
A confirmation covers only the exact request in its preview, in the same workspace, and works once, even if the same request arrives twice. If anything in the request changes, or the confirmation is older than 2 minutes for a call or 5 minutes for a deletion or replacement, the connector asks again.
The connector checks that a confirmation matches its preview, but it can't tell whether you or Claude sent it. Claude asks for your approval in the chat before it confirms, so read the preview before you approve.
Deleting an agent can't be undone. Check the numbers listed in the preview first, because they stop answering with an agent once it is deleted.
### Outbound calls
Outbound calls from the connector are meant for testing an agent, usually by calling your own phone. The connector can't verify that a number belongs to you, so it doesn't limit calls to your own numbers. Instead, every call needs your confirmation of the exact destination, and the checks below apply. The call goes from a Retell number in the selected workspace to the number you give, in E.164 format such as `+14155551234`. Before it shows the preview, the connector checks that:
* Both numbers are valid and different, and the from number belongs to the workspace.
* The destination isn't a premium-rate number (the US and Canada 900 area code and 976 local exchanges, and the international +979 range), a shared-cost or satellite number (+808, +870, +881, +882, +883), or a +1 number outside the US and Canada, such as Jamaica (+1 876) or the Dominican Republic (+1 809). US territories such as Puerto Rico and Guam can be called.
Retell then refuses the call if the destination is on the workspace's do-not-call list, and runs its own checks, including [KYC](/accounts/kyc).
The connector allows 20 outbound calls per hour per Retell login (as of October 2026). To place more, or to call a number the connector refuses, use the [dashboard or the API](/deploy/outbound-call).
You're responsible for having the consent the law requires to call a number with an AI agent. See Retell's [Terms of Service](https://www.retellai.com/legal/terms-of-service).
### AI disclosure
Agents you build through the connector tell callers they're an AI in two ways:
* **At the start of every call.** The agent's opening message is "Hi, this is an AI assistant. How can I help you today?" You can ask Claude for a different opening when you build the agent, or change it in the dashboard later. Keep the disclosure in it, because some jurisdictions require it.
* **When asked.** The **AI Disclosure When Asked** preset in the [Agent Handbook](/build/agent-handbook) is on, the same default as agents built in the dashboard. The agent says it's a virtual assistant whenever a caller asks if they're talking to a person. To review it, open the agent in the dashboard and select **Agent Handbook** in the prompt section.
Agents built in the dashboard keep their own settings when you deploy or test them through the connector.
## Tools
The connector has 52 tools (as of October 2026). Tools marked *widget* are for the connector's own widgets. The connector marks them as widget-only, and Claude doesn't offer them to the model.
### Workspaces and session
| Tool | What it does |
| - | - |
| `get_workspaces` | Lists the Retell workspaces your login belongs to. |
| `save_selected_workspace` | Sets which workspace later tools act on. |
| `show_workspaces_select` | Opens the workspace picker. |
| `check_selected_workspace` *(widget)* | Reports the current selection to widgets. |
| `get_widget_ui_state`, `save_widget_ui_state` *(widget)* | Keep a widget's unsaved draft across a reload. |
| `update_phase_progress` *(widget)* | Tracks the build, deploy, test, and iterate steps for the progress bar. |
### Agents
| Tool | What it does |
| - | - |
| `list_agents` | Lists the agents in the workspace. |
| `show_list_agents` | Opens the agent list. |
| `show_agent_creation_widget` | Opens the build wizard with values filled in. |
| `generate_prompt` | Writes a prompt from the agent's description. Uses OpenAI. |
| `create_agent` | Creates the agent and its functions in Retell, with the AI disclosure opening. |
| `delete_agent` | Deletes an agent after you confirm. |
### Editing
| Tool | What it does |
| - | - |
| `edit_agent_basic_info` | Changes the agent's name or language. |
| `list_available_agent_voices`, `show_voice_browser` | List and preview voices. |
| `get_voice` *(widget)* | Looks up one voice. |
| `edit_agent_voice` | Changes the voice. |
| `preview_agent_prompt_edit`, `show_prompt_preview` | Show the current prompt next to a modified version before anything is applied. Use OpenAI. |
| `refine_prompt` *(widget)* | Rewrites a prompt inside the prompt editor. Uses OpenAI. |
| `update_agent_prompt` | Saves a new prompt. |
| `get_agent_dynamic_variables`, `update_agent_dynamic_variables`, `show_edit_agent_dynamic_variables` | Read, set, and edit default values for `{{variables}}` in the prompt. |
| `edit_agent_end_call_function`, `edit_agent_transfer_call_function`, `edit_agent_custom_function`, `edit_agent_extract_variable_function`, `edit_agent_agent_swap_function`, `edit_agent_send_sms_function`, `edit_agent_press_digit_function` | Add, change, or remove the agent's functions. |
| `show_edit_agent_voice`, `show_edit_agent_basic_info`, `show_edit_agent_end_call`, `show_edit_agent_transfer_call`, `show_edit_agent_custom_function`, `show_edit_agent_extract_variable`, `show_edit_agent_agent_swap`, `show_edit_agent_send_sms`, `show_edit_agent_press_digit_function` | Show a summary of a change after it's applied. |
### Deployment
| Tool | What it does |
| - | - |
| `get_phone_numbers` | Lists the workspace's phone numbers and the agents on them. |
| `check_agent_deployment_status` | Reports which numbers an agent is on. |
| `show_deploy_agent` | Opens the deploy screen. |
| `deploy_agent` *(widget)* | Assigns the agent to the chosen numbers, after you confirm if another agent would be replaced. |
| `send_dashboard_link` | Emails a link to the dashboard's phone numbers page to the address on your Retell login, so you can buy a number. |
### Testing and calls
| Tool | What it does |
| - | - |
| `show_test_agent` | Opens the test chat and the call form. |
| `get_chat_completion` | Sends a message to the agent in Retell's [text playground](/test/llm-playground). |
| `initiate_call` | Places a test call after you confirm. |
### Analytics
| Tool | What it does |
| - | - |
| `show_agent_analytics` | Opens the analytics dashboard for an agent. |
| `list_agent_calls` | Lists calls with filters and paging. |
| `get_call_details` | Returns one call's transcript, recording link, and analysis. |
## What data does the connector use?
The connector runs on Retell's infrastructure and calls the Retell API on your behalf. Retell's [privacy policy](https://www.retellai.com/legal/privacy-policy) applies.
* **Your Retell login.** Sign-in uses OAuth 2.0 through Retell's identity provider. The connector uses the access token to call the Retell API during the session and doesn't store it. It reads your login's name, email address, and whether the email is verified, to send you the dashboard link when you ask and to identify your account in Retell's product analytics (Mixpanel). It caches these for up to 24 hours.
* **Agent configuration.** Names, prompts, voices, phone numbers, and functions are read from and written to the Retell API.
* **OpenAI.** Four tools use OpenAI to write or rewrite prompt text: `generate_prompt`, `refine_prompt`, `preview_agent_prompt_edit`, and `show_prompt_preview`. When generating a prompt they send the agent's name, description, use cases, audience, tone, style, and language. When editing one they send the current prompt and your change request. Anything written in that text, including phone numbers, goes to OpenAI. Call transcripts and recordings aren't sent.
* **Email.** `send_dashboard_link` sends one email to the verified address on your Retell login, up to 3 times an hour. You can't give it another address.
* **Stored by the connector.** Your workspace selection and Claude's OAuth client registration are kept in a database for as long as your connection is active. Unsaved widget drafts and test chat transcripts are held in memory for up to 24 hours, and the counts behind the hourly limits for up to an hour. A used confirmation is remembered until it would have expired.
* **Logs and analytics.** For each tool call, the connector records the tool name, timing, whether it succeeded, the error message if it failed, your login and workspace IDs, and the shape of the input. The shape keeps field names, on and off settings, numbers, and the voice and language. Every other text value, such as prompts, phone numbers, and messages, is replaced by its length. These records go to Retell's logging service (Axiom) and to Mixpanel.
* **Deleting your data.** Remove the connector in Claude to end the connection. To have Retell delete data it holds about you, email [support@retellai.com](mailto:support@retellai.com). The [privacy policy](https://www.retellai.com/legal/privacy-policy) describes the process.
## Troubleshooting
| Issue | Solution |
| - | - |
| "Authorization with the MCP server failed" when connecting | Sign in with the email you use for the Retell dashboard. If it still fails, remove the connector in Claude and connect again. |
| A tool is missing, or the tools look out of date | Disconnect and reconnect the connector in Claude's settings to refresh the tool list. |
| A widget shows "Waiting for agent data" or stays blank | Ask Claude to open it again and name the agent. |
| "is not a phone number in this Retell workspace" | Calls can only come from numbers in the selected workspace. Ask Claude to list your phone numbers, or [buy a number](/deploy/purchase-number). |
| The call is refused with a verification message | Complete [KYC](/accounts/kyc) from the phone number's page in the dashboard. |
| "cannot be called from the connector" or "outside the US and Canada" | The destination is a premium-rate, satellite, or non-US/Canada +1 number. Place the call from the [dashboard or the API](/deploy/outbound-call). |
| "on the do-not-call list" | The contact is marked do-not-call in your workspace. Remove the flag in the dashboard if you have consent to call them. |
| "reached the connector's outbound call limit" | Wait for the hourly window to reset, or place the call from the dashboard. |
| A confirmation "expired" or "was already used" | Ask Claude to prepare the action again, then confirm the new preview. |
| The dashboard link email didn't arrive | Check your spam folder. If your login's email isn't verified, the connector says so instead of sending. |
| "The dashboard link was already emailed" | The link can be sent 3 times an hour. Use the earlier email, or open the dashboard directly. |
| Changing a custom function's URL is refused | The function has headers or query parameters saved in the dashboard, and the new URL is on a different host, so they would be sent there. Change the URL in the dashboard, where you can update the credentials at the same time. |
| A custom function URL is refused | Remove the key, token, or password from the URL, create the agent, then add it as a header or query parameter in the dashboard. For a webhook whose secret is the URL itself, such as Slack, Discord, Zapier, Make, Telegram, IFTTT or Microsoft Teams, add the whole function in the dashboard. If the message says the URL isn't valid, use the full address, such as `https://api.example.com/lookup`. |
| Claude can't edit an agent's prompt or functions | The agent is a conversation flow agent. Edit it in the dashboard. |
## FAQ
No. The connector signs in with your Retell login through OAuth and shows widgets in the chat. The [Retell MCP server](/get-started/mcp-server) uses a Retell API key and exposes the Retell API through three generic tools, for clients such as Cursor and Claude Code.
Your Retell login belongs to more than one workspace, and every tool acts on one of them. Tell Claude which one by name, or ask for the workspace picker. The choice is remembered.
Another agent is already on the number you picked. The panel shows which one. Confirm to move the number to your agent, or pick a different number.
No. Connect Cal.com or another calendar on the dashboard's **Integrations** page, where Retell stores the credentials. You can then add its booking functions to your agents in the dashboard. See [Cal.com](/integrations/cal-com). If an agent still has the older per-agent Cal.com functions, Claude can edit the rest of the agent but can't change or remove those functions. Manage them in the dashboard.
## Support
Email [support@retellai.com](mailto:support@retellai.com) or check [status.retellai.com](https://status.retellai.com).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.