Tavus CLI & MCP

Agent-facing surfaces for building and managing Tavus PALs. PAL Maker is the human, in-product builder; this toolkit lets an agent (Claude, Codex, or any MCP-aware client) drive the same platform through the API:

• MCP server. The full PAL surface as MCP tools: the guided build (tavus_pal_build_and_verify), chat-mode text testing, and CRUD for PALs, tools, knowledge, guardrails, objectives, pronunciation dictionaries, capabilities, faces, and voices, plus deployments that put a PAL on a landing page, an embed or a widget. Run it locally over stdio, or connect to the hosted server at https://mcp.tavus.io/mcp.
• tavus CLI. The same surface as shell commands, published to PyPI as tavus-cli. Scripted PAL authoring and publishing, JSON round-tripping, browser login with OS-keychain storage.
• Codex skill. A publishable skill in skills/tavus-agentic-pals/ that teaches an external agent both surfaces without reading the full Tavus API.

The Tavus API exposes /v2/pals and /v2/faces as backwards-compatible aliases over /v2/personas and /v2/replicas. Everything in this repo speaks the pal/face vocabulary.

Hosted MCP server

The fastest way to use this toolkit is the hosted connector. Point any MCP client at https://mcp.tavus.io/mcp:

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

Claude.ai and ChatGPT custom connectors use the same URL. Do not put a Tavus API key or shared bearer token in client config: the Worker exposes standard OAuth metadata and dynamic client registration, so the client sends you through Tavus browser sign-in. The developer portal mints a per-user API key; the Worker keeps it encrypted server-side and issues expiring OAuth tokens. The API key never appears in client configuration or browser callback URLs.

Dynamic client registration accepts loopback callbacks from any local client (Claude Code, Codex, Gemini CLI) and the hosted callbacks of Claude, ChatGPT, Cursor, VS Code, v0, Vercel Connect, Lovable, Bolt and Replit. They are listed in KNOWN_REMOTE_CLIENTS in workers/tavus-mcp/src/oauth.ts. To add a client, press Connect in it once, read its callback from the Worker's oauth_register_rejected log line, and add an entry with a test. Clients that don't use dynamic registration, such as Gemini Enterprise, get a client ID and secret through the MCP_OAUTH_CLIENTS secret, with their callback in redirect_uris (for Gemini Enterprise, https://vertexaisearch.cloud.google.com/oauth-redirect).

PROMPT.md is the prompt for coding agents working with Tavus through this server. Paste it into Claude Code, Codex or Cursor: it gets the client connected, asks what the user wants to build, and states the contracts for building, changing and testing a PAL and wiring its tools into the user's code. Put a known PAL id or tool list above it and the agent will not ask for them. When the user wants the PAL in front of people, the agent suggests a landing page, embed or widget from the project, creates the deployment with tavus_deployment_create, and either shares the landing page link or hands off to the embed or widget prompt in tavus-examples (examples/embed-prompt.md, examples/widget-prompt.md) with the deployment id and the PAL's page tools already filled in.

ChatGPT plugin

plugins/tavus-pal/ packages this same hosted server as Tavus PAL for ChatGPT and Codex. It adds listing metadata and Tavus icons; tools and account authorization continue to live in the Worker. Build the uploadable ZIP with:

python scripts/build_chatgpt_plugin.py

The repository marketplace is .agents/plugins/marketplace.json. See ChatGPT setup and release guide for installation, authentication, migration, and directory submission.

Local MCP server

For IDE-embedded clients, run the stdio server from a checkout:

{
  "mcpServers": {
    "tavus": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/tavus-mcp", "tavus-mcp"]
    }
  }
}

Or from PyPI without a checkout: uvx --from 'tavus-cli[daily]' tavus-mcp.

MCP tools return data and file manifests. They do not write files.

Building a PAL

The standard way to build a PAL is tavus_pal_build_and_verify (MCP) or tavus pal build (CLI). It runs the guided PAL Maker build: it creates the artifact set (sectioned system prompt, objectives, guardrails, and greeting), publishes the PAL, selects a face, runs a CVI chat smoke test, and returns a judge verdict. Creation responses include pal_url, a direct link to the PAL Maker editor for that environment (maker.tavus.io in production).

The transport differs by surface. The CLI and local MCP server drive the builder conversation by joining its Daily room from your machine, which needs the daily extra (see Setup below). On the hosted connector, the calling agent interviews the creator itself, then passes the transcript and artifact briefs to the Worker, which runs the rest of the flow over Tavus HTTP endpoints. tavus_chat_turn works the same way on both surfaces: Daily locally, the Tavus HTTP bridge when hosted.

Defaults and constraints:

• Full-pipeline builds default to the tavus-gemma-4 model with speculative inference enabled.
• Tools are first-class /v2/tools resources and attach through top-level tool_ids or tavus_pal_tools_attach. Inline layers.llm.tools and perception tool arrays are rejected by both the MCP server and the CLI.
• Reserve raw tavus_pal_create for deliberate low-level use.

Inviting a PAL to Google Meet

Use tavus_meeting_configure with pal_id and the creator's exact wake_phrase and sleep_phrase. It creates a missing conferencing identity, preserves existing access restrictions, and reads back the settings. Omitted phrases stay unchanged. Wake and sleep phrases are runtime settings; do not put them in build briefs.

Ask for the meeting link, then call tavus_conversation_create with pal_id and meeting_url. This tool also accepts the two phrases and checks setup before sending the invitation. The PAL needs a default face, or you can supply face_id. Configuration readback and text tests do not prove spoken wake/sleep behavior. Check admission and audio behavior in the live meeting.

CLI

Install from PyPI, or run without installing:

uv tool install tavus-cli
uvx --from tavus-cli tavus doctor

The tavus and tavus-mcp names on PyPI are official alias packages (packages/) that only depend on tavus-cli; every release publishes all three at the same version.

Sign in with tavus auth login. It opens the developer portal at /dev/cli-authorize with a loopback callback; the portal mints an API key for your signed-in user and the CLI stores it in the OS keychain, per environment. For automation, set TAVUS_API_KEY instead — it wins over the keychain.

Command groups:

Examples:

tavus doctor
tavus pal build --prompt "A patient SQL tutor for junior analysts" --json
tavus chat start --pal-id p123
tavus chat turn c123 --message "What can you help me with?"
tavus chat end c123
tavus pal list
tavus pal options <pal_id>
tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
tavus pal capabilities list <pal_id>
tavus pal capabilities attach <pal_id> web_search
tavus pal capabilities attach <pal_id> slide_presenter --document-id <document_id> --slides-trigger walk_the_deck
tavus document create --url https://example.com/handbook.pdf --tag onboarding
tavus pal knowledge add <pal_id> --document-id <document_id>

pal capabilities mirrors PAL Maker's built-in capability surface: Magic Canvas (magic_canvas), Slide Presenter (slide_presenter), Web Search (web_search), Perception (perception), and Memory (memory). All but Perception map to platform PAL skills; Perception maps to layers.perception.

document and pal knowledge mirror PAL Maker's Knowledge section. With a normal Tavus API key you can create Knowledge documents from any reachable URL. Uploading a local file (tavus document upload, tavus pal knowledge upload) uses the same portal-only flow as PAL Maker, so it also requires TAVUS_PORTAL_BEARER_TOKEN (a Firebase ID token). PAL Knowledge attachment uses document_ids and document_tags; RAG tuning lives under layers.knowledge_base.

Environments

The CLI and local MCP server target production (PROD) by default. Switch with TAVUS_ENV=TEST (or STG) in .env / your shell, or --env TEST on the CLI:

# Production defaults; only the API key is required.
TAVUS_API_KEY=... tavus pal list

# Test DB without URL overrides.
TAVUS_ENV=TEST TAVUS_API_KEY=... tavus pal list
tavus --env TEST pal list

.env.example documents the per-environment URL defaults and the optional overrides (TAVUS_PUBLIC_API_BASE_URL, TAVUS_PAL_MAKER_URL, and friends). Explicit URLs always win over the environment defaults.

Codex skill

A publishable Codex skill lives at skills/tavus-agentic-pals/. It documents the CLI and MCP workflows, safe PAL patching, environment setup, and concrete examples. Install it by copying the folder into ${CODEX_HOME:-$HOME/.codex}/skills/, or publish it through your own skill distribution flow.

Development

Setup

uv sync --extra dev
cp .env.example .env
uv run tavus doctor --skip-network

Chat mode and the guided build join the conversation's Daily room from this machine, which needs the daily extra:

uv sync --extra dev --extra daily

uv sync installs only the extras named on that run, so list every extra you need together. daily-python ships macOS/Linux wheels only. The hosted connector uses the Tavus HTTP bridge and does not need a local Daily client.

Checks, all run by CI on every pull request:

uv run ruff check .
uv run pytest -q
cd workers/tavus-mcp && npm run build && npm test

Worker development

The hosted MCP server is a Cloudflare Worker in workers/tavus-mcp/ (configured in wrangler.jsonc) using the stateless createMcpHandler transport at /mcp.

cd workers/tavus-mcp
npm install
cp .dev.vars.example .dev.vars
npm run dev

The local endpoint is http://127.0.0.1:8787/mcp. To test the full browser-auth path against TEST with a local developer portal on port 3000:

npm run dev -- --env test --var TAVUS_DEV_PORTAL_URL:http://localhost:3000

claude mcp add -s user --transport http tavus-dev http://127.0.0.1:8787/mcp

Keep the Worker environment aligned with the portal environment that minted the key: a TEST key must hit a Worker running with --env test, otherwise downstream Tavus API calls return 401. Direct Wrangler commands default to production; use --env test to point at TEST.

The public endpoint is always https://mcp.tavus.io/mcp. mcp.tavus-preview.io belongs only to the stg Worker and must not be published as a production fallback.

How hosted OAuth works

The authorize step redirects to the developer portal at /dev/cli-authorize?mode=oauth. The portal verifies the Worker's signed request, shows the connector destination, and after sign-in posts a per-user API key to the Worker's trusted /oauth/callback. The Worker issues an short-lived authorization code, verifies PKCE plus the registered client, redirect, and MCP resource at /token, and issues a 15-minute opaque access token and rotating refresh token. The account API key stays encrypted in a SQLite-backed Durable Object; only token hashes are stored. Each MCP request validates the token's resource, scope, and expiry before using the linked key. Authorization requests and codes remain one-time grants.

Sessions do not expire. A session ends when POST /revoke revokes it, or when a refresh token is reused more than 60 seconds after its first use. A reuse within 60 seconds, such as a retry or two concurrent refreshes, gets new tokens. A Tavus API key sent directly as the bearer token still works, so connections made before OAuth sessions existed keep working. Native CLI sign-in is unchanged. See migration and rollout before deploying.

Local and hosted parity

Every remotely usable Tavus feature must land in the Python MCP server/CLI and the hosted Worker in the same change. A parity test compares both tool manifests and fails CI when a new difference is not explicitly classified. The current documented exceptions are local-file uploads, the builder-session administration tools, and two tools that keep backward-compatible local names (tavus_pal_capability_catalog / tavus_pal_knowledge_settings_patch locally; tavus_pal_capabilities_catalog / tavus_pal_knowledge_settings hosted).

Both servers load their builder instructions and capability-selection guidance from builder_guidance.json. These rules adapt Charlie's builder prompt to the MCP tools, including using Magic Canvas for on-screen scorecards instead of creating a saved tool. See maintaining builder guidance for the source and behavior checks.

Deploys and releases

Merges to main automatically build, test, deploy, and smoke-test the stg Worker. The deploy workflow can also target test or stg manually; it cannot deploy production. After a feature merge, confirm the staging connector still completes a real OAuth login and the feature's write/read/cleanup cycle; repeat that smoke test at mcp.tavus.io after the release ships.

Release Please keeps one version for the CLI and the hosted Worker. It opens or updates a release pull request after each non-release merge to main. Merging that pull request creates the GitHub release and starts the release workflow, which validates the tag (versions consistent across both packages, only release files changed, parent commit successfully staged), builds both deliverables from the exact tag, and waits for the prod environment approval. One approved job then deploys the Worker, smoke-tests https://mcp.tavus.io, and publishes the same version of tavus-cli to PyPI. A manual release run accepts only an existing GitHub release tag and is the recovery path for a failed production job.

Secrets:

• GitHub environment secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID for each deployable environment (test, stg, prod).
• Worker runtime secrets are set with npx wrangler secret put <NAME> --env <environment> and persist across deploys; the workflows never read or overwrite them. Every deployed environment needs MCP_OAUTH_SIGNING_SECRET (random, at least 32 characters, different per environment, never committed). The legacy TAVUS_API_KEY / MCP_BEARER_TOKEN fallback is also a runtime secret.

Production checks:

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

Unauthenticated /mcp should return 401 with a WWW-Authenticate header pointing at the protected-resource metadata URL. A 404 at discovery usually means the Worker serving the domain predates the OAuth routes.

More docs

• docs/usage-observability.md — how MCP and CLI API usage is attributed and observed.
• docs/gemini-enterprise/ — Gemini Enterprise marketplace listing copy.