> For the complete documentation index, see [llms.txt](https://help.ringtonic.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.ringtonic.app/guides/mcp.md). # MCP for AI Agents MCP (the Model Context Protocol) lets an AI assistant — such as Claude — operate your Ring Tonic account for you. Once you connect one, you can ask it in plain language to look things up and act on your account, and it uses Ring Tonic on your behalf through the same rules and permissions you'd have yourself. {% hint style="info" %} MCP keys are available on the **Agency plan** only. {% endhint %} {% hint style="success" %} **The full toolset is live.** A connected assistant can now work across your campaigns, calls, contacts, conversions, tracking numbers, call flows, appointments, form submissions, and analytics — reading, reporting, and making changes on your behalf. See [What You Can Ask For](#what-you-can-ask-for) below, or the complete tool reference at [ringtonic.app/docs/mcp](https://ringtonic.app/docs/mcp). {% endhint %} *** ### What you need before you start * A Ring Tonic account on the **Agency plan** with active billing * Owner or admin access to at least one workspace * An AI client that supports MCP — for example **claude.ai** or **Claude Desktop**, the **ChatGPT desktop app**, **Claude Code**, **Cursor**, or **Windsurf** *** ### Creating an MCP Key An MCP key is what your AI client uses to sign in to Ring Tonic. You create it once and paste it into the client. {% stepper %} {% step %} #### Open the MCP settings Go to **Settings** → **MCP**. {% endstep %} {% step %} #### Start a new key Click **New MCP key** and give it a name you'll recognise later, such as "Claude assistant". {% endstep %} {% step %} #### Choose what it can do Pick the **scopes** — the areas of your account the assistant may use. Use the **Read-only** or **Full access** presets, or turn individual areas on yourself. Read and write are separate, so you can allow an assistant to look without letting it change anything. {% endstep %} {% step %} #### Set an expiry (optional) Leave it as **Never expires**, or have the key stop working automatically after 30, 90, or 365 days. {% endstep %} {% step %} #### Create and copy Click **Create key**. Your key and the connection details appear **once** — copy them now. For your security they are never shown again.

The one-time connection panel, showing the new key and the setup snippet for each supported client

{% endstep %} {% endstepper %} {% hint style="warning" %} **Store your key securely.** Treat it like a password — anyone who has it can use your account as you. If you lose it, revoke the key and create a new one. {% endhint %} {% hint style="info" %} **An MCP key belongs to you, not to one workspace.** It can reach every workspace you own or administer, and it acts with your permissions in each. This is different from an [API key](/guides/api.md), which is tied to a single workspace. {% endhint %} *** ### Connecting Your AI Client When you create the key, Ring Tonic shows a ready-made setup for each kind of client. Copy the one that matches yours. {% tabs %} {% tab title="claude.ai / Claude Desktop" %} 1. In **claude.ai** or the **Claude Desktop** app, go to **Settings** → **Connectors** → **Add custom connector** 2. Paste the Ring Tonic connection URL 3. Leave **Authentication** as **None**, then add a request header named `Authorization` with the value `Bearer YOUR_MCP_KEY` 4. Save, then enable Ring Tonic in the message composer {% endtab %} {% tab title="Claude Code" %} Run the one-line command from the connection panel in your terminal: ```bash claude mcp add --transport http ringtonic https://ringtonic.app/mcp \ --header "Authorization: Bearer YOUR_MCP_KEY" ``` {% endtab %} {% tab title="ChatGPT Desktop" %} Codex is now part of the **ChatGPT desktop app** (macOS and Windows). Add Ring Tonic as a custom MCP server: 1. In ChatGPT, open **Settings** → **MCP servers** → **Add server** (shown as **Plugins** → **MCPs** → **Connect to a custom MCP**) 2. Choose **Streamable HTTP**, then enter a name and the Ring Tonic connection URL 3. The form takes no header, so add the key to the shared config file `~/.codex/config.toml`: ```toml [mcp_servers.ringtonic] url = "https://ringtonic.app/mcp" http_headers = { Authorization = "Bearer YOUR_MCP_KEY" } ``` 4. Restart ChatGPT — Ring Tonic appears under **MCP servers** The ChatGPT desktop app, the Codex CLI, and the IDE extension all share this config. {% endtab %} {% tab title="Codex CLI" %} The Codex terminal agent shares the same config. Add Ring Tonic with one command: ```bash export RINGTONIC_MCP_TOKEN=YOUR_MCP_KEY codex mcp add ringtonic --url https://ringtonic.app/mcp \ --bearer-token-env-var RINGTONIC_MCP_TOKEN ``` {% endtab %} {% tab title="Grok / Grok Bot" %} 1. In Grok, go to **grok.com/connectors** → **New Connector** → **Custom** 2. Set the URL to `https://ringtonic.app/mcp` 3. In the connector's authentication field, enter `Authorization: Bearer YOUR_MCP_KEY` Grok Bot uses the same connector once it is added. {% endtab %} {% tab title="Grok Build" %} xAI's Grok Build coding agent connects to remote MCP servers through `grok mcp add` and `~/.grok/config.toml`. Add `https://ringtonic.app/mcp` with an `Authorization: Bearer YOUR_MCP_KEY` header — see xAI's Grok Build MCP docs for the exact config syntax. {% endtab %} {% tab title="Cursor / Windsurf" %} Add the block from the connection panel to your client's MCP configuration: ```json { "mcpServers": { "ringtonic": { "url": "https://ringtonic.app/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_KEY" } } } } ``` {% endtab %} {% endtabs %} {% hint style="success" %} **Any client that can send a bearer key can connect.** The panel covers the most common ones, but the connection is a standard MCP endpoint over the web — a client is compatible as long as it can send an authorisation header. {% endhint %} {% hint style="info" %} **ChatGPT: use the desktop app, not the web.** Connect through the **ChatGPT desktop app** (the tab above). ChatGPT on the web (chatgpt.com connectors) still requires OAuth rather than a bearer key, which Ring Tonic does not offer yet, so it cannot connect there for now. {% endhint %} *** ### What You Can Ask For Once connected, ask the assistant in plain language. It sees a set of **tools** — the actions it's allowed to take, filtered to the scopes on your key — and picks the right one for what you ask. Here is what each area covers, with a prompt you can try. | Area | The assistant can… | Try asking | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **Workspaces** | List the accounts your key reaches; read a workspace's timezone, currency, and custom fields | *"Which client accounts can I manage with this connection?"* | | [**Campaigns**](/guides/campaigns.md) | List, read, create, update, and delete campaigns; attach a call flow | *"Set up a new static campaign called 'Radio Spot' that forwards to +1 512 555 0180."* | | **Calls** | Search calls, read a call with its recording and transcript, set lead status / deal value / tags, delete | *"List every missed call on the Downtown Dental campaign in the last 7 days."* | | [**Contacts**](/guides/contacts.md) | Search and match contacts, read a contact's history, add or update, remove | *"Add a new contact named Maria Gomez, phone +1 305 555 0190."* | | **Conversions** | List conversions; record a conversion that moves a contact along your pipeline | *"Log a won deal worth $4,000 for the contact at +1 305 555 0190."* | | [**Tracking numbers**](/guides/phone-numbers.md) | List and update your numbers; search, buy, and release numbers | *"Buy me a new local tracking number in area code 415 and label it 'Downtown billboard'."* | | [**Call flows**](/guides/call-flow-builder.md) | List and read flows and their graphs; create, edit the draft, publish, roll back, clone, delete | *"Publish the After-Hours Routing flow so it goes live."* | | [**Appointments**](/guides/appointments.md) | Search and read appointments; book, reschedule, and set status | *"Book a 30-minute follow-up with the contact at +1 305 555 0190 for Thursday at 2pm."* | | [**Form submissions**](/guides/form-submissions.md) | List captured web-form submissions and read one in full | *"Show me the form submissions we captured on Spring Promo this week."* | | Tags, products, [blocked numbers](/guides/blocked-numbers.md), [webhooks](/guides/webhooks.md) | List and manage each of these | *"Block the spam caller at +1 800 555 0111 as harassment."* | | [**Analytics**](/guides/analytics.md) | Read call metrics, attribution, the lead funnel, and per-number performance | *"Which marketing sources drove the most qualified calls and best ROI last month?"* | {% hint style="info" %} **The full list is on the docs page.** Every tool, its parameters, and a prompt to try are listed at [ringtonic.app/docs/mcp](https://ringtonic.app/docs/mcp) — handy when you want to see exactly what the assistant can reach. {% endhint %} {% hint style="info" %} **Tell the assistant which workspace you mean.** Because your key can reach several workspaces, ask it to list them first if you're unsure, then refer to the one you want by name. When your key reaches only one workspace, it uses that one automatically. {% endhint %} *** ### Report Recipes for Agencies The assistant is at its best when it chains several steps into one answer — exactly the recurring numbers you send clients. Paste one of these as a single instruction: * 📞 *"Show me last week's top campaigns by calls for Downtown Dental."* * 🎯 *"Which tracking numbers are converting best for Acme this month? Rank them by booked appointments."* * 💰 *"Build a Q3 report for Downtown Dental: total calls, qualified-lead rate, closed revenue, and top 3 sources."* * 🗓️ *"For the lead who called from (415) 555-0133 yesterday, book a follow-up Thursday 2pm and tag them 'hot-lead'."* * 🚦 *"Audit the Acme account: which campaigns have no call flow attached and which numbers are unassigned?"* * 📈 *"Across all my client workspaces, tell me which one had the biggest week-over-week jump in qualified calls."* {% hint style="success" %} **Pair MCP with** [**Scheduled Reports**](/guides/scheduled-reports.md)**.** Use the assistant for the ad-hoc "what happened this week" questions, and scheduled reports for the fixed ones that go out on a timetable. {% endhint %} *** ### Scopes: What the Assistant Is Allowed to Do The assistant can only ever see and use the areas you granted when you made the key. A key with read-only scopes produces a read-only assistant — it never even sees an action it isn't allowed to take, so it can't be talked into one. | Scope area | What it covers | | ------------------------- | ----------------------------------------------------------------------------- | | **Read** areas | Look at campaigns, calls, contacts, and the other parts of your account | | **Write** areas | Create, change, or remove records in those areas | | **Buy & release numbers** | Purchase and give back phone numbers | | **Analytics** | Read call, conversion, funnel, and attribution analytics | | **Force stage moves** | Override the guard on moving a contact's pipeline stage (owner or admin only) | {% hint style="info" %} **Grant only what an assistant needs.** If you want help reading and summarising your data, a read-only key is enough. Add write scopes only when you want the assistant to make changes for you. {% endhint %} {% hint style="warning" %} **A missing tool means a missing scope.** If the assistant says it can't find a tool you expected, the key doesn't include that scope. Create a new key with the scope added, or ask the key's owner to. Some clients keep an old list of tools until you reconnect them. {% endhint %} *** ### Seeing Your Keys in Action The **MCP** settings page shows what each key is doing. | Column | What it tells you | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | **Connection** | Whether a client has used the key recently — "Active" with a time, or that it hasn't been seen in the last 30 days | | **Last used** | When the key last signed in | | **Expires** | The expiry you set, or "Never" | Below the keys, the **Recent activity** feed lists the assistant's recent actions — which tool it used, in which workspace, and whether it succeeded. It's your record of what has been done on your account through MCP. *** ### Keys Reaching Your Workspaces If you own a workspace and a team member there has their own MCP key, that key can reach your workspace too. The **Keys reaching your workspaces** panel shows you every such key — who created it, and when it was last active — so there are no hidden connections into a workspace you own. {% hint style="info" %} **To cut off a team member's key, change their access.** Remove them from the workspace, or lower their role below admin, and their key can no longer reach it. You revoke your own keys directly; a team member's key is theirs to delete, but their access to your workspace is yours to control. {% endhint %} A workspace shown with a **Suspended** label means its owner's plan no longer includes MCP access — see [When access pauses](#when-access-pauses) below. *** ### Managing Keys | Action | How | | ---------------------- | -------------------------------------------------- | | View your keys | **Settings** → **MCP** | | See if a key is in use | Check the **Connection** and **Last used** columns | | Revoke a key | Click the trash icon next to it → Confirm | {% hint style="danger" %} **Revoking is permanent.** Any assistant using that key stops working immediately. Create a new key and reconnect the client to restore access. {% endhint %} MCP keys and [API keys](/guides/api.md) are kept separate: an MCP key never appears on the **API Keys** page, and an API key never appears here. Each is created, listed, and revoked on its own page. *** ### When Access Pauses MCP access follows your plan. If a workspace's owner moves off the Agency plan, or their billing lapses, keys reaching that workspace stop working and the workspace shows as **Suspended** on the MCP page. The keys are not deleted — they go dormant. Return to the Agency plan and they start working again, with no need to create them anew. *** ### Security & Privacy {% hint style="info" %} A few things worth knowing about how MCP keeps your account safe. {% endhint %} * **Your key acts as you.** It has exactly the access you have — no more — and every action it takes is checked against your role in that workspace, just as if you'd done it in the dashboard. * **Ring Tonic-branded connection only.** MCP is not available on white-label domains. On a white-label host the MCP page and the connection endpoint aren't there, and the menu entry is hidden. * **Your data is treated as data, not instructions.** Call transcripts, contact details and form submissions that an assistant reads are third-party information — the assistant is guided not to follow any instructions hidden inside them.
Technical details for developers The endpoint speaks MCP over Streamable HTTP at `https://ringtonic.app/mcp`. A few points if you're building against it directly: 1. **Authentication** is a bearer key in the `Authorization` header — the same `rt_` key shown once at creation. 2. **Discovery first.** Call the `list_workspaces` tool to see which workspaces the key reaches and their access status; most other tools take a `workspace` parameter (a workspace's public id or exact name) to say which one you mean. 3. **Timestamps** in results are UTC. Date-only filters are read in the target workspace's timezone. 4. **Rate limits** apply per key and per workspace, shared with the REST API, so combining the two can't exceed your quota. 5. **Actions that create or change data** accept an idempotency key so a retry after a timeout doesn't act twice — reuse the same key on the retry. It matters most for buying a number, booking an appointment, and regenerating a webhook secret. 6. **The complete tool reference** — every tool, its scope, its parameters, and an example prompt — is published at [ringtonic.app/docs/mcp](https://ringtonic.app/docs/mcp).
*** ### Common Questions
How is an MCP key different from an API key? Both let software use your account, but they're built for different things. * An **API key** is tied to **one workspace** and is meant for your own scripts and integrations calling the REST API. * An **MCP key** belongs to **you**, reaches **every workspace you own or administer**, and is meant for an AI assistant to use on your behalf. They're managed on separate pages and never appear in each other's list.
Which AI clients can connect? Any client that supports MCP over the web and can send an authorisation header — for example claude.ai / Claude Desktop, the ChatGPT desktop app, Claude Code, the Codex CLI, Cursor, and Windsurf. The connection panel gives you the key and URL plus a link to the setup for each; other MCP-capable clients can use the same URL and key.
Can I limit an assistant to reading only? Yes. When you create the key, choose the **Read-only** preset or select only read scopes. The assistant then sees only reading tools and cannot change anything in your account.
A team member has an MCP key — can they reach a workspace I own? Only if they're an owner or admin of it. You can see every such key in the **Keys reaching your workspaces** panel. To remove that access, lower their role below admin or remove them from the workspace.
My assistant says it can't find a tool. Why? The key most likely doesn't include the scope that tool needs. 1. Check the key's scopes on the **MCP** settings page. 2. If the scope is missing, create a new key that includes it. 3. Reconnect the client — some keep a cached list of tools until they reconnect. If the tool simply doesn't exist yet, it's a capability still on the way — this guide lists what's available today.
What happens to my keys if I change plans? Leaving the Agency plan pauses MCP access — keys stop working and affected workspaces show as **Suspended** — but the keys are kept, not deleted. Returning to the Agency plan reactivates them automatically.
How many MCP keys can I create? As many as you like. A separate key per assistant or device is a good idea, so you can revoke one without affecting the others.