The Tavus MCP server exposes the full agentic PAL toolkit to MCP clients. Each tool maps to a Tavus API operation and is callable from any MCP-aware client (for example, Codex or Claude Code). This page is a complete reference of every tool, grouped by category.
For installation and authentication, see the MCP server page. For the equivalent command-line surface, see the CLI. For the autonomous PAL loop, see Agentic PAL building & testing.
Tools are first-class objects, not inlined on the PAL. Before giving a PAL a tool, check the saved library with tavus_tool_list or tavus_describe_pal_options, then either attach an existing tool (tavus_pal_tools_attach) or create a new one (tavus_tool_create) and attach it. Writing tools inline via tavus_patch_pal (layers.*.tools) is deprecated. When you create a tool that overlaps an existing one, the response carries a _tool_reuse_advisory so you can reuse instead.
MCP tools return data plus optional file manifests for the client to handle. They never write files to disk themselves.
PAL CRUD & patch
| Tool | Parameters | Description |
|---|
tavus_pal_list | limit=25, page=0, pal_type=None | List PALs with an optional type filter. |
tavus_pal_get | pal_id, include_settings=False | Fetch a single PAL by ID; optionally include settings. |
tavus_pal_create | system_prompt=None, pal_name="Agentic Tavus PAL", default_face_id=None, pipeline_mode="full", greeting=None, context=None, layers=None, memories=None, objectives_id=None, guardrails_id=None, guardrail_ids=None, guardrail_tags=None, document_ids=None, document_tags=None, is_template=None | Create a PAL. system_prompt is required for pipeline_mode="full". Tools are attached separately after creation. |
tavus_pal_delete | pal_id | Delete a PAL by ID. |
tavus_patch_pal | pal_id, ops | Patch a PAL with JSON Patch operations. Ops that write inline tools (layers.*.tools) return _inline_tools_deprecated steering you to the attach/create flow. |
tavus_describe_pal_options | pal_id | Describe one PAL plus the account resources (guardrails, objectives, documents, tools, voices) that can be attached to it. |
pipeline_mode is one of full (LLM + TTS + STT + perception), speech-to-speech (no LLM), or echo (TTS + transport only).
Face
| Tool | Parameters | Description |
|---|
tavus_face_list | limit=25, stock=False | List faces; when stock=True, filters to system/stock faces only. |
Conversation
| Tool | Parameters | Description |
|---|
tavus_conversation_create | pal_id=None, face_id=None, conversation_name=None | Create a conversation with an optional PAL and face. Returns the conversation object with id and URL. |
tavus_conversation_end | conversation_id | End a conversation by ID. |
Quickstart
| Tool | Parameters | Description |
|---|
tavus_quickstart | system_prompt, pal_name="Agentic Tavus PAL", face_id=None | One-shot recipe: create a PAL, pick a stock face when needed, and create a conversation. Returns the PAL plus the conversation. |
Templates
| Tool | Parameters | Description |
|---|
tavus_pal_from_template | template, pal_name=None, business_context=None, default_face_id=None, layers=None | Create a PAL from a built-in prompt template (customer-support, interviewer, sales, tutor, dev-rel) with optional business context and layer overrides. |
Scaffold
| Tool | Parameters | Description |
|---|
tavus_scaffold_embed | conversation_url, target="iframe", component_name="TavusConversation" | Return starter files for embedding a Tavus conversation URL. target is one of iframe, cvi-ui, vanilla. |
Resource list
| Tool | Parameters | Description |
|---|
tavus_resource_list | resource, limit=25 | List account resources. resource is one of guardrails, objectives, documents, voices, tools (singular aliases accepted). |
Guardrails
Guardrails use a flat, per-rule shape by default (not legacy sets).
| Tool | Parameters | Description |
|---|
tavus_guardrail_list | limit=25, page=1, type="user", name_or_uuid=None, tags=None, legacy=False, verbose=False | List guardrails with optional filtering. type is one of user, system, all. verbose adds persona_refs and guardrail_type. |
tavus_guardrail_get | guardrail_id, verbose=False, legacy=None | Fetch a single guardrail. |
tavus_guardrail_create | guardrail_name, guardrail_prompt, modality="verbal", callback_url="", tool_call=None, app_message=True, tags=None | Create a flat guardrail with optional callback and tool-call payload. modality is one of verbal, visual, audio. |
tavus_guardrail_patch | guardrail_id, guardrail_name=None, guardrail_prompt=None, modality=None, callback_url=None, tool_call=None, app_message=None, tags=None | Update a guardrail. Omit fields to leave them unchanged; each supplied field is replaced whole. |
tavus_guardrail_delete | guardrail_id | Delete a guardrail by ID. |
tavus_guardrail_tags | search=None, page=None, limit=None | List tags applied to the account’s guardrails. |
Objectives
Objectives are stored as sets; PALs reference a set by objectives_id.
| Tool | Parameters | Description |
|---|
tavus_objective_list | limit=25, page=1, type="user", name_or_uuid=None, sort="ascending" | List objective sets. type is one of user, system, all. |
tavus_objective_get | objectives_id | Fetch a single objective set. |
tavus_objective_create | data, name="", allow_loops=False | Create an objective set. Each item has objective_name (letters/digits/underscores only), objective_prompt, optional confirmation_mode (“auto”|“manual”), modality (“verbal”|“visual”|“audio”), output_variables, callback_url, tool_call, and chains via next_required_objective or next_conditional_objectives (not both). When allow_loops=False, exactly one item must be root. |
tavus_objective_patch | objectives_id, ops | Patch an objective set with JSON Patch ops; cycle and single-root validation re-runs. |
tavus_objective_delete | objectives_id | Delete an objective set by ID. |
tavus_objective_validate | data, name="", allow_loops=False | Validate an objective-set payload (cycles, single root, references) without persisting. |
| Tool | Parameters | Description |
|---|
tavus_tool_list | limit=25, page=1, type="user", name_or_uuid=None, sort="ascending" | List tools. type filters by ownership (user, system, all). |
tavus_tool_get | tool_id | Fetch a single tool by ID. |
tavus_tool_create | name, description, parameters=None, delivery=None, origin="llm", on_call=None, on_resolve="fire_and_forget", static_filler=None | Create a tool. Placeholders {ident} in url/body/query must be declared in parameters.properties. Description plus parameters JSON must total ≤ 10,000 chars. Returns _tool_reuse_advisory if similar tools exist. For post-call actions, use the CLI tool create --file or Tools API with trigger_type: "post_call" (not yet a parameter on this MCP tool). |
tavus_tool_patch | tool_id, name=None, description=None, parameters=None, delivery=None, origin=None, on_call=None, on_resolve=None, static_filler=None | Update a tool. Omit fields to leave them unchanged. Secrets returned scrubbed (********) from a prior GET must be omitted, not re-sent. |
tavus_tool_delete | tool_id | Delete a tool by ID. |
delivery defaults to {"app_message": true} (Daily data channel), or use {"api": {...}} for HTTPS calls with headers, query params, body template, content type, timeout (default 10s, max 60s), and auth (none, bearer, basic, api_key, hmac, oauth2_client_credentials).
Pronunciation dictionaries
Pronunciation dictionaries are referenced from PALs via layers.tts.pronunciation_dictionary_id.
| Tool | Parameters | Description |
|---|
tavus_pronunciation_dictionary_list | limit=25, page=0, sort="desc" | List pronunciation dictionaries. |
tavus_pronunciation_dictionary_get | dictionary_id | Fetch a single pronunciation dictionary. |
tavus_pronunciation_dictionary_create | name, rules=None | Create a dictionary. Each rule is {text, pronunciation, type: "alias"|"ipa", alphabet?, case_sensitive?, word_boundaries?}; max 10,000 rules. Text values must be unique. |
tavus_pronunciation_dictionary_patch | dictionary_id, name=None, rules=None | Update a dictionary. Supplying rules replaces the full list (no merge). |
tavus_pronunciation_dictionary_delete | dictionary_id | Delete a dictionary by ID. |
| Tool | Parameters | Description |
|---|
tavus_pal_tools_list | pal_id | List tools currently attached to a PAL. |
tavus_pal_tools_attach | pal_id, tool_ids | Attach one or more existing tools to a PAL by ID. A PAL can hold up to 50 tools. If any attached tool is vision/audio, the PAL’s perception_model auto-bumps to raven-1 (response carries _perception_model_bumped_to_raven_1). |
tavus_pal_tools_detach | pal_id, tool_id | Detach a single tool from a PAL. |
Builder
The builder is an LLM-guided PAL creation flow.
| Tool | Parameters | Description |
|---|
tavus_builder_create | name, greeting=None, pal_id=None, model=None | Create a builder session, optionally based on an existing PAL. |
tavus_builder_list | limit=None, page=None, pal_id=None, name=None, status=None | List builder sessions with optional filters. |
tavus_builder_get | builder_id | Fetch a single builder by ID. |
tavus_builder_delete | builder_id | Delete a builder session. |
tavus_builder_chat | builder_id, message | Send a chat turn to the builder. Returns assistant text, autocomplete suggestions, a draft_ready flag, and target sections for scoped updates. |
tavus_builder_chat_history | builder_id, limit=50 | Fetch chat history for a builder session. |
tavus_builder_append_messages | builder_id, messages | Append messages to builder chat history. |
tavus_builder_update_objectives | builder_id, message | Update objectives based on a user feedback message. |
tavus_builder_update_guardrails | builder_id, message | Update guardrails based on a user feedback message. |
tavus_builder_update_greeting | builder_id, message | Update the greeting/opening based on feedback. |
tavus_builder_update_personality | builder_id, message, pal_name=False, system_prompt=False | Update PAL personality/system prompt based on feedback. Optionally include PAL name and/or system prompt fields. |
tavus_builder_publish | builder_id | Publish the builder’s drafted PAL. |
Chat mode (text-only)
| Tool | Parameters | Description |
|---|
tavus_chat_start | pal_id, custom_greeting=None, conversation_name=None | Start a text-only conversation with a PAL. Use this to test a built PAL by sending typed turns; no face video is rendered. |
tavus_chat_turn | conversation_id, text, timeout_s=20.0 | Send one user turn and wait for the PAL’s reply. Returns {text: <reply>}. |
tavus_chat_end | conversation_id | End a chat-mode conversation. |
PAL preview & build-and-verify
| Tool | Parameters | Description |
|---|
tavus_pal_preview | pal_id, face_id=None, conversation_name=None | Start a full audio/video preview conversation against a PAL and return {conversation_id, conversation_url, ...}. Hand the URL to a human for visual verification. |
tavus_pal_build_and_verify | prompt, face_id=None, max_rounds=4, answers=None | Build a PAL from one creator prompt (optionally using supplied answers for builder follow-ups), then publish and validate via CVI chat mode. When face_id is omitted, a default is selected and attached. |
