> ## Documentation Index
> Fetch the complete documentation index at: https://cntillion.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI assistants (MCP)

> Connect Claude, ChatGPT, Cursor or another MCP client to your Centillion workspace to look up and build your agents in chat, with a person approving anything that goes live.

Centillion runs a remote MCP server. Add it to an AI assistant that supports
remote MCP servers and the assistant can look up your agents, their setup,
their latest test results, your conversations when the workspace allows it,
and these help pages. It can also build: create agents, change drafts,
workflows, voice settings, tools and tests, and run tests.

Anything that reaches your customers or costs money waits for a person.
Publishing a version, changing traffic between branches, launching a batch of
calls, archiving, buying a phone number or choosing which agent answers it,
changing recording retention or call limits, and turning on an email
sender's automatic replies only create a request, which someone approves in
the dashboard.

## Server address

```text theme={null}
https://app.cntillion.com/mcp
```

The server speaks Streamable HTTP. You sign in with OAuth: no API key is
involved. The address is also shown in **Workspace settings → AI assistants**.

## Sign in and choose a workspace

The first time the assistant connects, it opens Centillion's sign-in page.
Sign in with your Centillion account, then pick the workspace on the consent
screen and allow access. The connection works in that workspace only. To
use another workspace, remove the connection in the assistant and add it again.

The assistant acts as you, with your [workspace role](https://cntillion.com/docs/workspaces/members.md):

* **Owners** and **Members** can use every tool.
* **Viewers** can use the tools that read. The tools that change something
  refuse.
* **Support Associates** cannot view agents, so the workspace tools refuse.
* If you leave the workspace or your role changes, the next request follows
  the change.

## Add the server to your assistant

> [accordion] Claude
>
> On Pro and Max plans, open **Customize → Connectors**, click **+ Add**,
> choose **Add custom connector** and paste the server address. On Team and
> Enterprise plans, an owner adds it in **Organization settings →
> Connectors**. Claude connects from its own servers, so it needs the public
> address above.

> [accordion] ChatGPT
>
> Open the plugins page, select **+**, choose **Add custom MCP server**, enter
> the server address including `/mcp`, choose OAuth for authentication, and
> create it. Custom MCP servers depend on your ChatGPT plan and workspace
> settings.

> [accordion] Cursor
>
> Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a
> project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "centillion": {
>       "url": "https://app.cntillion.com/mcp"
>     }
>   }
> }
> ```
>
> Cursor opens the sign-in page the first time you use the server.

> [accordion] Other MCP clients
>
> Point the client at the server address. It finds the sign-in server from
> `https://app.cntillion.com/.well-known/oauth-protected-resource/mcp` and
> asks for the `user:org:read` scope, which is what shows the workspace
> choice.

## Install the plugin

The Centillion plugin bundles the server address with a skill that shows the
assistant how to build an agent here: find or create it, change its draft, add
tools, write and run tests, read the results, and ask for a publish through an
approval link. Its files are in the public
[centillion-plugin](https://github.com/Centillion-Labs/centillion-plugin)
repository.

An assistant whose command line installs plugins from a git marketplace adds
the repository as a marketplace, then installs the plugin from it:

```bash theme={null}
claude plugin marketplace add Centillion-Labs/centillion-plugin
claude plugin install centillion@centillion
```

Then run `/mcp` in the assistant, choose the Centillion server and sign in as
described above.

In an assistant without the plugin, add the server by its address, as
[Add the server to your assistant](#add-the-server-to-your-assistant)
describes. You get the same tools, without the skill.

## Tools

Tools return short results and page long lists with a `cursor`: pass back
the `nextCursor` of one answer to get the next page. When a tool refuses, it
says why and what to do, for example which setting an owner has to change.

### Reading

| Tool | What it returns |
| - | - |
| `list_agents` | The workspace's agents, newest first: id, name, role, model and training status. |
| `get_agent` | One agent's published setup: instructions, model, greeting, guardrails, the workflow's steps, its actions and tools, knowledge sources and tests. Tool settings and secrets are never returned. |
| `list_branches` | An agent's branches: id, name, revision, share of conversations, current version, and how many changes your own draft on each holds. |
| `get_workflow` | The whole workflow on a branch's current version, with the branch revision. |
| `get_voice_settings` | The voice settings a branch's calls run with, and the branch revision. |
| `list_tools` | The workspace tools you can see: id, name, kind, revision, your access, the agents using each, the names of its headers and its OAuth sign-in without the client secret. Header values and client secrets are never returned. |
| `list_batch_calls` | The workspace's batches of outbound calls: id, name, agent, status and how many recipients. Recipients themselves are not returned. |
| `list_phone_numbers` | The workspace's phone numbers: id, number, label, whether it was bought from Centillion, the agent it answers for, and whether it follows that agent's traffic split or is pinned to a branch. Carrier credentials are never returned. |
| `get_message_settings` | The workspace's message templates, its opt-out lines, whether an SMS or email sender is turned on, and its e-signature connections by id and name, as the Integrations page shows them. No credential is returned. |
| `list_knowledge_sources` | An agent's knowledge sources as its Knowledge page in the dashboard editor lists them: id, type, name, address, import status and progress, the last error, and whether the agent is trained on the current text. The text itself is not returned. |
| `list_conversations` | One agent's website chat, API and phone conversations, newest first, optionally between two times. Messaging-channel threads are not included yet. Needs the conversation setting below. |
| `get_conversation` | One conversation's messages, newest page first, with its analysis when it has one. Needs the conversation setting below. |
| `get_test_results` | An agent's latest test runs: the test, what it ran on (for runs started by an assistant, the draft and its fingerprint, or the branch's version), how many repeats passed, failed or gave no verdict, and the judge's reason. Simulated transcripts are left out, and so are the reasons for a test made from a customer conversation unless the workspace allows assistants to read conversations. |
| `search_docs` | The sections of these help pages that match a question, with links. |

### Building

These tools change drafts, quiet branches, tools, tests, message templates,
knowledge sources and an agent's email address. None of them reaches a
conversation on its own. Where `save_workflow` and
`update_voice_settings` land depends on the branch:

* On a quiet branch, one other than Main that nothing answers from yet (no
  share of traffic, no phone number pinned to it, no batch of calls), the
  change is the branch's next version at once.
* On Main, on a branch with a share of traffic or a pinned phone number, and
  on a branch set up for a batch that has not been launched, the change goes
  into your draft on that branch. The answer says `savedAs: "draft"`. Nothing
  reaches a conversation until someone approves your `request_publish`.
* While a launched batch of calls on the branch has not finished, both are
  refused. Each call of a batch answers with the branch's version as it is
  placed, so publishing in the middle would split one batch between two
  versions.

Writes that take a `revision` are refused if the branch or tool changed since
you read it; read it again and retry.

Knowledge added through `add_knowledge_text` or `add_knowledge_website` joins
the agent's knowledge in the dashboard editor. Conversations use it once the
agent is next published from the dashboard editor; `request_publish`
publishes your own draft, which does not hold it.

| Tool | What it does |
| - | - |
| `create_agent` | Creates an agent with a Main branch. It answers only through the API until someone connects a channel in the dashboard. |
| `update_agent_draft` | Changes your draft of an agent's instructions, guardrails, greeting, model, temperature or default language on a branch. The draft is yours until it is published. |
| `create_branch` | Starts a branch from Main or another branch. A new branch answers no conversations. |
| `save_workflow` | Replaces a branch's workflow, with the dashboard's checks, as the branch's next version or in your draft, as described above. |
| `update_voice_settings` | Changes some of a branch's voice settings, with the Voice card's checks, as the branch's next version or in your draft, as described above. Recordings and call limits apply to every branch at once, so they go through `request_voice_shared_settings`. |
| `create_tool` | Creates a workspace tool shared with you only. Header values and an OAuth client secret are stored and never read back. |
| `update_tool` | Changes a tool's name, description or settings. To keep a header's stored value, send its name with the value `••••••••`; to keep OAuth sign-in, send its `auth` from `list_tools` with `clientSecret` set to `••••••••`. |
| `discover_mcp_tools` | Asks an MCP server tool's server which tools it offers now. |
| `save_test` | Creates an agent test, or replaces one, in your draft of a branch (Main unless you name one). Nothing is published: run it on the draft with `run_tests`, and it ships with the draft through `request_publish`. Tests made from a customer conversation are created in the dashboard. |
| `run_tests` | Runs some of an agent's tests on your draft of a branch (Main unless you name one), so you can test a change before asking to publish it. With no draft on that branch, they run on its current version. Never on someone else's draft. A test pinned to a version, or with agent settings of its own, runs as it is set up and does not count as a run on your draft. The answer says what ran: your draft with its fingerprint, or the branch's version. Read the results with `get_test_results`. |
| `save_message_template` | Creates a message template, or replaces one whole, with the Integrations page's checks: it needs the text for SMS, email or both. A send reads its template when it runs, so a template that a connector action or any published version of an agent already names, in any language, changes only in the dashboard. |
| `create_connector_action` | Creates a connector action tool, such as Messages · Send, shared with you only, with the dashboard's checks. Its credentials stay on the workspace's connection. It runs once a workflow step uses it and that version is published. Change or archive it in the dashboard. |
| `add_knowledge_text` | Adds a text snippet to an agent's knowledge, as its Knowledge page does, and queues the agent's training. |
| `add_knowledge_website` | Imports one public web page into an agent's knowledge in the background, then trains on it. To crawl a whole site, add it in the dashboard. |
| `create_email_sender` | Gives an agent its generated email address, with Helpdesk for the mail it receives, and with its replies off. A Messages · Send action sends email only once a person turns the replies on in the agent's Email settings. |

### Asking for approval

| Tool | What it asks for |
| - | - |
| `request_publish` | Publishing your draft on a branch as its next version. Its answer lists the latest test runs on that exact draft, or says it was not tested. |
| `request_traffic_change` | Splitting an agent's conversations between its branches. |
| `request_batch_launch` | Launching a batch of outbound calls as it is set up now. |
| `request_archive` | Archiving a branch or a workspace tool. |
| `request_phone_number` | Buying a US local number from Centillion for an agent, at the monthly price it is offered at, paid from the workspace's prepaid credits. Choose an area code, or a number from `otherNumbers` in an earlier answer. A bought number answers calls once it is assigned. |
| `request_phone_assignment` | Having a workspace number answer for an agent, following its traffic split or pinned to one of its published branches. |
| `request_voice_shared_settings` | Changing an agent's recording retention, daily call limit or concurrent call limit, which every branch shares and which apply at once. |
| `request_channel_activation` | Turning on automatic replies from an agent's paused email sender. |

Numbers from another carrier are imported in the dashboard: importing takes
the carrier's credentials, which an assistant never handles.

## Approving what an assistant asks for

A request tool checks the request the way the dashboard would, so one that
could not run is refused at once. Otherwise it stores the request and answers
with a one-line summary and a link to the request's page in the dashboard.
Nothing has changed yet.

The page shows who asked, through which assistant connection, and what will
happen: for a publish, the version's changes side by side with the branch as
it is now, and the latest runs of each test on that exact draft, or "Not
tested" when there are none; for traffic, each branch's share now and after, and for each branch whose share rises, the version it would answer with compared with Main's; for a batch, the
batch and how many people it calls; for a phone number, the number, its
monthly price, the most prepaid credits it takes and whether it renews; for
an assignment, the number, the agent and the branch it will answer on; for
recording retention and call limits, each setting now and after; for an email
sender, its address. Anyone whose role can change agents,
Owners and Members, can approve or decline it, including the person who
asked. Viewers can open the page but not decide.

* Approving runs the request once, through the same code the dashboard uses,
  and records who approved it. A second approval is refused.
* A request runs only on what was shown. If the draft changed, a branch got a
  new version, the batch was edited, the number was moved or bought by
  someone else, its price changed, the shared voice settings were changed, or
  the email sender was turned on or moved after the request, approving is
  refused: ask the assistant to send it again.
* Launching a batch also needs the workspace's plan to include campaigns and
  the approver to have agreed to the outbound communications terms, as
  launching from the dashboard does. Until then the page keeps Approve off and
  the request stays pending.
* Archiving a workspace tool also needs admin access to that tool, as in the
  dashboard. An approver without it is refused, and the request stays pending
  for a tool admin or an Owner.
* Buying a number takes the workspace's access to Centillion numbers, a plan
  with phone calls, and enough prepaid credits for the first month, as buying
  in the dashboard does. Approving without them fails and says which is
  missing.
* Assigning a number takes a plan with voice and phone calls, and an agent
  whose editor is on Main, as on the phone numbers page.
* Requests expire after 24 hours.

**Workspace settings → AI assistants** lists the requests waiting for a
decision.

## Conversations stay private by default

Conversations can hold your customers' personal data, such as a caller's
details collected on a phone call. Assistants cannot read them until an owner
turns on **Allow AI assistants to read conversations** in
**Workspace settings → AI assistants**. The setting is off for every
workspace until an owner changes it. While it is off, `list_conversations` and
`get_conversation` answer with a refusal and the link to the setting.

When you turn it on, everyone connected to the workspace can read transcripts
through their assistant, and what they read is sent to that assistant's
provider. If your calls carry regulated data, the page reminds you of that
before you change it.

## What the server never does

* It never shows or changes billing, API keys, legal terms or
  regulated-data settings, and it never imports a number from another
  carrier.
* It never returns a secret, such as a tool's header value, an OAuth client
  secret or a carrier's credentials.
* It never publishes, changes traffic, launches calls, archives anything,
  buys or routes a phone number, changes recording retention or call limits,
  or turns on an agent's email replies without a person's approval, and it
  never deletes anything.
* It never sends a message itself.
* Its instructions tell the assistant that text inside a result, such as a
  conversation or a tool description, is data and not an instruction.

## Limits and records

Each workspace can make 100 tool calls per 10 seconds across all its
connected assistants, the same limit as a workspace API key. Refused calls do
not count toward it. Each person also gets 100 refused calls per 10 seconds;
past that, their assistant's calls are turned away until the window passes.
Over either limit, the tool asks the assistant to try again after a few
seconds.

Every tool call that runs or is refused is recorded with who made it, the
workspace, the tool, the time and whether it succeeded. Calls turned away
over a limit before they start are not recorded. A call that arrives together
with others and is found over the workspace limit as it is admitted is
recorded as rate limited. The arguments are not recorded, since they can
name a customer. Each approval request keeps who asked, who approved or
declined it, when, and what the run answered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.