MCP server
Tools and write safety
The read and write tools the OnCore MCP server exposes, how destructive changes are confirmed, and how results are kept small enough for an agent to reason over.
The server exposes 19 tools. They are shaped around what a developer wants to do rather than around individual API endpoints, so one tool call often covers several requests, and a few tools stand in for a whole family of resources.
This page assumes the server is installed. See Introduction if not.
Read tools#
Always available, regardless of write mode.
| Tool | What it does |
|---|---|
whoami | Reports the environment, key type, write mode, and every capability the server does not have. |
list_assistants | Lists your assistants with their linked prompt, voice, model and phone number. |
get_assistant | Full configuration for one assistant. Can resolve prompts, tools, documents, task groups and the phone number in the same call. |
list_calls | Searches voice calls by assistant, status, date range, duration or free text. |
get_call | One call, with the transcript, analysis and cost returned on request. |
get_call_insights | How up to 25 calls actually ran: pipeline models, per-stage latency, and a turn-by-turn timeline of speech and tool calls. |
list_conversations | Searches text conversations across SMS, web chat and WhatsApp. |
get_conversation | One text conversation with its messages. |
get_activity_overview | What is happening now: calls in progress, and recent activity per assistant. |
list_catalogue | The voice, language-model and transcriber catalogues, filterable by provider or language. |
list_resources | Lists any one configuration resource: prompts, tools, documents, dictionaries, task groups, capture forms, transfer reasons, SMS reasons, custom instructions, phone numbers, test suites or test runs. |
get_resource | One of those resources in full. A test suite lists every case by id and size, with the full cases on request; a test run comes back as a verdict per case, with transcripts on request. |
Write tools#
Available when ONCORE_WRITES is confirm (the default) or unattended.
| Tool | What it does |
|---|---|
create_assistant | Creates an assistant. It is not live until a phone number is linked. |
update_assistant | Changes an assistant's configuration. |
link_assistant | Wires an assistant to tools, dictionaries, documents, task groups or a phone number. |
set_assistant_override | Overrides a shared tool's description or a step's instruction for one assistant, without editing the shared object. channel: "text" targets the tool's text-conversation instructions instead of the voice ones. |
create_resource | Creates one configuration resource, including a test suite or a test case. |
update_resource | Updates one configuration resource. Always partial: send only the fields you want changed. |
delete_resource | Deletes one configuration resource. Deleting a test suite removes its cases; past runs stay readable. |
Two details worth knowing, because they differ from calling the API directly.
update_resource is always partial. Some of the underlying routes replace the whole record rather than merging. The server reads the current record and resends the fields you did not mention, so you never have to know which routes behave which way.
Assistant links are not part of update_assistant. Tool, dictionary and phone-number links are managed only through link_assistant, which reads the current set and applies your addition or removal to it. Sending a partial list of tools through a general update would replace the whole set and silently drop the links you left out, so update_assistant does not accept those fields at all.
Test suites and runs#
A test suite is a set of simulated conversations with one assistant, up to 12 cases. Each case describes a caller, the outcome the assistant should reach, and optional assertions: that a tool was or was not called, or that a value read from the transcript compares as expected. The agent can create, edit and delete suites and cases.
It cannot start a run. A run is a metered simulation, where language models play the caller, answer as the assistant and judge each conversation, once per run of every case. So after each suite or case change the agent gives you the steps instead: open Tests in the dashboard, open the suite, choose Runs per case and click Run suite. Text runs need an assistant on a chat model. A suite on a speech-to-speech model such as GPT-Live is refused at that click with the reason, and the agent's steps say so, so retarget the suite or test that assistant with a real call. When the run has finished, ask the agent to read it. It lists the suite's runs and reads the newest, which reports for each case whether it passed, how many of its runs passed, the judge's reason and any failed assertions.
Write safety#
By default, anything that changes what a live assistant does is confirmed before it applies.
The first call returns a preview: the current state, the resulting state, and a single-use token. Nothing has changed at that point. The change applies only when the tool is called again with that token.
The token is bound to the exact arguments it was issued for. Change any of them and the token is refused, so a preview of a small change cannot be used to apply a larger one. Tokens expire, and each one works once.
Some writes skip the gate because they cannot affect a live call. Creating a prompt, a document or a task group applies immediately, since nothing is using it until you link it.
Choosing a write mode#
confirm is the default and suits interactive work: you see a diff before anything changes.
off removes the write tools entirely. This is stronger than instructing an agent not to change things, because the tools are not registered at all and the agent has no way to know the capability exists. Use it when an agent is reading production configuration and should have no path to modifying it.
unattended applies without the confirmation round. Only appropriate for scripted use where no human is reading the output.
One limitation stated plainly: in confirm mode, if your MCP client does not support prompting you mid-call, the confirmation round is the agent re-calling with its own token rather than you approving it. The result text says which of the two happened. That still prevents accidents and still prevents a widened change, but it is not a human approval, and off is the only setting that is a hard boundary.
How results stay small#
An agent has a limited context window, and some OnCore responses are large. The server prunes rather than passing responses through.
List results carry a summary of each row, with long text replaced by its length so the agent can decide what to open. Call transcripts and conversation messages are returned in windows with a pointer to the next one. The voice catalogue drops provider-specific configuration, which is most of its size and rarely what you need to choose a voice. Every result has a ceiling, and a truncated result names the argument that would narrow the query rather than just reporting that there was more.
The practical effect is that filtering costs you nothing and helps a lot. Asking for one provider's voices, or one assistant's calls in a date range, gives the agent a result it can reason over instead of one it has to summarize.
Next steps#
- Introduction covers installation and configuration.
- Authentication explains key types and tenant scope.
- Read call activity documents the call and transcript data these tools return.