MCP servers

These endpoints are for the VIP plan only. Other plans get a 403. See Plan access.

An MCP server gives a voice agent more tools. A workspace can have up to 10, and a voice agent can use up to 5.

Method	Path	What it does
`GET`	`/v1/mcp-servers`	List the workspace’s MCP servers
`POST`	`/v1/mcp-servers`	Add one. Returns `201`.
`GET`	`/v1/mcp-servers/{id}`	Get one
`PATCH`	`/v1/mcp-servers/{id}`	Update one
`DELETE`	`/v1/mcp-servers/{id}`	Delete one. Returns `204`.
`POST`	`/v1/mcp-servers/{id}/test`	Connect with the saved settings and list the tools
`GET`	`/v1/agents/{agentId}/mcp-servers`	List the servers an agent uses
`PUT`	`/v1/agents/{agentId}/mcp-servers`	Set the servers an agent uses: `{ "mcpServerIds": [...] }`. An empty list removes all. Voice agents only.

An account API key sends workspaceId in the body on create, and in the query on list.

Fields

string

required

The server’s name. Each name is used once per workspace.

string

required

The server URL. It must be a public https address.

string

bearer or api_key. Send null on update to remove the auth.

string

The secret for authType.

object

Extra headers to send.

authValue and header values are write only. We never send them back. A response shows hasAuth and the header names.

If you change url to another address (a different host, http or https, or port), send authValue and headers again in the same request, or set authType to null and headers to {} to remove them. The saved ones stay with the old address, and we refuse the change with a 400.

Response

{
  "id": "9b2f6c1a-3e4d-4a5b-8c7d-0e1f2a3b4c5d",
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Inventory",
  "url": "https://mcp.example.com/mcp",
  "authType": "bearer",
  "hasAuth": true,
  "headerNames": [],
  "toolCount": 4,
  "lastConnectedAt": "2026-10-11T10:00:00Z",
  "createdAt": "2026-10-11T09:00:00Z",
  "updatedAt": "2026-10-11T10:00:00Z"
}

Test an MCP server

POST /v1/mcp-servers/{id}/test We connect with the saved URL, headers and auth and ask for the tool list. A redirect to a private or internal address is refused. When a redirect goes to another address (a different host, http or https, or port), we do not send your auth there. Your other headers go with it. You can test 10 times a minute per workspace.

Response

{ "success": true, "tools": [{ "name": "check_stock", "description": "Look up stock for a product" }] }

When the connection fails, success is false and error says why.

Errors

Status	When
`400`	A field is wrong, the URL is not a public `https` address, the workspace already has 10 servers, an id in `mcpServerIds` is not a server in the agent’s workspace, the agent is not a voice agent, or `url` moved to another address without the auth and headers.
`404`	The server or agent is not in your API key’s scope.
`429`	More than 10 tests in a minute. Wait a minute.

API Reference

Workspaces

Agents

Phone Numbers

Contacts

Knowledge

Templates

Campaigns

Calls

Workflows

Conversations

Fields

Test an MCP server

Errors

​Fields

​Test an MCP server

​Errors

Fields

Test an MCP server

Errors