Skip to main content
Builder MCP exposes PolyAI’s platform as MCP tools, grouped into the families below. Your client discovers them automatically on connection — you don’t configure tools by hand. Each tool carries its own input schema, which the client reads directly from the server; the parameter tables below reproduce that schema so you can see what each tool takes without connecting first. US, UK, and EU workspaces expose 131 tools; self-serve Studio workspaces expose 125 (the Alerts family is enterprise-only). Tool names appear exactly as your client sees them in tools/list.
Every tool maps to a PolyAI REST endpoint. Parameters are named path_*, query_*, or nested under a request body in the raw schema — the tables below strip those prefixes and expand the body’s top-level fields. For deeply nested request bodies, follow the API reference link on each tool for the complete schema. To see exactly what your client discovered, ask it to list its tools or query the endpoint’s tools/list method (see Quickstart → Verify).

Build & manage agents

Agents

create-agent

Create agent. API reference: Create agent.

list-agents

List agents. API reference: List agents.

duplicate-agent

Duplicate agent. API reference: Duplicate agent.

delete-agent

Delete agent. API reference: Delete agent.

Behavior

get-agent-behavior-rules

Get agent behavior rules. API reference: Get agent behavior rules.

update-agent-behavior-rules

Update agent behavior rules. API reference: Update agent behavior rules.

Branches

create-branch

Create branch. API reference: Create branch.

list-branches

List branches. API reference: List branches.

delete-branch

Delete branch. API reference: Delete branch.

merge-branch

Merge branch. API reference: Merge branch.

sync-branch-with-parent

Pull the latest changes from the branch’s parent (main) into it, without merging the branch back. Use to keep a long-lived branch up to date before merging. API reference: Sync branch with parent.

deploy-a-branch

Deploy a branch’s current configuration to an environment (sandbox, pre-release, or live). Triggers any configured test runs as part of the deployment. API reference: Deploy a branch.

check-branch-divergence

Check whether a branch has diverged from its parent branch (the parent has new changes the branch does not have). API reference: Check branch divergence.

get-merge-history-for-a-branch

Get the merge history for a branch, showing which branches were merged into it and when. API reference: Get merge history for a branch.

tag-a-branch-as-staging

Tag a branch as staging to deploy it to pre-release. Only direct children of main can be tagged, and one branch holds the staging tag per project. API reference: Tag a branch as staging.

remove-the-tag-from-a-branch

Remove the tag from a branch, clearing the environment it was deployed to (pre-release for staging, sandbox for internal). API reference: Remove the tag from a branch.

list-archived-branches

List deleted and merged branches that can be restored within their 30-day retention window. Each entry’s status says whether it was merged or deleted. API reference: List archived branches.

restore-an-archived-branch

Restore a soft-deleted branch from the archive back to an active state. API reference: Restore an archived branch.

Deployments

publish-the-current-draft-to-an-environment

Publish the current draft to an environment. API reference: Publish the current draft to an environment.

promote-a-deployment-to-the-next-environment

Promote a deployment to the next environment. API reference: Promote a deployment to the next environment.

rollback-to-a-previous-deployment

Rollback to a previous deployment. API reference: Rollback to a previous deployment.

list-deployments

List deployments for an environment. API reference: List deployments for an environment.

get-a-deployment

Get a single deployment by ID. API reference: Get a deployment.

get-active-deployment-per-environment

Get active deployment per environment. API reference: Get active deployment per environment.

Knowledge base

create-knowledge-base-topic

Create knowledge base topic. API reference: Create knowledge base topic.

get-knowledge-base-topic

Get knowledge base topic. API reference: Get knowledge base topic.

list-knowledge-base-topics

List knowledge base topics. API reference: List knowledge base topics.

update-knowledge-base-topic

Update knowledge base topic. API reference: Update knowledge base topic.

delete-knowledge-base-topic

Delete knowledge base topic. API reference: Delete knowledge base topic.

Variants

create-variant

Create variant. API reference: Create variant.

list-variants

List variants. API reference: List variants.

update-variant

Update variant. API reference: Update variant.

delete-variant

Delete variant. API reference: Delete variant.

Attributes

create-attribute

Create attribute. API reference: Create attribute.

list-attributes

List attributes. API reference: List attributes.

update-attribute

Update attribute. API reference: Update attribute.

delete-attribute

Delete attribute. API reference: Delete attribute.

Connectors

get-a-connector-by-id

Get a connector by ID. API reference: Get a connector by ID.

batch-get-connectors-by-id

Batch get connectors by ID. API reference: Batch get connectors by ID.

list-all-connectors-for-a-project

List all connectors for a project. API reference: List all connectors for a project.

update-a-connector

Update a connector. API reference: Update a connector.

batch-update-connectors

Batch update connectors. API reference: Batch update connectors.

delete-a-connector-and-its-phone-numbers

Delete a connector and its phone numbers. API reference: Delete a connector and its phone numbers.

look-up-connector-by-phone-number

Look up connector by phone number. API reference: Look up connector by phone number.

Connector tokens

A connector token is the per-environment credential a telephony or websocket integration presents so PolyAI routes the call to this agent in that environment. It is not an API key. Treat it as a secret.

list-connector-tokens

List the connector token for each client environment of an agent. Only environments that already have a connector are returned. API reference: List connector tokens.

get-the-connector-token-for-an-environment

Get the connector token for one client environment. Returns 404 if the environment has no connector yet. API reference: Get connector token.

ensure-a-connector-token-exists-for-an-environment

Create a connector for one client environment if none exists, and return its token. Safe to call repeatedly: an existing token is returned unchanged. API reference: Ensure connector token.

Phone numbers

get-a-specific-phone-number

Get a specific phone number. API reference: Get a specific phone number.

batch-get-phone-numbers

Batch get phone numbers. API reference: Batch get phone numbers.

list-all-phone-numbers-for-a-project

List all phone numbers for a project. API reference: List all phone numbers for a project.

import-a-single-phone-number

Import a single phone number. API reference: Import a single phone number.

import-phone-numbers-into-a-project

Import phone numbers into a project. API reference: Import phone numbers into a project.

delete-a-single-phone-number

Delete a single phone number. API reference: Delete a single phone number.

delete-phone-numbers-from-a-project

Delete phone numbers from a project. API reference: Delete phone numbers from a project.

reassign-a-phone-number-to-a-different-connector

Reassign a phone number to a different connector. API reference: Reassign a phone number to a different connector.

Config pages (real-time config)

get-a-config-page-by-environment

Get a config page by environment. API reference: Get a config page by environment.

list-all-config-pages

List all config pages. API reference: List all config pages.

update-config-variables-for-an-environment

Update config variables for an environment. API reference: Update config variables for an environment.

upsert-the-json-schema-for-a-config-page

Upsert the JSON Schema for a config page. API reference: Upsert the JSON Schema for a config page.

Flows

list-flows

List all flows on a branch. API reference: List flows.

create-flow

Create a flow on a branch. API reference: Create flow.

get-flow

Get a single flow by ID. API reference: Get flow.

update-flow

Update a flow’s name, description, start step, or steps. API reference: Update flow.

delete-flow

Delete a flow from a branch. API reference: Delete flow.

Functions

list-all-functions-for-an-agent-on-a-branch

List all functions for an agent on a branch. API reference: List functions.

create-a-new-function

Create a new custom function on a branch. API reference: Create function.

get-a-single-function-by-id

Get a single function by ID. API reference: Get function.

update-a-function

Partially update a function: name, description, code, parameters, or latency control. Renaming also rewrites the def name in the code. Returns 409 Conflict if a rename would orphan flow-step references, unless force is true. API reference: Update function.

delete-a-function

Archive a function on a branch. Returns 409 Conflict if the function is still referenced by flow steps, topics, stop keywords, behaviors, or variables. Call get-function-references first to see what would break. API reference: Delete function.

get-function-references

List the entities that reference a function. API reference: Get function references.

validate-all-functions

Return validation issues found across all functions on a branch. API reference: Validate functions.

get-the-start-function-code

Get the start function code. Runs synchronously before every conversation greeting. API reference: Get start function.

get-the-end-function-code

Get the end function code. Runs asynchronously after every conversation ends. API reference: Get end function.

execute-a-function

Execute a function. API reference: Execute function.

duplicate-a-function

Duplicate a function. API reference: Duplicate function.

replace-the-start-function-code

Replace the entire code of the start function. This is a complete replacement, not a partial edit. API reference: Replace start function.

replace-the-end-function-code

Replace the entire code of the end function. This is a complete replacement, not a partial edit. API reference: Replace end function.

get-python-type-stubs-for-a-function

Return generic Python type-stub boilerplate (for example, the Conversation class) for IDE autocomplete when editing a function’s code. API reference: Get function type definitions.

Builder knowledge

Search PolyAI’s builder knowledge base for design patterns, implementation rules, and best practices before building or modifying an agent.

search-the-builder-knowledge-base

Search the builder knowledge base. Returns ranked results by relevance. API reference: Search the builder knowledge base.

list-builder-knowledge-categories

List the available knowledge categories to help narrow searches, such as functions, flows, prompting, entities, deployment, integrations, scopes, and patterns. API reference: List builder knowledge categories. This tool takes no parameters.

read-a-builder-knowledge-document-by-path

Read the full content of a knowledge base document by its file path. Use after searching. Returns structured fields parsed from YAML frontmatter plus the markdown body. API reference: Read a builder knowledge document.

Voice & audio

Voice library

register-a-new-voice-in-the-voice-library

Register a new voice in the voice library. API reference: Register a new voice in the voice library.

update-a-voice-in-the-voice-library

Update a voice in the voice library. API reference: Update a voice in the voice library.

get-a-single-voice-from-the-voice-library

Get a single voice from the voice library. API reference: Get a single voice from the voice library.

list-all-voices-in-the-account-s-voice-library

List all voices in the account’s voice library. API reference: List all voices in the account’s voice library.

synthesize-a-short-audio-sample-of-a-voice

Synthesize a short audio sample of a voice. API reference: Synthesize a short audio sample of a voice.

set-the-project-s-active-voice

Set the project’s active voice. API reference: Set the project’s active voice.

Deployed voice configs

create-or-update-a-deployed-voice-configuration

Create or update a deployed voice configuration. API reference: Create or update a deployed voice configuration.

list-deployed-voice-configurations

List deployed voice configurations. API reference: List deployed voice configurations.

delete-a-deployed-voice-configuration

Delete a deployed voice configuration. API reference: Delete a deployed voice configuration.

Voice & disclaimer tuning

get-voice-tuning-settings

Get voice tuning settings. API reference: Get voice tuning settings.

update-voice-tuning-settings

Update voice tuning settings. API reference: Update voice tuning settings.

get-disclaimer-voice-tuning-settings

Get disclaimer voice tuning settings. API reference: Get disclaimer voice tuning settings.

update-disclaimer-voice-tuning-settings

Update disclaimer voice tuning settings. API reference: Update disclaimer voice tuning settings.

Audio cache

list-audio-cache-entries

List audio cache entries. API reference: List audio cache entries. Filter values take an optional operator prefix: eq: (default), gt:, ge:, lt:, le:, in:, ex:, contains: or exists:.

delete-audio-cache-entry

Delete audio cache entry. API reference: Delete audio cache entry.

bulk-delete-audio-cache-entries

Bulk delete audio cache entries. API reference: Bulk delete audio cache entries.

download-cached-audio-file

Download cached audio file. API reference: Download cached audio file.

replace-audio-file-for-a-cache-entry

Replace audio file for a cache entry. API reference: Replace audio file for a cache entry.

update-cache-entry-file-and-settings

Update cache entry file and settings. API reference: Update cache entry file and settings.

generate-a-tts-audio-preview

Generate a TTS audio preview. API reference: Generate a TTS audio preview.

preview-tts-audio-for-a-cache-entry

Preview TTS audio for a cache entry. API reference: Preview TTS audio for a cache entry.

Run, test & inspect

Debug chat

create-a-new-debug-chat-session

Create a new debug chat session. API reference: Create a new debug chat session.

send-a-message-to-a-debug-chat-session

Send a message to a debug chat session. API reference: Send a message to a debug chat session.

Conversations

get-a-conversation-by-id

Get a conversation by ID. API reference: Get a conversation by ID.

list-conversations-for-a-project

List conversations for a project. API reference: List conversations for an agent. Filter values take an optional operator prefix: eq: (default), gt:, ge:, lt:, le:, in:, ex:, contains: or exists:.

get-audio-recording-for-a-conversation

Get audio recording for a conversation. API reference: Get audio recording for a conversation.

add-annotations-to-a-conversation

Add annotations to a conversation. API reference: Add annotations to a conversation.

upsert-a-note-on-a-conversation

Upsert a note on a conversation. API reference: Upsert a note on a conversation.

Test suites

trigger-a-test-run

Trigger a simulation test run. Select test cases explicitly by id, by severity, or by tag via the select field. The legacy flat testCaseIds body is deprecated but still accepted. API reference: Trigger a test run.

get-a-test-run-by-id

Get a test run by ID. API reference: Get a test run by ID.

list-test-runs-for-a-project

List test runs for a project. API reference: List test runs for a project.

list-test-cases

List test cases. API reference: List test cases.

get-test-case

Get test case. API reference: Get test case.

get-test-execution-history-for-a-project

Get test execution history for a project. API reference: Get test execution history for a project.

Outbound calling

trigger-an-outbound-call

Trigger an outbound call. API reference: Trigger an outbound call.

get-the-status-of-an-outbound-call

Get the status of an outbound call. API reference: Get the status of an outbound call.

Manage agent infrastructure

MCP servers on an agent

add-mcp-server

Add MCP server. API reference: Add MCP server.

list-mcp-servers

List MCP servers. API reference: List MCP servers.

connect-mcp-server

Connect MCP server. API reference: Connect MCP server.

update-mcp-server

Update MCP server. API reference: Update MCP server.

delete-mcp-server

Delete MCP server. API reference: Delete MCP server.

Secrets

create-a-secret

Create a secret. API reference: Create a secret.

update-a-secret

Update a secret. API reference: Update a secret.

delete-a-secret

Delete a secret. API reference: Delete a secret.

Monitor deployed agents

The Alerts family is enterprise-only — it’s available on US, UK, and EU workspaces, not on self-serve Studio workspaces.
Watch live agents and react to issues. Backed by the Alerts API.

Alerts

Limiting what a client can do

To narrow what a client can reach, scope the API key itself. Create a least-privilege key limited to the agents and permissions that client needs, for example a read-only key for a monitoring assistant. The key’s scope governs which calls succeed, so a narrowly scoped key can’t create, delete, or publish even though the tools are still discovered.
Last modified on November 12, 2026