Create Connector

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; the in-call agent connects to the server and discovers its tools itself, so there is nothing to import.

POST /v2/connectors

cURL

OAuth server

curl --request POST \
  --url https://tavusapi.com/v2/connectors \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Linear",
  "server_url": "https://mcp.linear.app/mcp",
  "auth_config": {
    "type": "oauth2"
  }
}
'

200

{
  "connector_id": "c8-58ea0f6420b2",
  "owner_id": 4309,
  "team_id": null,
  "name": "Linear",
  "source": "mcp",
  "server_url": "https://mcp.linear.app/mcp",
  "auth_config": {
    "type": "oauth2"
  },
  "selected_tool_names": null,
  "oauth_status": "linked",
  "oauth_scopes": [
    "read",
    "write"
  ],
  "access_token_expires_at": "2026-08-18T09:14:00",
  "last_indexed_at": "2026-08-17T18:20:11",
  "last_index_error": null,
  "created_at": "2026-08-17T18:02:56.838918",
  "updated_at": "2026-08-17T18:20:11.563911"
}

Authorizations

x-api-key · string · header · required

Body

application/json

name · string · required

Human-readable name, e.g. Linear.

Example:

"Linear"

server_url · string · required

The MCP server endpoint.

Example:

"https://mcp.linear.app/mcp"

auth_config · object

How Tavus authenticates to the server. Defaults to { "type": "none" }.

• { "type": "none" } - public server.
• { "type": "bearer", "token": "..." } - static bearer token.
• { "type": "oauth2" } - Tavus runs the OAuth flow; the response carries authorize_url.

Secrets are encrypted at rest and never returned.

Example:

{ "type": "oauth2" }

Response

200

application/json

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

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.

Example:

"c8-58ea0f6420b2"

owner_id · integer

The account that owns the connector.

Example:

4309

team_id · integer | null

Team the connector belongs to, when applicable.

Example:

null

name · string

Human-readable name. Also the basis of the label the background agent sees for this service.

Example:

"Linear"

source · string

Connector kind. mcp today.

Example:

"mcp"

server_url · string

The MCP server endpoint.

Example:

"https://mcp.linear.app/mcp"

auth_config · object

How Tavus authenticates to the server, with secrets removed. See the create request for the accepted shapes.

Example:

{ "type": "oauth2" }

selected_tool_names · string[] | null · deprecated

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.

Example:

null

oauth_status · enum<string>

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.

Available options: none, pending, linked, needs_reauth

Example:

"linked"

oauth_scopes · string[] | null

Scopes granted by the authorization server.

Example:

["read", "write"]

access_token_expires_at · string | null

When the current access token expires. Tavus refreshes it automatically while the connector stays linked.

Example:

"2026-08-18T09:14:00"

last_indexed_at · string | null

When tools were last imported from the server. null if never indexed.

Example:

"2026-08-17T18:20:11"

last_index_error · string | null

Why the last import failed, if it did.

Example:

null

created_at · string

Example:

"2026-08-17T18:02:56.838918"

updated_at · string

Example:

"2026-08-17T18:20:11.563911"

authorize_url · string

Send the customer here to authorize. Present only for oauth2 connectors.

Example:

"https://mcp.linear.app/authorize?response_type=code&client_id=..."

oauth_state · string

Opaque state for the in-flight authorization. Single-use.

Example:

"wA0meZRQKOwa4wHxcN27xt3eYfII0hLs"