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, skills, 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. |
PAL capabilities
The five built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory. Prefer these over raw JSON Patch or raw skills: they accept friendly IDs (magic_canvas, slide_presenter, web_search, perception, memory, plus the portal IDs builtin:magic_canvas, builtin:slide_presenter, builtin:web_search, skill:memory) and know that Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL’s skills while Perception persists through layers.perception.
| Tool | Parameters | Description |
|---|
tavus_pal_capability_catalog | — | List the five PAL Maker capabilities and their backend mappings. |
tavus_pal_capabilities_list | pal_id | List Magic Canvas, Slide Presenter, Web Search, Perception, and Memory attachment state and config for a PAL. |
tavus_pal_capability_attach | pal_id, capability_id, config=None, document_ids=None, slides_trigger=None, prompt=None, magic_canvas_components=None, magic_canvas_usage_guidance=None, scheduling_url=None, scheduling_provider=None, perception_model=None, visual_awareness_queries=None, audio_awareness_queries=None, visual_tool_prompt=None, audio_tool_prompt=None | Attach a capability. Options are capability-specific: Slide Presenter uses document_ids/slides_trigger/prompt; Magic Canvas uses magic_canvas_*/scheduling_*; Perception uses perception_model and the visual/audio awareness fields; Web Search and Memory take no config. |
tavus_pal_capability_patch | same as tavus_pal_capability_attach | Update the config of an already-attached capability. |
tavus_pal_capability_detach | pal_id, capability_id | Detach a capability. Perception detaches by setting perception_model: off; the other four detach from /pals/{id}/skills. |
Skills (raw RQH)
Lower-level access to the RQH skill registry and a PAL’s raw skill attachments. Use PAL capabilities for the five PAL Maker capabilities; reach for these only to work with a skill by its raw registry ID.
| Tool | Parameters | Description |
|---|
tavus_skill_list | — | List registered RQH skills/capabilities available to attach to PALs. |
tavus_pal_skills_list | pal_id | List raw RQH skill attachments for a PAL. |
tavus_pal_skill_attach | pal_id, skill_id, config=None | Attach or replace one raw RQH skill on a PAL. |
tavus_pal_skill_patch | pal_id, skill_id, config | Merge config into an already-attached raw RQH skill. |
tavus_pal_skill_detach | pal_id, skill_id | Detach one raw RQH skill from a PAL. |
Knowledge documents
Account-level Knowledge document records that back a PAL’s Knowledge section. With a normal Tavus API key, create documents from an already-reachable URL (tavus_document_create). Local file upload uses the same portal-only path as PAL Maker and requires a locally running MCP server (to read the file) plus TAVUS_PORTAL_BEARER_TOKEN.
| Tool | Parameters | Description |
|---|
tavus_document_list | limit=25, page=0, status=None, tags=None, participant_tags=None, name_or_uuid=None, verbose=True | List Knowledge documents available to attach to PALs. |
tavus_document_get | document_id, verbose=True | Get one Knowledge document record. |
tavus_document_create | document_url, document_name=None, tags=None, participant_tags=None, crawl=None, custom_description=None, is_customer_support_document=False, font_size_aware_extraction=False | Create a Knowledge document from an already-hosted URL. |
tavus_document_upload | local_path, document_name=None, tags=None, participant_tags=None, custom_description=None, is_customer_support_document=False, font_size_aware_extraction=False, bucket_name="developer-portal-documents", region="us-east-1", sign_duration=None | Upload a local file through tavus-api/S3, then create the document record. Requires TAVUS_PORTAL_BEARER_TOKEN. |
tavus_document_tags | search=None, page=None, limit=None | List document tags that can be attached to PAL Knowledge. |
tavus_document_chunks | document_id, collection="regular", limit=100, offset=None | Read the extracted chunks RQH indexed for a document. Use before making claims about a document’s contents. |
tavus_document_recrawl | document_id, crawl=None | Trigger a recrawl for a crawl-backed Knowledge document. |
PAL Knowledge
A PAL’s Knowledge section is its document_ids plus document_tags, with RAG tuning under layers.knowledge_base. Create documents first with the Knowledge documents tools, then attach them here.
| Tool | Parameters | Description |
|---|
tavus_pal_knowledge_list | pal_id | Show Knowledge documents/tags attached to a PAL and resolve the direct document IDs into records. |
tavus_pal_knowledge_add | pal_id, document_ids=None, document_tags=None | Attach existing Knowledge documents or document tags to a PAL. |
tavus_pal_knowledge_remove | pal_id, document_ids=None, document_tags=None | Remove Knowledge documents or document tags from a PAL. |
tavus_pal_knowledge_replace | pal_id, document_ids=None, document_tags=None | Replace the PAL’s Knowledge document/tag selections. |
tavus_pal_knowledge_settings_patch | pal_id, rag_score_threshold=None, rag_n_chunks=None, rag_surrounding_chunk_radius=None, enable_rag_observability_app_messages=None, use_procedure_goalchain=None | Patch RAG tuning settings under layers.knowledge_base. |
tavus_pal_knowledge_upload | pal_id, local_path, document_name=None, tags=None, participant_tags=None, custom_description=None, is_customer_support_document=False, font_size_aware_extraction=False, bucket_name="developer-portal-documents", region="us-east-1", sign_duration=None, attach=True | Upload a local file as a Knowledge document and attach it to the PAL by default. Requires TAVUS_PORTAL_BEARER_TOKEN. |
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. |
