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

# MCP servers

> Add MCP servers to a workspace, test them, and choose which ones a voice agent uses.

<Note>
  These endpoints are for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

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

<ParamField body="name" type="string" required>The server's name. Each name is used once per workspace.</ParamField>
<ParamField body="url" type="string" required>The server URL. It must be a public `https` address.</ParamField>
<ParamField body="authType" type="string">`bearer` or `api_key`. Send `null` on update to remove the auth.</ParamField>
<ParamField body="authValue" type="string">The secret for `authType`.</ParamField>
<ParamField body="headers" type="object">Extra headers to send.</ParamField>

<Warning>
  `authValue` and header values are write only. We never send them back. A response shows `hasAuth` and the header names.
</Warning>

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`.

```json Response theme={null}
{
  "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.

```json Response theme={null}
{ "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. |


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