MCP Tools Reference
You don’t need to memorize any of this. Your assistant reads the catalog itself and picks the right tool from what you asked for in plain language. This page is here for when you want to know exactly what’s reachable, what isn’t, and why a request was refused.
New to the MCP server? Start with Installing MCP Server.
How the tools work
Names describe the resource and the job. campaigns.read inspects campaigns,
campaigns.manage changes them, campaigns.routing_settings.read inspects one
campaign’s routing.
Read tools list or show. Omit the id to list a page of records; pass the id to get one record in full. Lists are paginated, and the response says how many pages there are.
Manage tools create, update, or delete. They take an action — create,
update, or delete — plus the fields to write. A few narrower ones only
create (duplicating a buyer, resetting a cap, test-firing a webhook).
Most write tools support a dry run. Ask your assistant to preview a change
and it passes dry_run: true: Retreaver returns the exact diff it would apply
and changes nothing. Worth doing on anything that touches live routing. A few
actions apply immediately and have no preview: duplicating a buyer or handler
group, resetting a hard cap, creating or test-firing a webhook.
Writes come back as a status. ok means it applied, dry_run means nothing
changed. If a field is one your role can’t write, it’s ignored rather than
silently applied.
catalog.search finds tools by keyword. Every tool is available up front
today; catalog.search is there so the assistant can look one up by name or
description when it isn’t sure which to call.
Access levels
Each tool needs one of three access levels, chosen when you approve the connection. See MCP Authentication for how to grant them.
| In this page | Scope | Granted as |
|---|---|---|
| Identify | mcp:basic |
Always included |
| Read | mcp:operations:read |
“Operations Read” |
| Manage | mcp:operations:manage |
“Operations Manage” — includes Read |
A note on names
Some tools use Retreaver’s internal names rather than the ones on screen:
| Tool name | What you call it in the Browser Platform |
|---|---|
targets |
Buyers (call endpoints) |
target_groups |
Handler groups (buyer groups) |
affiliates |
Sources (publishers) |
webhooks |
Webhooks (timers) |
Connection
Available on every connection, including read-only ones. Neither tool reads or changes any account data.
| Tool | Access | What it does |
|---|---|---|
account.whoami |
Identify | Reports the company this connection is bound to, who you’re acting as, your role, and the access levels granted. |
catalog.search |
Identify | Searches the catalog of tools this connection may call, by name or description. |
Campaigns
| Tool | Access | What it does |
|---|---|---|
campaigns.read |
Read | List campaigns, or show one in full. |
campaigns.manage |
Manage | Create, update, or delete a campaign — including pausing and resuming it. |
campaigns.routing_settings.read |
Read | Inspect a campaign’s routing: its menu options and the ordered rows beneath them, with each row’s priority, weight, locked, disabled, and route-by-bid / route-by-performance settings. |
campaigns.routing_settings.manage |
Manage | Edit that routing — reorder buyers, disable a row without deleting it, add or remove menu options, turn on bid or performance routing. |
Routing is the highest-stakes thing the MCP can change. Ask for a dry run first.
Buyers
| Tool | Access | What it does |
|---|---|---|
targets.read |
Read | List buyers, search them by name, number, or client id, or show one in full. |
targets.manage |
Manage | Create, update, or delete a buyer — including pausing, resuming, and setting weekly business hours. |
targets.caps.manage |
Manage | Set a buyer’s hard, hourly, daily, monthly, and concurrency caps. Passing null removes a limit. |
targets.cap_resets.manage |
Manage | Reset a buyer’s hard cap — zeroes the calls counted against it and clears the cap alert. Doesn’t change the limit itself. No dry run. |
targets.duplicates.manage |
Manage | Duplicate a buyer, deep-copying its settings, conversions, business hours, tags, forward tags, and SIP headers. No dry run. |
See How to configure Retreaver number caps for what the cap types mean.
Handler groups
| Tool | Access | What it does |
|---|---|---|
target_groups.read |
Read | List handler groups, or show one in full including its members. |
target_groups.manage |
Manage | Create, update, or delete a group, set its membership, pause or resume it. |
target_groups.duplicates.manage |
Manage | Duplicate a group. Its settings are copied; the same member buyers are re-linked, not cloned. No dry run. |
Sources
| Tool | Access | What it does |
|---|---|---|
affiliates.read |
Read | List sources (publishers), or show one in full. |
affiliates.manage |
Manage | Create, update, or delete a source, including pausing and resuming it. |
Numbers and number pools
| Tool | Access | What it does |
|---|---|---|
numbers.read |
Read | List tracking numbers, or show one in full. |
numbers.manage |
Manage | Create, update, or delete a tracking number. On create, omit the number itself to have one provisioned. |
number_pools.read |
Read | List number pools, or show one in full. |
number_pools.manage |
Manage | Create or update a pool. Pools can’t be deleted over MCP. |
Background: What are number pools and how do they work.
Caller lists
| Tool | Access | What it does |
|---|---|---|
caller_lists.read |
Read | List the caller lists on a campaign or buyer, or show one in full. |
caller_lists.manage |
Manage | Create, update, or delete a caller list, including its auto-add tag rule. |
caller_list_numbers.read |
Read | List the numbers on a caller list, search within them, or check a single number. |
caller_list_numbers.manage |
Manage | Add or remove one number on a caller list. |
caller_list_uploads.read |
Read | Check the status of bulk uploads, including any errors. |
caller_list_uploads.manage |
Manage | Bulk-add or bulk-remove numbers in one batch, optionally replacing the list’s contents. Processing is asynchronous. |
caller_list_checks.manage |
Read | Check whether a caller number is on a list, honouring the list’s removal window. Despite the name it changes nothing, so read access is enough. |
Tags, IVR prompts, and conversions
| Tool | Access | What it does |
|---|---|---|
tags.read |
Read | List the tag keys the company has defined, or show one in full. (Tag keys, not the values on individual calls.) |
tags.manage |
Manage | Create, update, or delete a tag key. |
prompts.read |
Read | Inspect the IVR prompts on a campaign, buyer, or number — the greeting and other spoken messages. |
prompts.manage |
Manage | Create, update, or delete a prompt. Prompts speak text-to-speech or a music preset; audio uploads aren’t supported over MCP. |
conversion_groups.read |
Read | Inspect the conversion groups on a campaign, source, buyer, or number — the rules that decide when a call converts and for how much. |
conversion_groups.manage |
Manage | Create, update, or delete a conversion group and the payout/revenue rules inside it. |
prompts.* are IVR greetings and spoken messages — not MCP prompt templates.
Webhooks and postback keys
| Tool | Access | What it does |
|---|---|---|
webhooks.read |
Read | List the webhooks on a campaign, buyer, number, or company, or show one in full including the URLs it fires. |
webhooks.manage |
Manage | Create, update, or delete a webhook — its trigger, delay, dedupe window, tag rules, and pixels. No dry run. |
webhooks.templates.read |
Read | Browse the webhook configurator templates and the parameters each one needs. |
webhooks.configurations.manage |
Manage | Create a webhook from a template by supplying its parameters — the easy path when a template fits. No dry run. |
webhooks.test_fires.manage |
Manage | Test-fire a webhook against the real endpoints with a fake call, and report each pixel’s URL, status, and response. No dry run. |
postback_keys.read |
Read | Inspect postback keys on a campaign, buyer, handler group, source, or company, including endpoint URLs. |
postback_keys.manage |
Manage | Create, update, or delete a postback key. |
Note
webhooks.test_fires.manage makes real HTTP calls to whatever the webhook
points at, so it counts against that endpoint’s rate limits. It’s the right
tool for “does this integration actually work?” — just be aware it isn’t a
simulation.
Calls and reporting
Read-only. There are no tools that create or modify call records.
| Tool | Access | What it does |
|---|---|---|
calls.read |
Read | Inspect individual calls: list a page (filtered by campaign, buyer, source, status, duration, revenue, tags, time window, free text) or show one call in full by its uuid. |
calls_drill_down_tables.read |
Read | The pivot/rollup report. Groups calls server-side by the dimensions you name, returns metrics per group plus a totals row, and drills a level deeper on request. It also computes metrics the raw records don’t carry — telco cost, profit, connected counts. |
Any aggregate question — a count, a sum, a per-buyer or per-publisher breakdown
— goes through calls_drill_down_tables.read, in one round trip. calls.read
is for looking at specific calls.
Not available (yet)
Deliberately absent today:
- RTB reporting. Coming alongside the new RTB Dashboard, and shipping with it.
- Billing and account administration. No tool reads or changes billing, users, or roles.
- Integrations, number extensions, and standalone suppression lists. Suppression is reachable through the caller-list tools instead.
- Audio file uploads for IVR prompts. Text-to-speech and music presets only.
- Deleting a number pool. Create and update only.
The catalog grows as Retreaver does. Because assistants cache the tool list for the life of a session, start a new session now and then to pick up what’s new.
Related
Help us improve this article or request new support guides.