MCP Server

The Tavus MCP server is a hosted endpoint your coding agent connects to. Once it is wired into Codex, Claude Code, Cursor, or another MCP client, your agent can build and patch a PAL, define the tools that PAL can call, attach them, and start test conversations, all from your editor against your own codebase. There is nothing to install or run. You connect over HTTPS and authenticate once in the browser.

Why connect your editor

A working voice agent has two parts that have to agree:

The PAL needs to know which tools exist and when to call them. That lives in the PAL’s tool definitions and prompt.
Your application needs to handle those calls when they fire. That lives in your code.

Keeping those two parts in sync by hand is where integrations drift. The MCP server lets one agent work both sides: it defines the tool on the PAL and can scaffold and check the matching handler in your repo, so the two stay consistent. You then test the exchange by starting a conversation and watching the tool fire and your handler respond, without leaving your editor.

Develop the PAL

Create and patch the PAL’s layers, prompt, guardrails, and objectives.

Wire tool calls

Define tools, attach them, and generate the handler code in your own app.

Test the integration

Start chat or full conversations and watch tool calls round-trip live.

Connect a client

The server is reachable at an HTTPS /mcp endpoint. Authentication uses a browser-based OAuth flow: the PAL Maker mints a per-user API key and the server forwards it to the Tavus API as x-api-key. No key or shared token sits in your client config.

Production

https://mcp.tavus.io/mcp (custom domain).

Preview

https://mcp.tavus-preview.io/mcp (Cloudflare-owned domain).

Step 1: Add the server

Point your MCP client at the hosted endpoint.For Codex:

codex mcp add tavus --url https://mcp.tavus-preview.io/mcp

For Claude Code:

claude mcp add -s user --transport http tavus https://mcp.tavus-preview.io/mcp

This registers the server under the name tavus for your user scope.

Never put a Tavus API key or shared bearer token in your MCP client config. The hosted server authenticates each user through the PAL Maker and keeps keys user-scoped and out of client configuration.

Step 2: Authenticate in the browser

On first use, the client runs an OAuth flow against the server. For Codex, you can start it directly:

codex mcp login tavus

Then the flow is:

The client initiates the authorize flow.
The portal redirects to /dev/cli-authorize?mode=oauth.
You sign in.
The portal mints a per-user Tavus API key.
You are redirected back to the client’s loopback callback.
The server exchanges the authorization code and forwards the minted key to the Tavus API as x-api-key on every downstream call.

Step 3: Drive Tavus from your agent

Once authenticated, the full Tavus toolset is available: PAL CRUD, faces, conversations, builder, chat-mode testing, guardrails, objectives, tools, pronunciation dictionaries, built-in PAL Maker capabilities (Magic Canvas, Slide Presenter, Web Search, Perception, Memory), and Knowledge documents. See Agentic PAL building & testing for the autonomous PAL loop, or the MCP tools reference for the full catalog.

MCP tools return data and file manifests. They do not write files themselves. Your client decides what to do with the returned data, such as writing a generated tool handler into your repo.

Bidirectional tool calls

A tool call in Tavus is an exchange, and that exchange is what connects the PAL to your app:

During a conversation the PAL decides a tool is needed, based on the tool’s description and the PAL’s prompt, and calls it with arguments.
Tavus delivers that call to your code.
Your code runs its logic and returns a result.
The PAL uses the result to decide what to say and do next.

The PAL calls into your application in steps 1 and 2, and your application’s response shapes the PAL’s next turn in steps 3 and 4.

Two delivery channels

A tool’s delivery field sets where the call is delivered. It is the main choice you make when you define a tool.

To your client (app_message)
To your backend (api webhook)

"delivery": { "app_message": true }

The call is emitted to your frontend or client over the conversation’s data channel as a tool-call event. Your app listens for it and runs local logic.Best for actions in the UI: highlight a product, change a slide, navigate a page, or update on-screen state. This is also the default channel for LLM tool calling.

"delivery": {
  "api": {
    "url": "https://your-app.example.com/api/tools/get_order_status",
    "method": "POST",
    "content_type": "application/json",
    "body_template": { "order_id": "{order_id}" },
    "timeout": 10.0
  }
}

Tavus makes a direct HTTPS call to your backend and waits for the JSON response. Best for server-side work such as database lookups, business logic, and third-party APIs.The HTTP form also supports headers, query_params, and auth (none, bearer, basic, api_key, hmac, or oauth2_client_credentials). timeout defaults to 10 seconds (max 60).

Any {placeholder} used in url, body_template, or query_params must be declared as a property in the tool’s parameters.properties. The tool’s description plus parameters JSON must total 10,000 characters or fewer.

Controlling what the PAL does around the call

Two fields shape the conversational behavior of the exchange:

Field	Common values	What it does
`on_call`	`silent`	What the PAL does while the tool runs, for example staying silent instead of narrating the call.
`on_resolve`	`generate_response`, `fire_and_forget`	What happens after the result returns. `generate_response` has the PAL speak based on the result. `fire_and_forget` (the default) does not wait or narrate.
`static_filler`	any string	A line to say while waiting on a slow tool.

Use on_resolve: generate_response when the result should change what the PAL says next, such as an order status or an availability check. Use fire_and_forget for side effects the PAL does not need to react to.

A complete example

A backend lookup the PAL can call to answer “where’s my order?”:

get_order_status tool

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer's order. Call this when the user asks about the state, location, or delivery date of an order they reference by number. The result tells you the status and the estimated delivery date so you can relay it.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order number the customer gave, e.g. 'A-10428'."
      }
    },
    "required": ["order_id"]
  },
  "delivery": {
    "api": {
      "url": "https://your-app.example.com/api/tools/get_order_status",
      "method": "POST",
      "content_type": "application/json",
      "body_template": { "order_id": "{order_id}" },
      "timeout": 10.0
    }
  },
  "origin": "llm",
  "on_call": "silent",
  "on_resolve": "generate_response"
}

When the PAL calls it, Tavus POSTs { "order_id": "A-10428" } to your endpoint. Your handler returns JSON, for example:

{ "status": "out_for_delivery", "eta": "today by 6pm" }

Because on_resolve is generate_response, the PAL speaks from that result, for example: “Good news, order A-10428 is out for delivery and should arrive today by 6pm.”

Build and test it with your agent

One agent can do every step above. A typical loop:

Define the tool. The agent calls tavus_tool_create with the parameters and delivery that match what the tool should do.
Attach it. tavus_pal_tools_attach wires the tool onto your PAL so it is offered during conversations.
Write the handler. For an api tool, the agent scaffolds the matching endpoint in your repo (the route at delivery.api.url) so the request and response shape match the tool’s parameters.
Test the exchange. tavus_chat_start and tavus_chat_turn (text only), or tavus_conversation_create (full video), start a session so you can watch the tool fire and your handler respond, then iterate.

For a new PAL, an agent can run this as one autonomous build, simulated-turn test, and judge pass with tavus_pal_build_and_verify. See Agentic PAL building & testing.

The server flags a likely duplicate when you create a tool that resembles one you already have, so your agent can attach the existing tool instead. Prefer attaching saved tools over redefining them inline. See the MCP tools reference for tavus_tool_list, tavus_tool_create, and tavus_pal_tools_attach.

Built-in capabilities

Custom tools are one way to extend a PAL. The other is the set of built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory - which the server exposes through friendly, portal-aligned tools so your agent turns them on the same way PAL Maker does:

tavus_pal_capability_catalog lists the five capabilities and their backend mappings.
tavus_pal_capabilities_list shows what is attached to a PAL and its config.
tavus_pal_capability_attach / tavus_pal_capability_patch / tavus_pal_capability_detach manage them by friendly ID (magic_canvas, slide_presenter, web_search, perception, memory).

Prefer these over raw JSON Patch: the server knows that Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL’s skills (/pals/{id}/skills) while Perception persists through layers.perception. For skills that are not one of the five capabilities, the raw tavus_skill_list and tavus_pal_skill_* tools work with a skill by its registry ID.

Knowledge

Give a PAL documents to ground its answers with the Knowledge tools. This is a two-step flow that mirrors PAL Maker’s Knowledge section:

Create the document. tavus_document_create ingests an already-hosted URL with a normal Tavus API key. To upload a local file, tavus_document_upload runs the portal path (local file → tavus-api upload/S3 URL → document record) and needs a locally running MCP server plus TAVUS_PORTAL_BEARER_TOKEN.
Attach it. tavus_pal_knowledge_add (or _replace) wires documents and document tags onto the PAL. tavus_pal_knowledge_settings_patch tunes RAG behavior under layers.knowledge_base, and tavus_pal_knowledge_upload does the upload-and-attach in one call.

Use tavus_document_chunks to inspect the text RQH actually indexed for a document before relying on it - it returns the ingested chunks, not the source file. See the MCP tools reference for the full capability, skill, and Knowledge catalogs.

Environment alignment

The server must run in the same environment as the portal that minted your key.

A TEST key authenticated against a production server, or the reverse, makes downstream Tavus API calls return 401. Keep the endpoint and the portal you sign in to on the same environment.

Troubleshooting the connection

The server exposes standard OAuth discovery metadata you can inspect directly:

curl https://mcp.tavus-preview.io/.well-known/oauth-protected-resource/mcp
curl https://mcp.tavus-preview.io/.well-known/oauth-authorization-server
curl -i https://mcp.tavus-preview.io/mcp

An unauthenticated /mcp request should return 401 with a WWW-Authenticate header pointing at the protected-resource metadata URL. If that header or the discovery endpoints are missing, the OAuth flow cannot complete. Re-add the server and retry the browser sign-in.

Getting started

Build

Deploy

Debug

Guides

Resources

Why connect your editor

Develop the PAL

Wire tool calls

Test the integration

Connect a client

Production

Preview

Bidirectional tool calls

Two delivery channels

Controlling what the PAL does around the call

A complete example

Build and test it with your agent

Built-in capabilities

Knowledge

Environment alignment

Troubleshooting the connection

​Why connect your editor

Develop the PAL

Wire tool calls

Test the integration

​Connect a client

Production

Preview

​Bidirectional tool calls

​Two delivery channels

​Controlling what the PAL does around the call

​A complete example

​Build and test it with your agent

​Built-in capabilities

​Knowledge

​Environment alignment

​Troubleshooting the connection

Why connect your editor

Connect a client

Bidirectional tool calls

Two delivery channels

Controlling what the PAL does around the call

A complete example

Build and test it with your agent

Built-in capabilities

Knowledge

Environment alignment

Troubleshooting the connection