---
title: MCP server
summary: Connect Claude, ChatGPT, Codex, Cursor, OpenClaw, Hermes or any MCP client; the tools and their flow.
updated: '2026-11-17'
---

# MCP server

Zebracat runs a remote MCP server (Model Context Protocol, streamable HTTP) at:

```
https://mcp.zebracat.ai/mcp
```

It authenticates the same two ways as the REST API: OAuth (the client opens a Zebracat login; spends your plan
credits) or an `X-API-KEY` header (spends your API dollar balance). Every tool re-enters the public REST endpoint
it names, so validation, prices, limits, idempotency and errors are exactly the REST API's.

## Connect

Every client below signs in with OAuth unless it sends an `X-API-KEY` header. OAuth spends your plan credits; an
API key spends your API dollar balance.

**Claude (claude.ai, Claude Desktop, Cowork, mobile):**

1. Open **Customize → Connectors** (`https://claude.ai/customize/connectors`).
2. Click **+ Add → Add custom connector**. Name it `Zebracat` and paste `https://mcp.zebracat.ai/mcp`, then click **Continue**.
3. Keep the sign-in settings Claude detects (OAuth; Claude registers itself with Zebracat automatically) and click
   **Add**.
4. Click **Connect** and sign in with your Zebracat account, then approve the permissions.
5. In a chat, turn Zebracat on under **+ → Connectors** and ask for a video.

Free Claude plans allow one custom connector. On Team and Enterprise plans an Owner first adds it under
**Organization settings → Connectors → Add → Custom → Web** with the same URL; each member then opens Customize →
Connectors, finds Zebracat and clicks **Connect**. To change the URL later, remove the connector and add it again.

**ChatGPT (chatgpt.com; custom MCP servers need a Business, Enterprise or Edu workspace):**

1. Open **Plugins** (`https://chatgpt.com/plugins`) and select **+ → Add custom MCP server**.
2. Name it `Zebracat` and paste `https://mcp.zebracat.ai/mcp` under **Connection**.
3. Choose **OAuth**, review the risk warning, select **I understand and want to continue**, then **Create as a
   plugin**.
4. Sign in with your Zebracat account and approve the permissions.
5. In a new chat, type `@`, pick Zebracat and ask for a video.

On Business, an admin or owner adds it for the workspace.

**Codex:**

```bash
codex mcp add zebracat --url https://mcp.zebracat.ai/mcp
codex mcp login zebracat
```

**Claude Code:**

```bash
claude mcp add --transport http zebracat https://mcp.zebracat.ai/mcp
```

Then run `/mcp` in Claude Code to log in (plan credits). With an API key instead:
`claude mcp add --transport http zebracat https://mcp.zebracat.ai/mcp --header "X-API-KEY: $ZEBRACAT_API_KEY"`.

**Cursor, Windsurf, other clients** (`mcp.json`; Cursor: `~/.cursor/mcp.json`). OAuth:

```json
{"mcpServers": {"zebracat": {"url": "https://mcp.zebracat.ai/mcp"}}}
```

Or with an API key:

```json
{"mcpServers": {"zebracat": {"url": "https://mcp.zebracat.ai/mcp", "headers": {"X-API-KEY": "sk-your-api-key"}}}}
```

**OpenClaw:**

```bash
openclaw mcp set zebracat '{"url":"https://mcp.zebracat.ai/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw gateway stop && openclaw mcp login zebracat   # or Settings → MCP → Sign in
```

Start the Gateway again afterwards.

**Hermes:**

```bash
hermes mcp add zebracat --url https://mcp.zebracat.ai/mcp --auth oauth
```

Hermes opens the login on the first connection (`hermes mcp login zebracat` if it does not), then `/reload-mcp`.

**Raw JSON-RPC** (for testing):

```bash
curl -sS -X POST https://mcp.zebracat.ai/mcp \
  -H "X-API-KEY: $ZEBRACAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1"}}}'
```

Send the `Mcp-Session-Id` the answer returns on every later call (`tools/list`, `tools/call`).

## The flow the tools follow

The server's `instructions` teach the model this order, and the paid tools enforce it:

1. `create_video` (or `plan_video`) with the person's words. MCP plans first: `auto_generate` defaults to `false`.
2. `get_video` until `phase` is `plan_ready`, or `needs_input` (then `answer_video_question`).
3. Show the person the plan summary and `quote_video`'s price.
4. Change it with `edit_plan` or `chat_plan` if they ask.
5. `generate_video` with `confirmed: true` only after the person says yes. Without it, the tool answers the quote
   and `awaiting_confirmation`, and nothing is spent.
6. `get_video` every 15-30 seconds until `completed`; give the person `video_url` and `editor_url`.

Every paid tool in the table below works this way: first the price, then `confirmed: true` (`generate_video`,
`clone_video`, `translate_video`, `generate_script`, and `schedule_post`, which posts publicly). Create tools take an
optional `idempotency_key`, sent as the `Idempotency-Key` header; a confirmed `clone_video` sent again without one,
or the same `schedule_post` within 10 minutes, answers the first one instead of charging or posting twice.

Every failure is a tool error with a `code` and a sentence saying what to do: `not_found` for an id that is not on
this account (someone else's video included), `plan_not_ready` while a video has no plan yet, `insufficient_credit`
or `insufficient_balance`, `plan_upgrade_required` for a feature the plan does not include, `video_not_ready` for a
video still being made, `provider_timeout` when a service Zebracat uses is slow, and `insufficient_scope` for a write
on a read-only sign-in. An expired token gets the OAuth challenge (HTTP 401), so the client signs in again.

## Tools

Each tool's description names when to use it, its cost, what it returns and the tool to call next. Every tool
carries `title` and explicit `readOnlyHint`, `destructiveHint` and `openWorldHint` annotations: read tools are
`readOnlyHint: true`; every tool that can spend credits, post publicly or cancel a job is `destructiveHint: true`, so
Claude and ChatGPT ask the person before calling it; tools that take an arbitrary public link are
`openWorldHint: true`.

Besides making videos, the tools read the studio's libraries: music (`list_music` by mood, `search_music` by
description), the brainrot backgrounds (`list_brainrot_backgrounds`), the person's uploads (`list_media`), the
Inspiration feed (`search_inspiration`: viral videos by keyword, niche or brand; a free plan gets the shared trending
feed) and a feed video's words (`get_inspiration_transcript`), and social scheduling (`list_social_accounts`,
`list_scheduled_posts`, `schedule_post`).

| Tool | What it does | Kind |
|---|---|---|
| `answer_video_question` | Answer the question the planner asked (phase needs_input); planning resumes. | write |
| `cancel_video` | Cancel a video before it spends: a queued (pending) job, or a Director v2 video still planning or at its plan. It cannot be undone. | write: can spend credits, post or cancel |
| `chat_plan` | Send one plan-chat turn: ask about the plan or say what to change; every change lands as one new version. | write |
| `clone_video` | Make a new video modelled on a reference video: its style, pacing, structure, script and music are analysed (about 60-90 s), then a new video is generated. | write: can spend credits, post or cancel |
| `create_avatar_from_image` | Create a custom avatar (digital twin) from one photo. It is animated and lip-synced whenever it appears in a video. | write |
| `create_video` | Start a Director v2 video from the user's words, the way the dashboard's /chat does: a plan first, then Generate. | write: can spend credits, post or cancel |
| `edit_plan` | Apply one structured change to the plan as a new version, exactly as the dashboard's plan card does. | write |
| `generate_script` | Write a voice-over script from an idea and return the text at once. No video is made. | write: can spend credits, post or cancel |
| `generate_video` | Film the approved plan: clips, voices, music and the final video. This is the step that spends. | write: can spend credits, post or cancel |
| `get_balance` | Read what the caller can spend: the plan's credits and the API dollar balance, plus their API keys. | read |
| `get_inspiration_transcript` | Read what an Inspiration video says: its spoken words, or its on-screen text when it has no speech. | write |
| `get_plan` | Read the full plan of a video: the screenplay (beats, cast, places, voices, music), the render choices and its version rev. | read |
| `get_pricing` | List what each kind of generation costs: credits per minute, and the dollar price of a credit. | read |
| `get_project` | Read one video job in full: status, project_id, video_url and error. Find it by task_id or by project_id. | read |
| `get_video` | Read a Director v2 video: its phase, the plan's question or summary, the quote, and the video once made. | read |
| `get_video_status` | Read the current status of one video job. | read |
| `list_avatars` | List the AI presenters (avatars) a video can put on camera: the user's own and any catalogue presenters. | read |
| `list_brainrot_backgrounds` | List the brainrot background library: its categories (Subway, Minecraft, Satisfying...) and their clips. | read |
| `list_brands` | List the user's brand kits (logo, colours, fonts). | read |
| `list_characters` | List the user's saved characters: reusable people kept consistent across videos, each with its saved title and description. | read |
| `list_cloned_voices` | List the caller's own cloned voices. | read |
| `list_languages` | List the languages a new video's voice-over and script can be in. | read |
| `list_latest_videos` | List the caller's most recent video jobs, newest first. | read |
| `list_media` | List the files the user uploaded to their Zebracat media library (pictures, videos, audio), newest first. | read |
| `list_music` | List the music moods, and the hand-picked tracks of one mood (the shelf a video's music is chosen from). | read |
| `list_presets` | List the video presets: formats (street interview, podcast, UGC ad...) and tool pages (Ghibli, brainrot...), each with the defaults it pre-fills. | read |
| `list_projects` | List the caller's video jobs, newest first, optionally only those in one status. | read |
| `list_prompt_styles` | List the script writing styles (listicle, storytime, howto, pov ...). | read |
| `list_scheduled_posts` | List the user's social posts: scheduled, being posted, posted or failed. | read |
| `list_social_accounts` | List the social accounts the user connected to Zebracat (TikTok, Instagram, YouTube...) and whether each can post. | read |
| `list_templates` | List the ready-made video templates. Each has a prompt_markup sentence with blanks to fill and a full_prompt describing the video. | read |
| `list_translate_languages` | List the target languages translate_video supports. | read |
| `list_video_models` | List the quality tiers, the video models each films on and their credits per 5 s scene. | read |
| `list_visual_styles` | List the visual styles (looks such as Cinematic or Ghibli Studio), grouped by category. | read |
| `list_voices` | List the voice-over voices: the catalogue voices of every provider plus the caller's cloned voices (is_cloned true). | read |
| `plan_video` | Plan a Director v2 video from the user's words and wait (up to 45 s) for the plan: screenplay summary and price. Nothing is generated. | write |
| `quote_video` | Price the plan's current version: the exact amount Generate charges. | read |
| `resolve_template` | Fill a template's blanks and return the prompt that makes its video. | read |
| `schedule_post` | Publish a finished video to the user's connected social accounts, now or at a set time. Posts are public. | write: can spend credits, post or cancel |
| `search_inspiration` | Find viral short videos (TikTok, YouTube Shorts) for ideas: by keyword or niche, or trending for the user's brands. | read |
| `search_music` | Search the music library by description: tracks whose sound matches the words. | read |
| `translate_video` | Translate an existing video into another language: the speech is re-voiced, with optional translated captions. | write: can spend credits, post or cancel |
| `undo_plan` | Undo plan changes: back to the version before (or to_rev), saved as a new version. | write |

## Credits and plan messages

MCP sign-in spends the plan credits of the signed-in account, exactly as the studio does; an `X-API-KEY` spends the
API dollar balance. Planning, quotes, catalogues and status are free. When a call needs more credits than the
balance holds, or a feature the plan does not include, the tool answers a plain statement with its `code` and the
numbers, for example `Not enough credits for this. Your balance is 12 credits; it needs 40.` MCP answers carry no
links to billing, upgrade or checkout pages.

## Ask in Claude or ChatGPT

| You say | What happens |
|---|---|
| "Make a 30-second vertical video about why octopuses are so smart." | `plan_video`, then `get_video` until the plan is ready, then `quote_video`: the plan and its price, nothing spent |
| "Looks good, make it." | `generate_video` with `confirmed: true`; the answer has the `task_id` and the editor link at once |
| "Is my video ready? Give me the download link." | `get_video`: the phase, then `video_url` (MP4) and `editor_url` when done |
| "Make a video that reads this script word for word: …" | `plan_video` with `input_kind: "script"`; the words are kept exactly |
| "Translate this video into Spanish: https://…/promo.mp4" | `translate_video`: the price first, then `confirmed: true` on the person's yes |
| "Show my last five Zebracat videos." | `list_projects` |
| "What's going viral about skincare right now?" | `search_inspiration` with `keyword: "skincare"`, then `get_inspiration_transcript` for a video's words |
| "Make one like the second video." | `clone_video` with that video's `url` (a quote first; paid plans) |
| "Use calm music." / "Find upbeat lo-fi." | `list_music` with `mood: "calm_chill"`, then `edit_plan` `set_music`; `search_music` |
| "Put Minecraft parkour behind it." | `list_brainrot_backgrounds`, then `edit_plan` `set_background` on a brainrot plan |
| "Post it to my TikTok tomorrow at 9." | `list_social_accounts`, then `schedule_post` (what it would post first, then `confirmed: true`) |

## Example: one video, plan first

```json
{"method": "tools/call", "params": {"name": "create_video", "arguments": {"brief": "A 30-second explainer on how bees make honey", "aspect": "vertical"}}}
{"method": "tools/call", "params": {"name": "get_video", "arguments": {"task_id": "9f1c2a7b4e5d4c3b"}}}
{"method": "tools/call", "params": {"name": "quote_video", "arguments": {"task_id": "9f1c2a7b4e5d4c3b"}}}
{"method": "tools/call", "params": {"name": "generate_video", "arguments": {"task_id": "9f1c2a7b4e5d4c3b", "confirmed": true}}}
```

## Also

- The tool list as JSON, without connecting: `GET https://api.zebracat.ai/api/v1/public/mcp/tools`.
- Installable agent skills (Claude Code, Cursor, Codex, OpenClaw, Hermes): `npx skills add zebracatai/skills`,
  listed at `https://mcp.zebracat.ai/skills`. They use this MCP server when it is connected.
- The `zebracat` CLI (`npm install -g @zebracat/cli`, or `curl -fsSL https://cli.zebracat.ai | bash`) signs in with
  an API key (`zebracat auth login`) and spends your API dollar balance. See [CLI](cli.md).
- OAuth endpoints, scopes and token lifetimes, for client builders: [Auth and billing](auth-and-billing.md).

<!-- WORKFLOWS (crew `workflows`, 2026-11-17): add the workflow tools here (list, create, update, pause, resume,
run, runs), one line each with the matching REST endpoint, once they are on the server. Until then nothing is
listed, so the docs never name a tool the server does not serve. -->
