tavus-cli 0.1.0

Tavus CLI and MCP server for agentic persona creation and editing.

tavus-cli

Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.

What's here

• MCP server. Persona CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
• CLI. Scripted persona authoring + publish. tavus persona list / options / patch, JSON round-tripping, OS-keychain auth.
• Codex skill. Publishable skill so an external agent can invoke the MCP server and CLI without reading the full Tavus API.

Why standalone (not under Conversational Persona Builder)

The CPB project is the human builder — replica-driven, in-product. This repo is for agents driving the API without that UI. Adjacent in code and concepts, but a different deliverable and audience.

Out of scope (for now)

• Replica/video preview surfaces (lives in CPB)
• Marketplace / sharing UX
• Multi-tenant auth beyond the existing dev-portal token model

Local Setup

uv sync --extra dev
cp .env.example .env

By default the CLI targets production (PROD). To switch to the test DB, either set TAVUS_ENV=TEST in .env / your shell or pass --env TEST to the CLI. You can set TAVUS_API_KEY directly for automation or run:

uv run tavus auth login

Examples:

# Production defaults; only the API key is required.
TAVUS_API_KEY=... uv run tavus persona list

# Test DB without URL overrides.
TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
uv run tavus --env TEST persona list

The login flow opens the dev-portal at /dev/cli-authorize with a loopback callback URL and an anti-CSRF state. The dev-portal mints an API key for your signed-in user (tagged source: cli) and POSTs it back to the loopback receiver. The CLI stores that key in the OS keychain under the selected environment. No Firebase config lives in the CLI — the browser side handles all of it.

CLI

Install the CLI from PyPI:

uv tool install tavus-cli

Or run it without installing:

uvx --from tavus-cli tavus doctor

Local development commands:

uv run tavus doctor
uv run tavus persona list
uv run tavus persona options <persona_id>
uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'

MCP

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

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

Cloudflare Worker

The remote MCP server lives in workers/tavus-mcp/ and uses Cloudflare's stateless createMcpHandler transport at /mcp.

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

The local remote-MCP endpoint is http://127.0.0.1:8787/mcp.

Hosted remote MCP

Hosted remote MCP clients should point directly at the HTTPS /mcp URL. Do not put a Tavus API key or shared bearer token in client config. The Worker exposes standard OAuth metadata, dynamic client registration, authorize, and token endpoints so MCP clients can authenticate through Tavus browser auth.

Claude Code example:

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

The OAuth authorize step redirects to Tavus developer portal /dev/cli-authorize?mode=oauth. After the user signs in, the portal mints a per-user Tavus API key and redirects back to the MCP client's loopback callback. The Worker exchanges that code for an MCP bearer token, then forwards the bearer to RQH as x-api-key. This keeps Tavus API keys user-scoped and out of MCP client configuration.

Developer portal must support the mode=oauth authorize flow for remote MCP auth to complete. If a local portal is running on port 3000, test the full browser-auth path against TEST with:

cd workers/tavus-mcp
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. For example, a TEST key from a local or dev portal must hit a Worker running with --env test, otherwise downstream Tavus API calls will return 401.

For Tavus deployment, configure these Cloudflare/GitHub environment secrets:

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID
• TAVUS_API_KEY and MCP_BEARER_TOKEN only if you need the legacy shared-token fallback

Then run the Deploy Tavus MCP Worker workflow for test, stg, or prod. The prod Wrangler route is configured as a custom domain on mcp.tavus.io; use https://mcp.tavus-preview.io/mcp as the Cloudflare-owned endpoint until mcp.tavus.io DNS resolves. For direct Wrangler usage, the default config targets production; use wrangler deploy --env test or wrangler dev --env test to point at TEST.

Useful production checks:

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

Unauthenticated /mcp should return 401 with a WWW-Authenticate header that points at the protected-resource metadata URL. A 404 Not Found at discovery usually means the Worker version serving the custom domain does not include the OAuth routes yet.

Codex Skill

A publishable Codex skill for this repo lives at skills/tavus-agentic-personas/. It documents the CLI and MCP workflows, safe persona patching, environment setup, and concrete examples for agents using this toolkit.

Install it by copying that folder into ${CODEX_HOME:-$HOME/.codex}/skills/, or publish the folder directly through whatever skill distribution flow you use.