MCP Tools Reference

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.

Tools (PAL tool library)

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.

PAL tools (attach & detach)

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.

See Agentic PAL building & testing for expected agent usage, CLI usage, and how to read the simulated-turn verdict.

Getting started

Build

Deploy

Debug

Guides

Resources

MCP Tools Reference

PAL CRUD & patch

Face

Conversation

Quickstart

Templates

Scaffold

Resource list

Guardrails

Objectives

Tools (PAL tool library)

Pronunciation dictionaries

PAL tools (attach & detach)

PAL capabilities

Skills (raw RQH)

Knowledge documents

PAL Knowledge

Builder

Chat mode (text-only)

PAL preview & build-and-verify

​PAL CRUD & patch

​Face

​Conversation

​Quickstart

​Templates

​Scaffold

​Resource list

​Guardrails

​Objectives

​Tools (PAL tool library)

​Pronunciation dictionaries

​PAL tools (attach & detach)

​PAL capabilities

​Skills (raw RQH)

​Knowledge documents

​PAL Knowledge

​Builder

​Chat mode (text-only)

​PAL preview & build-and-verify

PAL CRUD & patch

Face

Conversation

Quickstart

Templates

Scaffold

Resource list

Guardrails

Objectives

Tools (PAL tool library)

Pronunciation dictionaries

PAL tools (attach & detach)

PAL capabilities

Skills (raw RQH)

Knowledge documents

PAL Knowledge

Builder

Chat mode (text-only)

PAL preview & build-and-verify