TAtavus
Connectors

Create Connector

Changed on

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

Request

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

Request body

namestring required

Human-readable name, e.g. Linear.

server_urlstring required

The MCP server endpoint.

auth_configobject

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.

Example request

{
  "name": "Linear",
  "server_url": "https://mcp.linear.app/mcp",
  "auth_config": {
    "type": "oauth2"
  }
}

Response

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

connector_idstring

The unique identifier of the connector. Use this everywhere a connector is referenced, including layers.mcp.connectors on a PAL.

owner_idinteger

The account that owns the connector.

team_idinteger nullable

Team the connector belongs to, when applicable.

namestring

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

sourcestring

Connector kind. mcp today.

server_urlstring

The MCP server endpoint.

auth_configobject

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

selected_tool_namesstring[] 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.

oauth_scopesstring[] nullable

Scopes granted by the authorization server.

access_token_expires_atstring nullable

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

last_indexed_atstring nullable

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

last_index_errorstring nullable

Why the last import failed, if it did.

created_atstring
updated_atstring
authorize_urlstring

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

oauth_statestring

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

Example response

{
  "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"
}

Changes