🔌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.

MCP keys are available on the Agency plan only.

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 below, or the complete tool reference at ringtonic.app/docs/mcp.

---

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.

1

Open the MCP settings

Go to Settings → MCP.

2

Start a new key

Click New MCP key and give it a name you'll recognise later, such as "Claude assistant".

3

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.

4

Set an expiry (optional)

Leave it as Never expires, or have the key stop working automatically after 30, 90, or 365 days.

5

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

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.

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, which is tied to a single workspace.

---

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.

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

Claude Code

Run the one-line command from the connection panel in your terminal:

claude mcp add --transport http ringtonic https://ringtonic.app/mcp \
  --header "Authorization: Bearer YOUR_MCP_KEY"

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:

[mcp_servers.ringtonic]
url = "https://ringtonic.app/mcp"
http_headers = { Authorization = "Bearer YOUR_MCP_KEY" }

1. Restart ChatGPT — Ring Tonic appears under MCP servers

The ChatGPT desktop app, the Codex CLI, and the IDE extension all share this config.

Codex CLI

The Codex terminal agent shares the same config. Add Ring Tonic with one command:

export RINGTONIC_MCP_TOKEN=YOUR_MCP_KEY
codex mcp add ringtonic --url https://ringtonic.app/mcp \
  --bearer-token-env-var RINGTONIC_MCP_TOKEN

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.

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.

Cursor / Windsurf

Add the block from the connection panel to your client's MCP configuration:

{
  "mcpServers": {
    "ringtonic": {
      "url": "https://ringtonic.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_KEY"
      }
    }
  }
}

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.

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.

---

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	List, read, create, update, and delete campaigns; attach a call flow	"Set up a new static campaign called 'Radio Spot' that forwards to [phone]."
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	Search and match contacts, read a contact's history, add or update, remove	"Add a new contact named Maria Gomez, phone [phone]."
Conversions	List conversions; record a conversion that moves a contact along your pipeline	"Log a won deal worth $4,000 for the contact at [phone]."
Tracking numbers	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	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	Search and read appointments; book, reschedule, and set status	"Book a 30-minute follow-up with the contact at [phone] for Thursday at 2pm."
Form submissions	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, webhooks	List and manage each of these	"Block the spam caller at [phone] as harassment."
Analytics	Read call metrics, attribution, the lead funnel, and per-number performance	"Which marketing sources drove the most qualified calls and best ROI last month?"

The full list is on the docs page. Every tool, its parameters, and a prompt to try are listed at ringtonic.app/docs/mcp — handy when you want to see exactly what the assistant can reach.

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.

---

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 [phone] 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."

Pair MCP with Scheduled Reports. 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.

---

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)

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.

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.

---

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.

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.

A workspace shown with a Suspended label means its owner's plan no longer includes MCP access — see 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

Revoking is permanent. Any assistant using that key stops working immediately. Create a new key and reconnect the client to restore access.

MCP keys and API keys 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

A few things worth knowing about how MCP keeps your account safe.

• 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.

---

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.