---
title: "Register a new MCP server."
method: POST
path: "/mcpservers"
tags: ["AI"]
---

# Register a new MCP server.

`POST /mcpservers`

Registers a remote Streamable-HTTP MCP server owned by the authenticated customer. Opt an AI in via the AI's `mcp_server_ids` field. **Tool use scope:** a whitelisted server's tools are exposed to that AI's Normal-type, single-AI sessions only. See that field for what discovery and dispatch do.

## Request body

- object
  - `name` string, required — Name of the MCP server.
  - `detail` string — Detailed description of the MCP server.
  - `url` string, uri, required — Streamable-HTTP MCP endpoint. Must be https.
  - `auth_type` '' | 'bearer' | 'api_key' — How the outbound MCP call authenticates. Empty string sends no Authorization header.
  - `api_key_header` string — Header name used when auth_type is api_key, e.g. X-API-Key. Ignored otherwise.
  - `secret` string — Bearer token or API key value. Stored encrypted at rest; never returned in responses.

## Response `200`

The created MCP server.

- AIManagerMcpServer — A customer-registered remote MCP (Model Context Protocol) server. Excludes the stored secret entirely; `has_secret` indicates whether one is configured. Whitelist a server for an AI via that AI's `mcp_server_ids` field. **Tool use scope:** a whitelisted server's tools are presented to that AI's Normal-type, single-AI sessions; `type=insight` AIs, team-typed AI calls, and realtime voice call sessions never receive MCP tools.
  - `id` string, uuid — The unique identifier of the MCP server.
  - `customer_id` string, uuid — The unique identifier of the associated customer. Returned from the `GET /customers` response.
  - `name` string — Name of the MCP server.
  - `detail` string — Detailed description of the MCP server.
  - `url` string, uri — Streamable-HTTP MCP endpoint.
  - `status` 'active' | 'disabled' — disabled servers are excluded from tool list resolution and tool calls.
  - `auth_type` '' | 'bearer' | 'api_key' | 'oauth', required — How the outbound MCP call authenticates. Empty string sends no Authorization header. A server is moved INTO "oauth" only by completing POST /mcpservers/oauth/complete; sending "oauth" on a server that is not already connected is rejected. Re-sending the current "oauth" value on an already-connected server is accepted. Moving a connected server OUT of "oauth" is allowed and irreversibly erases its stored OAuth access and refresh tokens.
  - `api_key_header` string — Header name used when auth_type is api_key.
  - `oauth_vendor` 'github' | 'linear' — Which OAuth vendor this server is connected to. Only set when auth_type is "oauth"; it is cleared along with the stored tokens when a server is moved out of "oauth".
  - `has_secret` boolean, required — Whether a bearer token / API key / OAuth access token is configured. The secret/token value itself is never returned.
  - `tm_create` string, date-time — Timestamp when the MCP server was registered.
  - `tm_update` string, date-time — Timestamp when the MCP server was last updated.
  - `tm_delete` string, date-time — Timestamp when the MCP server was deleted.

## Other responses

- `400` — Invalid request (INVALID_ARGUMENT).
- `401` — Authentication required (UNAUTHENTICATED).
- `500` — Internal error (INTERNAL).

## Changes

- **2026-09-24** `3c004713c5fa` — 1 info
  - the response property `auth_type` became required for the status `200`
- **2026-09-12** `a5e92b1a8467` — 1 warning, 1 info
  - added the new `oauth` enum value to the `auth_type` response property for the response status `200`
  - added the optional property `oauth_vendor` to the response with the `200` status
- **2026-09-10** `f3996b9c5c48` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/mcpservers/post.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) · [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/6a2b13260ccc?raw)