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"
}
}
'{
"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"
}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.
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"
}
}
'{
"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
Body
Human-readable name, e.g. Linear.
"Linear"
The MCP server endpoint.
"https://mcp.linear.app/mcp"
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 carriesauthorize_url.
Secrets are encrypted at rest and never returned.
{ "type": "oauth2" }
Response
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.
The unique identifier of the connector. Use this everywhere a connector is referenced, including layers.mcp.connectors on a PAL.
"c8-58ea0f6420b2"
The account that owns the connector.
4309
Team the connector belongs to, when applicable.
null
Human-readable name. Also the basis of the label the background agent sees for this service.
"Linear"
Connector kind. mcp today.
"mcp"
The MCP server endpoint.
"https://mcp.linear.app/mcp"
How Tavus authenticates to the server, with secrets removed. See the create request for the accepted shapes.
{ "type": "oauth2" }
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.
null
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.
none, pending, linked, needs_reauth "linked"
Scopes granted by the authorization server.
["read", "write"]
When the current access token expires. Tavus refreshes it automatically while the connector stays linked.
"2026-08-18T09:14:00"
When tools were last imported from the server. null if never indexed.
"2026-08-17T18:20:11"
Why the last import failed, if it did.
null
"2026-08-17T18:02:56.838918"
"2026-08-17T18:20:11.563911"
Send the customer here to authorize. Present only for oauth2 connectors.
"https://mcp.linear.app/authorize?response_type=code&client_id=..."
Opaque state for the in-flight authorization. Single-use.
"wA0meZRQKOwa4wHxcN27xt3eYfII0hLs"