MCP (Model Context Protocol)

Client Configuration

The MCP endpoint requires authentication via OAuth 2.0.

MCP clients that support OAuth Client ID Metadata Documents (CIMD) can connect without any manual configuration: Telerivet registers it automatically the first time a user authorizes it. Telerivet does not support Dynamic Client Registration.

Setup instructions are available for the following MCP clients:

• Claude (claude.ai and Claude Desktop)
• Claude Code
• ChatGPT
• Codex
• Antigravity CLI
• Hermes Agent

For MCP clients that do not support Client ID Metadata Documents, an OAuth Client must be configured manually. To allow using another MCP client that does not support CIMD, you can add a new OAuth Client in your Telerivet organization and configure the OAuth callback URLs required by the MCP client. (The service providing the MCP client may specify their OAuth callback URLs in their documentation.) When an OAuth Client is manually configured in this way, it will only be accessible by users within your own Telerivet organization.

Authorizing an MCP Client

When you connect an MCP client, it redirects you to Telerivet to authorize access. On this page, you choose:

• Permissions – which types of data and actions the application may access (for example, View messages, Send messages, or Edit automated services). Uncheck any permission you don't want the application to have. The application can never do more than your own user account is allowed to do, and API methods requiring a permission you didn't grant are hidden from the MCP client.
• Organization – which of your organizations the application may access. Each authorization covers a single organization; to use the application with another organization, connect it again.

Approving applications for your organization. Each MCP client (such as Claude or ChatGPT) must be approved by an organization administrator before it can be used in an organization. If you are an organization administrator, the authorization page lets you approve the application for your organization, and choose Who can use this application?: all users in the organization, organization administrators only, or organization and project administrators only. Other users will see a message asking them to contact an organization administrator to approve the application.

Revoking access. You can revoke an application's access to your own account at any time from the Authorized Applications section of your Account Security settings. Organization administrators can review and revoke every user's access tokens from the OAuth Access Tokens page, or revoke an application entirely from the Connected Applications page.

Organization Controls

Organization administrators can control what each approved MCP client is allowed to do within their organization on the Connected Applications page (also linked from your organization's Developer API page). Click an application to view or change its settings. These settings apply to every user's access to that application within the organization, regardless of the permissions users granted when connecting it.

Required permission – which users in the organization can authorize the application (all users, organization administrators only, or organization and project administrators only).

Allowed actions – for each category of action, whether the application may perform it on its own, whether a user must approve each action, or whether it is not allowed at all:

Action	Description	Options	Default
Reading data	Looking up contacts, messages, statistics, and other project data.	Allowed, Not allowed	Allowed
Creating and updating data	Creating and editing contacts, groups, services, draft campaigns, routes, and other project data.	Allowed, Require approval, Not allowed	Allowed
Sending messages and triggering services	Sending or scheduling messages and calls to contacts, triggering automated services, and running scripts.	Allowed, Require approval, Not allowed	Require approval
Deleting data	Deleting contacts, messages, services, and other project data.	Allowed, Require approval, Not allowed	Require approval
Making external web requests	Making requests to external websites and third-party APIs from scripts this application runs.	Allowed, Not allowed	Allowed

When a category is Not allowed, the corresponding MCP tool (such as send_api or delete_api) is hidden from the MCP client, and any API request in that category is refused. The run_script tool follows the strictest setting among sending, creating/updating, and deleting data.

Some applications specify their own defaults – for example, an autonomous agent that needs to send messages without a user present. When an application's default differs from the standard default, the Connected Applications page notes the application's default next to the setting. Your organization's setting always takes precedence.

Allowed permissions – the types of data and actions the application can access in this organization. Unchecking a permission blocks the corresponding API actions for all users of the application in the organization, even if a user granted that permission when connecting it.

Revoke access – removes the application from your organization's approved applications and revokes all existing access tokens for it in your organization.

Applications owned by your own organization (added via Add OAuth Client) don't need approval, and their allowed actions are configured on the application's own settings page instead.

Human-in-the-Loop Confirmation

When a category of action is set to Require approval on the Connected Applications page, the MCP client can't perform those actions until a user explicitly approves each one. By default, this applies to sending messages and triggering services, and to deleting data.

Actions in the sending category include sending or scheduling messages and calls, resending messages, triggering automated services, creating batch tasks, simulating incoming messages, editing scheduled messages or campaigns, activating an automated service or changing an active service's configuration, creating webhooks or changing webhook URLs, changing a route's phone number or provider settings, changing the project's default route, and running scripts with the run_script tool. The deleting category includes all delete methods, as well as reducing a project's message retention.

Depending on the MCP client, you can approve an action in one of the following ways:

Approval prompt in the MCP client

If the MCP client supports MCP elicitation (using MCP protocol version 2026-07-28 or later), the MCP client prompts you to approve the action directly, with a plain-language description of what the action will do and which project it affects. If you approve, the action is performed immediately. If you decline, the action is not performed and the AI model is told not to retry it.

Message drafts

If the MCP client supports the MCP Apps extension, the AI model can use the draft_message tool to show you an editable draft of a text message, including the recipients. Clicking Send approves sending that exact message to those recipients.

Approval link

If the MCP client doesn't support either of the above, or the action can't be approved that way, the AI model receives a link to an Approve Action page in the Telerivet web app, and should ask you to open it. This page shows the application, project, a description of the action, and the full request details. After clicking Approve, return to the MCP client and ask it to try again.

To approve an action, you must have the permission that the action itself requires (for example, permission to send messages in the project). Approving an action doesn't grant the application any additional permissions.

How approvals work

• Each approval applies to one exact request – the same API method with the same parameters – and can be used only once. If the AI model changes anything about the request, it needs to be approved again.
• Approvals expire after 1 hour.
• API requests made by a script that you approved via run_script don't require separate approval.
• If the application calls the REST API directly with its access token (rather than via MCP), requests requiring approval fail with the error code confirmation_required, and the error message includes an approval link. Applications that need to perform these actions without a user present (such as server-side integrations or autonomous agents) require an organization administrator to set the category to Allowed.

Message Review. Independently of the above, if a project has Message Review enabled in its Messaging Settings, messages sent via the API (including via MCP) that exceed the configured limits are held as pending messages until a reviewer approves them, the same as messages sent from the web app.

Tools

The MCP server currently exposes the following tools:

• list_api_methods – Lists available API methods with name, description, and parameter summary. Supports filtering by category.
• get_method_schema – Returns the full parameter schema and response field descriptions for a specific API method.
• read_api – Executes a read-only API method to retrieve data.
• modify_api – Executes an API method that creates or updates data.
• delete_api – Executes an API method that deletes data.
• send_api – Executes an API method that sends, schedules, or receives messages, invokes automated services, or performs batch tasks.
• run_analysis_script – Runs read-only JavaScript in Telerivet's Cloud Script API sandbox to analyze project data – useful for aggregations, joins across entity types, or scanning many records without paging them all through the model. API access is read-only and outbound HTTP is disabled.
• run_script – Runs JavaScript with Cloud Script API access (reads, writes, sending, HTTP requests), for bulk operations that would otherwise take many individual API calls. API requests made by scripts are checked against the OAuth token's scopes, so scripts can never do more than the token that ran them.
• get_web_app_urls – Returns information about web app functionality and URL patterns. Allows AI agents to generate links to functionality that isn't directly available via the API. Without a query, returns a compact index of all pages; searching by keywords or URL path returns full details for matching pages.
• draft_message – Drafts a simple text message to one or more phone numbers (or a group of contacts), and prompts for user approval before sending (see Message drafts). Only available if the MCP client supports the MCP Apps extension.
• get_route_options – Returns information about available messaging route/channel options. Filtering by country, channel type, or use case (or looking up a specific route type) returns full details including geographic availability, compliance requirements, registration process, billing modes (internal/Telerivet-managed vs external/BYOC), setup timelines, and pricing.
• skillbook_search / skillbook_get – Returns information about common solution patterns, services, campaign types, platform features, and message templates matching an intent or use case.
• search_documentation / get_documentation – Searches and retrieves entries from Telerivet's documentation corpus, including User Guide help articles, legal/policy pages, developer API documentation, and marketing/company content on www.telerivet.com.

The tools and API methods exposed by the MCP server may change over time.

The links below show the JSON returned by the MCP server, which may help to get an understanding of the available tools and API methods:

• Tool definitions
• Output of list_api_methods tool
• Output of get_method_schema tool for Project_queryContacts method (replace the last component of the URL to view the schema for other API methods)
• Output of get_documentation tool for the Cloud Script API reference (replace the last component of the URL to view other documentation entries)

The scopes granted to your OAuth token, along with your organization's controls for the application, determine which tools and API methods are available. Methods requiring a scope that your token does not have, or that your organization does not allow for the application, will be excluded from the list.