# Ringover MCP API

**Canonical:** https://apis.io/apis/ringover/ringover-mcp-api/  
**Provider:** Ringover — https://apis.io/providers/ringover/  
**Base URL:** https://public-api.ringover.com/v2  
**Documentation:** https://developer.ringover.com/

Ringover MCP API is one of 28 APIs that [Ringover](https://apis.io/providers/ringover/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include mcp. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

## Model Context Protocol The MCP endpoint exposes a **curated** set of Ringover operations to AI assistants (Claude, ChatGPT, Cursor, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/). It is not a 1:1 copy of the REST API: tools that are hard for an agent to fill, rarely useful, or unsafe are omitted, and related mutations are grouped (for example `calls.archive`, `channels.control`, `users.update`). Source of truth for names, argument schemas and titles is `tools/list`. This page lists the frozen catalogue. ### Useful links - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest) - [Lifecycle & initialization](https://modelcontextprotocol.io/specification/latest/basic/lifecycle) - [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) - [Streamable HTTP transport](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) ### How it works MCP is JSON-RPC 2.0 over HTTP using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http). All interactions use `POST /mcp` with a JSON-RPC body. The server is **stateless** — every request is independent. There is no session (`Mcp-Session-Id` is not used) and no `notifications/tools/list_changed`. ### Request headers Every `POST` must send: - `Content-Type: application/json` - `Accept: application/json, text/event-stream` — **both** media types are required (comma-separated, as MCP clients do). A request that omits `text/event-stream` is rejected with HTTP `400`. ### Response format Successful MCP calls return HTTP `200` with `Content-Type: application/json` and a **single JSON-RPC object** in the body. There is no SSE stream: the endpoint is stateless (one request, one response, no shared connection across tool calls), so Server-Sent Events would not add multiplexing here. ### JSON-RPC errors vs HTTP errors - **Supported methods** (`initialize`, `tools/list`, `tools/call`): invalid tool arguments, tool rate limits, and application failures on `tools/call` are returned with HTTP `200` (JSON-RPC `error` or a tool result with `isError: true`). - **HTTP transport rejections** (before the message is handled as MCP): invalid `Accept`, malformed JSON-RPC, unsupported method **name** (anything other than the three methods above), etc. → HTTP **`400`** with a **plain-text** body, not a JSON-RPC envelope. Example: `JSON RPC not handled: "monitor/unknown_method" unsupported`. - Missing or invalid credential → **`401`**. HTTP rate limit → **`429`**. ### Available JSON-RPC methods | Method | Purpose | |--------|---------| | `initialize` | Capability negotiation. Returns server info (`name: "ringover-public-api"`, `version: "v1.0.0"`) and capabilities. Optional — you can call `tools/list` or `tools/call` directly. | | `tools/list` | Returns the tools **this credential can use**, with `name`, `title`, `description`, `inputSchema` and `annotations`. | | `tools/call` | Execute a tool by `name` with `arguments`. | `tools/list` never returns a tool the caller cannot invoke. A write tool is listed only when the credential has the matching **write** grant. Calling a hidden name is refused (`forbidden`). ### Authentication The MCP endpoint accepts the same credentials as the rest of public-api: - a **Public API key** (raw, no `Bearer` prefix) - an **OAuth 2.0 access token** (`Authorization: Bearer <token>`), when OAuth is enabled for the environment For API keys, three sources are tried in this **order** (first one set wins): | # | Source | Endpoint | Example | When to use | |---|--------|----------|---------|-------------| | 1 | URL path parameter | `POST /mcp/{token}` | `POST /mcp/abcd1234…` | Last resort for clients that cannot set headers or query strings. | | 2 | Query string `?token=` | `POST /mcp?token=…` | `POST /mcp?token=abcd1234…` | No-code / web tools that cannot set custom headers. | | 3 | `Authorization` header | `POST /mcp` | `Authorization: abcd1234…` | **Recommended** — same as REST. | The token is then normalized internally, so rate limiting, logging and permission checks behave the same regardless of source. > ⚠️ **Security note** — Tokens in the URL path or query string often appear in proxy logs, browser history and access logs. Prefer the `Authorization` header. If a token may have been exposed in a URL, **rotate it** from the Ringover Dashboard. ### Identifiers and JSON - MCP identifiers are **core IDs**. Do not apply the REST public offset (`+10000`). - Tool results use **snake_case** keys (`user_id`, `campaign_uuid`, `webhook_id`). - Write acknowledgements typically return `{"success": true}`. - `users.update`, `campaigns.update` and `conversations.update` may apply several upstream mutations in sequence. Validation runs first; an upstream error can still leave earlier fields updated. ### Cursor ```json { "mcpServers": { "ringover-public-api": { "url": "https://public-api.ringover.com/mcp", "headers": { "Authorization": "<your-public-token>" } } } } ``` Use the US host `https://public-api-us.ringover.com/mcp` for US workspaces. ### Quick start Using the standard `Authorization` header (recommended): ``` POST /mcp Authorization: your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Same call using the query string variant: ``` POST /mcp?token=your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Same call using the URL path variant: ``` POST /mcp/your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Example response: ```json {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}} ``` ### Rate limiting The MCP endpoint has its own rate limiting, separate from the REST API: - **HTTP rate limit** (per API key): 1 request/second with a burst of 10. Returns HTTP `429` when exceeded. - **Tool rate limit** (per team + tool name): ~1 call every 3 seconds with a burst of 5. Returns a JSON-RPC error in the response body (HTTP status remains `200`). ### Request timeout Each request has a **30-second timeout**. If a tool call exceeds this duration, the request is cancelled and an error is returned. ### Error handling Transport errors use HTTP status codes. Application errors on `tools/call` use a tool result with `isError: true` (HTTP still `200`): | Situation | Response | |-----------|----------| | Missing or invalid API key | HTTP `401` | | HTTP rate limit exceeded | HTTP `429` | | Tool rate limit exceeded | HTTP `200` + JSON-RPC error: `"rate limit exceeded for tool X"` | | Insufficient permission | HTTP `200` + tool result `isError`: `"forbidden"` | | Invalid arguments | HTTP `200` + tool result `isError` (validation message) | | Resource not found | HTTP `200` + tool result `isError` (for example `"user not found"`) | | Team feature not enabled (transcription) | HTTP `200` + JSON-RPC error: `"transcription feature not enabled for team"` | | Upstream / internal failure | HTTP `200` + tool result `isError` (generic message) | ### Permissions and Monitoring MCP tools follow the **same permission and Monitoring rules** as the matching REST operations. Read tools need the category **Read** grant; write tools need **Write**. `tools/list` already hides tools the token cannot use. The **Monitoring** flag still controls data **scope** (own data vs team), not which tools exist. `team.get` is visible to every authenticated caller. --- ## Available tools (111) Tool names follow `{resource}.{action}` (optional sub-resource: `campaigns.numbers.add`). `R` = read, `W` = write. ### Contacts **Permission:** Contacts. Monitoring does not widen the address book. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `contacts.search` | R | Search contacts by name, phone number, or company. | `query`, `limit` (0–500), `offset` | | `contacts.get` | R | Get a contact by core ID. | `contact_id` | | `contacts.create` | W | Create 1–50 contacts (numeric contract). | contacts payload | | `contacts.replace` | W | Replace a contact's full desired state. | `contact_id` + payload | | `contacts.delete` | W | Delete a contact. | `contact_id` | ### Calls and callbacks **Permission:** Calls. Call listing is team-wide regardless of Monitoring (same as REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `calls.search` | R | Search terminated calls. `summary`, `transcription` and `contact` are omitted unless `expand` asks for them. | `start_date`, `end_date`, `call_type`, `limit`, `offset`, `expand` | | `calls.get` | R | Get a terminated call. Unlike `GET /calls/{callId}`, summary, transcription and contact are omitted unless `expand` asks for them. | `call_id`, `expand` | | `calls.surveys.get` | R | Get post-call surveys. | `call_id` | | `calls.current.list` | R | List in-progress calls. | *(none / filters as advertised)* | | `calls.archive` | W | Archive a call, one channel, or logs. | `target` (`call` default, `channel`, `logs`), `call_id`, `channel_id`, `channel_ids`, `archive_cdr` | | `callbacks.create` | W | Create a callback. | user, destination number | | `callbacks.ivr.create` | W | Create a callback through an IVR. | IVR + destination | `expand` on `calls.search` and `calls.get` accepts `summary`, `transcription` and `contact`. Repeat values to combine them. The field states are the same as on REST (omitted, `null`, or object; a failed download stays a successful tool result and sets `error.code`). `contact` is included only when requested. Download URLs are not returned. ### Transcriptions **Permission:** Calls **and** the team transcription feature. Otherwise `"transcription feature not enabled for team"`. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `transcriptions.search` | R | List transcriptions, or semantic search when `query` is set. | `query`, `limit` (default 50), `offset`, `min_audio`, `max_audio` (`offset` / audio filters cannot be combined with `query`) | | `transcriptions.get` | R | Full transcript for a call. | `call_id` | ### Team **Permission:** none beyond a valid credential. Monitoring OFF returns a user-scoped view; ON returns the full team. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `team.get` | R | Team name, timezone, country, subscription. | *(none)* | ### Users, planning and snooze **Permission:** Users. Without Monitoring you only reach **your** user. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `users.list` | R | List team users. | *(none)* | | `users.get` | R | Get a user. | `user_id` | | `users.update` | W | Patch named identity fields. | `user_id` plus at least one of `email`, `first_name`, `last_name`, `job_title` | | `users.assign_profile` | W | Assign a permission profile. | `user_id`, `profile_id` | | `users.invite` | W | Invite users (per-item `created` / `failed`). | `users[]` (`email`, `number`, `plan_id`, names) | | `users.delete` | W | Delete or archive a user. | `user_id`, `type` (`DELETED` or `ARCHIVED`) | | `users.planning.get` | R | Weekly schedule. | `user_id` | | `users.planning.set` | W | Replace the weekly schedule. | `user_id`, slots | | `snoozes.list` | R | Available DND / snooze labels. | *(none)* | | `users.snooze.get_log` | R | Snooze history. | `user_id`, `limit`, `offset` | | `users.snooze.set` | W | Set or clear do-not-disturb. | `user_id`, label / duration | ### Groups **Permission:** Users. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `groups.list` | R | List ring groups. | *(none)* | | `groups.get` | R | Group with **all** members (not paginated). | `group_id` | | `groups.create` | W | Create a ring group. | name / members as advertised | | `groups.delete` | W | Delete a ring group. | `group_id` | | `groups.users.add` | W | Add members. | `group_id`, user IDs | | `groups.users.remove` | W | Remove members. | `group_id`, user IDs | ### Profiles **Permission:** Users. Profiles are team-wide. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `profiles.list` | R | List permission profiles. | *(none)* | | `profiles.get` | R | Get a profile. | `profile_id` | ### Numbers **Permission:** Numbers. Monitoring OFF returns numbers assigned to you. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `numbers.list` | R | List team numbers. | *(none)* | | `numbers.get` | R | Get a number. | `number` | | `numbers.reassign` | W | Reassign to a user, IVR or conference. | `number`, target | ### IVRs **Permission:** IVRs. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `ivrs.list` | R | List IVRs. | *(none)* | | `ivrs.get` | R | Get an IVR. | `ivr_id` | | `ivrs.scenarios.list` | R | Scenarios of one IVR. | `ivr_id` | | `ivrs.scenarios.get` | R | One scenario. | `ivr_id`, `scenario_id` | ### Conferences **Permission:** Calls (Monitoring typically required, same as REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `conferences.list` | R | List conference rooms. | *(none)* | | `conferences.get` | R | Get a conference. | `conf_id` | | `conferences.pincode.update` | W | Change the PIN. | conference id, pin | ### Tags **Permission:** Tags (API keys often include this with IVR-related grants). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `tags.list` | R | List tags. | *(none)* | | `tags.get` | R | Get a tag. | `tag_id` | | `tags.create` | W | Create a tag. | `name`, `color` | ### Presences **Mixed:** team presence typically requires Monitoring ON; user presence follows Users + Monitoring. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `presences.team.get` | R | Presence of all members. | *(none)* | | `presences.user.get` | R | Presence of one user. | `user_id` | ### Blacklist **Team list:** Numbers + Monitoring ON. **User list:** Users (own user without Monitoring). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `blacklist.team.list` | R | Team-blocked numbers. | `limit`, `offset` | | `blacklist.team.check` | R | Is this number blocked for the team? | `number` | | `blacklist.team.add` | W | Block for the team. | `number` | | `blacklist.team.delete` | W | Unblock for the team. | `number` | | `blacklist.user.list` | R | User blacklist. | `user_id`, `limit`, `offset` | | `blacklist.user.check` | R | Is this number blocked for a user? | `user_id`, `number` | | `blacklist.user.add` | W | Block for a user. | `user_id`, `number` | | `blacklist.user.delete` | W | Unblock for a user. | `user_id`, `number` | ### Channels (live call) **Permission:** Conversations write (same resource as live channel REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `channels.control` | W | Toggle mute, hold or recording, or hang up. | `channel_id`, `action` (`mute`, `hold`, `recording`, `hangup`) | | `channels.transfer` | W | Transfer to a number. | `channel_id`, `phone_number` | | `channels.dtmf.send` | W | Send one DTMF digit. | `channel_id`, `dtmf` (`0-9`, `#`, `*`) | ### Conversations and messages **Permission:** Conversations. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `conversations.list` | R | List SMS/chat conversations. | pagination / filters as advertised | | `conversations.get` | R | Get a conversation. | `conversation_id` | | `conversations.members.list` | R | List members. | `conversation_id` | | `conversations.messages.list` | R | List messages. | `conversation_id` | | `conversations.archive` | W | Archive (level 1). | `conversation_id` | | `conversations.unarchive` | W | Restore. | `conversation_id` | | `conversations.update` | W | Rename and/or set purpose. | `conversation_id`, `name` and/or `purpose` | | `conversations.messages.archive` | W | Archive a message. | conversation + message IDs | | `conversations.messages.unarchive` | W | Restore a message. | conversation + message IDs | ### SMS **Permission:** Conversations write. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `sms.send` | W | Send or schedule SMS. `mode=alphanumeric` uses the v1 sender contract. | `mode` (`standard` default, `alphanumeric`), `from_number` / `from_alphanum`, `to_number`, `content`, `user_id`, `user_id_forced`, `scheduled_at` | | `sms.opt_out.add` | W | Add a number to the team opt-out list. | `phone_number` | | `sms.opt_out.remove` | W | Remove a number from the opt-out list. | `phone_number` | ### WhatsApp **Permission:** Conversations. A valid key is enough on REST for some WhatsApp routes; MCP still lists only tools the credential can call. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `whatsapp.accounts.list` | R | List WhatsApp accounts. | *(none)* | | `whatsapp.templates.list` | R | List templates. | account as advertised | | `whatsapp.conversations.list` | R | List WhatsApp conversations. | filters as advertised | | `whatsapp.templates.send` | W | Send a template to a number. | template + destination | | `whatsapp.messages.send` | W | Send a message in a conversation. | conversation + body | ### Campaigns **Permission:** Campaigns (often granted on API keys by default). `campaigns.list` with `assigned_to_me=true` lists campaigns assigned to the caller; `ascending_order` and `is_running` cannot be combined with that flag. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `campaigns.list` | R | List calling campaigns. | `limit`, `offset`, `ascending_order`, `is_running`, `assigned_to_me` | | `campaigns.get` | R | Get a campaign. | `campaign_uuid` | | `campaigns.numbers.list` | R | Numbers in the campaign. | `campaign_uuid`, pagination | | `campaigns.groups.list` | R | Attached groups. | `campaign_uuid`, pagination | | `campaigns.users.list` | R | Attached users. | `campaign_uuid`, pagination | | `campaigns.logs.list` | R | Campaign logs. | `campaign_uuid` | | `campaigns.create` | W | Create a campaign. | `name`, `max_retry`, optional tags / IVR / dates | | `campaigns.start` | W | Start or schedule. | `campaign_uuid`, optional `start_date` | | `campaigns.stop` | W | Stop. | `campaign_uuid` | | `campaigns.reset` | W | Reset. | `campaign_uuid` | | `campaigns.update` | W | Patch name, retries, start date and/or script. Empty `script_uuid` unlinks the script. | `campaign_uuid` plus at least one of `name`, `max_retry`, `start_date`, `script_uuid` | | `campaigns.numbers.add` | W | Add numbers. | `campaign_uuid`, `to_numbers` | | `campaigns.numbers.delete` | W | Remove numbers. | `campaign_uuid`, `to_numbers` | | `campaigns.groups.add` | W | Attach groups. | `campaign_uuid`, `ids` | | `campaigns.groups.remove` | W | Detach groups. | `campaign_uuid`, `ids` | | `campaigns.users.add` | W | Attach users. | `campaign_uuid`, `ids` | | `campaigns.users.remove` | W | Detach users. | `campaign_uuid`, `ids` | | `campaigns.tags.add` | W | Add one tag without dropping existing tags. | `campaign_uuid`, `tag_id` | | `campaigns.tags.remove` | W | Remove one tag. | `campaign_uuid`, `tag_id` | CSV column editing is **not** exposed on MCP. ### Empower and tasks **Permission:** Empower. Visibility also follows Empower roles (admin / supervisor / user). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `empower.calls.list` | R | Search analysed calls. | filters as advertised | | `empower.calls.get` | R | Get an analysed call. | call UUID | | `empower.calls.get_moments` | R | Call moments. | call UUID | | `empower.calls.get_summary` | R | Call summary. | call UUID | | `empower.flags.list` | R | List flags. | *(none)* | | `empower.calls.delete` | W | Delete calls or only their media. | call UUIDs / media flag | | `empower.flags.associate` | W | Attach a flag. | call + flag | | `empower.flags.disassociate` | W | Detach a flag. | call + flag | | `tasks.list` | R | List team tasks. | filters as advertised | | `tasks.create` | W | Create a batch of tasks. | task payload | ### Webhooks **Permission:** webhooks / integrations (`webhooks:manage` on OAuth). There is no separate read-only webhook scope: list/get appear with the same grant as mutations. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `webhooks.list` | R | List subscriptions with stable `webhook_id`. | *(none)* | | `webhooks.get` | R | Get one subscription. | `webhook_id` | | `webhooks.create` | W | Create or merge by target URL. | `target_url`, `events` | | `webhooks.events.add` | W | Union extra events onto a subscription. | `webhook_id`, `events` | | `webhooks.delete` | W | Delete a subscription. | `webhook_id` | Event names: `call.started`, `call.answered`, `call.ended`, `call.missed`, `call.voicemail`, `call.aftercall`, `sms.sent`, `sms.received`, `sms.delivery_receipt`, `fax.received`, `contact.call`, `contact.search`. `contact.call` and `contact.search` accept a single target URL each: attaching one to a second URL fails and nothing is saved. Their keys are returned in `event_signing_keys`. Replacing the whole event set is REST-only (`PUT`).

## Operations (2)

| Method | Path | Summary |
|---|---|---|
| POST | `/mcp` | Model Context Protocol (MCP) endpoint |
| POST | `/mcp/{token}` | Model Context Protocol (MCP) endpoint — token in URL path |

## Machine-readable artifacts (7)

- **OpenAPI** — https://artifacts.apis.io/ringover/openapi/ringover-mcp-api-openapi.yml
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-calls-filter-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-response-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-call-empower-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-conversation-light-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-get-call-empower-res-body-schema.json

## Other Ringover APIs (12)

- [Ringover Blacklist API](https://apis.io/apis/ringover/ringover-blacklist-api/)
- [Ringover Callbacks API](https://apis.io/apis/ringover/ringover-callbacks-api/)
- [Ringover Calls API](https://apis.io/apis/ringover/ringover-calls-api/)
- [Ringover Campaigns API](https://apis.io/apis/ringover/ringover-campaigns-api/)
- [Ringover Cdn API](https://apis.io/apis/ringover/ringover-cdn-api/)
- [Ringover Channels API](https://apis.io/apis/ringover/ringover-channels-api/)
- [Ringover Conferences API](https://apis.io/apis/ringover/ringover-conferences-api/)
- [Ringover Contacts API](https://apis.io/apis/ringover/ringover-contacts-api/)
- [Ringover Conversations API](https://apis.io/apis/ringover/ringover-conversations-api/)
- [Ringover Empower API](https://apis.io/apis/ringover/ringover-empower-api/)
- [Ringover Groups API](https://apis.io/apis/ringover/ringover-groups-api/)
- [Ringover Ivrs API](https://apis.io/apis/ringover/ringover-ivrs-api/)

## Tags

mcp

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/ringover/ringover-mcp-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/ringover/.