---
title: "Create Connector"
method: POST
path: "/v2/connectors"
tags: ["Connectors"]
---

# Create Connector

`POST /v2/connectors`

## Request

- Base URL: `https://tavusapi.com`
- URL: `https://tavusapi.com/v2/connectors`
- Auth: API key in header `x-api-key`

Register an MCP server. What happens next depends on `auth_config.type`.

For **`oauth2`**, Tavus performs discovery against the server and registers itself as a client (Dynamic Client Registration), then returns an `authorize_url` alongside the connector. Send the customer there; the server redirects back to Tavus, which stores the tokens and moves the connector to `oauth_status: linked`. Nothing needs to be registered on your side. If discovery or registration fails the connector is not created, so you can retry cleanly.

For every other type the connector is usable immediately.

Attach the connector to a PAL with [`layers.mcp.connectors`](/sections/conversational-video-interface/pal/mcp-connectors); the in-call agent connects to the server and discovers its tools itself, so there is nothing to import.

## Request body

- object
  - `name` string, required: Human-readable name, e.g. `Linear`.
  - `server_url` string, required: The MCP server endpoint.
  - `auth_config` object: How Tavus authenticates to the server. Defaults to `{ "type": "none" }`. - `{ "type": "none" }` - public server. - `{ "type": "bearer", "token": "..." }` - static bearer token. - `{ "type": "api_key", "name": "X-Api-Key", "value": "...", "location": "header" }` - static key sent as a header (`location: header`, the default) or as a query parameter (`location: query`). - `{ "type": "basic", "username": "...", "password": "..." }` - HTTP basic auth. - `{ "type": "oauth2_client_credentials", "token_url": "https://...", "client_id": "...", "client_secret": "...", "scope": "..." }` - Tavus exchanges the client credentials for a bearer token before each call; `scope` is optional. - `{ "type": "oauth2" }` - Tavus runs the OAuth flow; the response carries `authorize_url`. Secrets are encrypted at rest and never returned.

## Response `200`

Connector created. For `oauth2`, also carries `authorize_url` and `oauth_state`.

- object: An MCP server you have registered. Secret material is never returned: `auth_config` comes back with its `type` and non-secret fields only, and OAuth tokens are omitted entirely.
  - `connector_id` string: The unique identifier of the connector. Use this everywhere a connector is referenced, including `layers.mcp.connectors` on a PAL.
  - `owner_id` integer: The account that owns the connector.
  - `team_id` integer, nullable: Team the connector belongs to, when applicable.
  - `name` string: Human-readable name. Also the basis of the label the background agent sees for this service.
  - `source` string: Connector kind. `mcp` today.
  - `server_url` string: The MCP server endpoint.
  - `auth_config` object: How Tavus authenticates to the server, with secrets removed. See the create request for the accepted shapes.
  - `selected_tool_names` string[], nullable: Always `null` on connectors created today, and not settable: the create and update endpoints reject the field. A leftover from the removed tool importer - tool scoping is a per-PAL decision, so use `layers.mcp.connector_tools`.
  - `oauth_status` 'none' | 'pending' | 'linked' | 'needs_reauth': `none` for non-OAuth connectors. `pending` once an authorize URL has been issued but the flow is not finished. `linked` when Tavus holds a working token. `needs_reauth` when the refresh token stopped working - send the customer through [Reconnect OAuth](/api-reference/connectors/reconnect-connector-oauth).
  - `oauth_scopes` string[], nullable: Scopes granted by the authorization server.
  - `access_token_expires_at` string, nullable: When the current access token expires. Tavus refreshes it automatically while the connector stays `linked`.
  - `last_indexed_at` string, nullable: When tools were last imported from the server. `null` if never indexed.
  - `last_index_error` string, nullable: Why the last import failed, if it did.
  - `created_at` string
  - `updated_at` string
  - `authorize_url` string: Send the customer here to authorize. Present only for `oauth2` connectors.
  - `oauth_state` string: Opaque state for the in-flight authorization. Single-use.

## Other responses

- `400`: Invalid request body
- `424`: OAuth discovery, client registration, or setup against the MCP server failed (`oauth_discovery_failed`, `oauth_registration_failed`, `oauth_setup_failed`). `detail` carries the server's own message.

## Changes

- **2026-11-03** `932c24e63be2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/changes/v2/connectors/post.md)

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) - [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/revisions/60c89a007146?raw)