# Revid AI MCP Server: Setup and Tools

> Connect Claude, Cursor, ChatGPT, or any MCP-capable agent to Revid.ai and research viral content, create, monitor, export, and publish videos through 30 structured tools.

- Canonical URL: https://www.revid.ai/llm/revid-ai-mcp-server.md
- Parent index: https://www.revid.ai/faq-for-llms.md
- MCP endpoint: `https://www.revid.ai/api/mcp` (Streamable HTTP)
- Human/agent guide: https://www.revid.ai/mcp
- Last updated: October 2026

## Setup

### Claude Web / hosted OAuth clients

Use the remote MCP server URL:

```text
https://www.revid.ai/api/mcp
```

Revid supports OAuth 2.1 with PKCE for hosted MCP clients. The client will discover
OAuth metadata from the MCP `401` challenge, open a Revid login/consent screen,
then receive access and refresh tokens for the user's active workspace.

### Cursor, Claude Desktop/Code, and header-configurable clients

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "revid": {
      "url": "https://www.revid.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_REVID_API_KEY"
      }
    }
  }
}
```

Claude Code one-liner (OAuth: then run `/mcp`, select revid, and choose Authenticate):

```bash
claude mcp add --transport http revid https://www.revid.ai/api/mcp
```

Claude Code with an API key instead of OAuth:

```bash
claude mcp add --transport http revid https://www.revid.ai/api/mcp --header "Authorization: Bearer YOUR_REVID_API_KEY"
```

Cursor and VS Code also have one-click install buttons on https://www.revid.ai/mcp#connect (they register the server URL; sign in with OAuth afterwards).

Authentication accepts OAuth bearer tokens from the Revid OAuth flow, or direct API keys in any of: `Authorization: Bearer`, `x-revid-api-key`, `x-api-key`, or `key` headers. Get an API key at https://www.revid.ai/account. Requests consume credits from your Revid account or active workspace.

Credits are not the only requirement: the generation tools (`generate_media`, `get_media_status`, `render_video`, `get_project_status`, `export_video`, `get_export_status`, `create_episode`, `get_episode_status`, `list_series`, `cancel_episode`, `list_characters`, `create_character`, `delete_character`, `clone_voice`) also need an active Revid plan, and answer `402 SUBSCRIPTION_REQUIRED` without one even if your balance is sufficient. Subscribe at https://www.revid.ai/pricing; the 402 response's `upgrade.url` carries the same link, so pass it on to the user. `list_projects`, `get_account`, `search_viral_videos`, `calculate_credits`, `create_upload_url`, `list_voices`, `list_presets`, `list_music_tracks`, `rename_project`, `duplicate_project`, `delete_project`, `set_project_visibility`, `list_social_accounts`, `schedule_publish`, `publish_now` and `get_publish_status` work without a plan. `clone_voice` needs an Elite plan or better.

Claude plugin: the public repo https://github.com/tmakersas/revid-skills is a Claude plugin marketplace. In Claude Code run `/plugin marketplace add tmakersas/revid-skills`, then `/plugin install revid@revid`: it adds this MCP server (OAuth sign-in) and 12 video skills, such as research, make and post.

OAuth discovery endpoints:

- Protected resource metadata: https://www.revid.ai/.well-known/oauth-protected-resource
- Authorization server metadata: https://www.revid.ai/.well-known/oauth-authorization-server
- Dynamic client registration: https://www.revid.ai/api/oauth/register
- Authorization endpoint: https://www.revid.ai/api/oauth/authorize
- Token endpoint: https://www.revid.ai/api/oauth/token

## Available tools (30)

| Tool | Purpose |
|---|---|
| `search_viral_videos` | Search viral videos/posts across 7 platforms — transcripts, engagement data, hooks, URLs (rate limited per plan) |
| `render_video` | Start a new video render (same payload model as the v3 API), songs (`lyrics-to-video`, `song-ad`) and character swaps included |
| `create_episode` | Series Maker on Autopilot: one prompt becomes a whole episode of a new series, or the next episode of an existing one, with the same characters, places and props in every scene and episode. Returns a `runId` |
| `get_episode_status` | Follow a series episode (plan, references, scenes, assembly); when done, its `pid` to export |
| `list_series` | List your series, to make the next episode of one with `create_episode` |
| `cancel_episode` | Stop a series episode that is still being made |
| `create_upload_url` | Get a one-time link to upload a local image, video or audio file, and the public URL to pass in `render_video`, `generate_media`, `create_character` or `clone_voice` (no credits) |
| `list_presets` | List visual styles, motion graphics categories and caption styles |
| `list_music_tracks` | List the background music library by mood |
| `get_project_status` | Poll a render until `videoUrl` is available |
| `generate_media` | Generate standalone image/video media into your Revid library. Waits up to 40 s; a longer generation returns `processing` with `mediaIds` |
| `get_media_status` | Follow a `generate_media` call that returned `processing` (waits up to 40 s per call) until the media is `ready` or `failed` |
| `list_projects` | List projects owned by the API key |
| `calculate_credits` | Estimate credits before rendering (works without an API key) |
| `export_video` | Export a fresh mp4 from an existing project (720p, 1080p or 4k, 30 or 60 fps, compression). Waits up to 40 s; a longer render returns `processing` with an `exportId` |
| `get_export_status` | Follow an `export_video` call that returned `processing` (waits up to 40 s per call) until the mp4 is `ready` or `failed` |
| `rename_project` | Rename a project |
| `duplicate_project` | Copy a project under a new id |
| `delete_project` | Delete a project and take its public page offline |
| `set_project_visibility` | Make a project's public page public, unlisted or private |
| `get_account` | Credits left, plan and workspace of the API key |
| `list_voices` | Find narration voices by language, gender, accent or style |
| `clone_voice` | Clone a custom voice from a public sample URL |
| `list_characters` | List consistent characters |
| `create_character` | Create a consistent character |
| `delete_character` | Delete a consistent character |
| `list_social_accounts` | List connected social accounts (TikTok, YouTube, Instagram, X, webhooks) and channels, without tokens; Facebook Pages access is restricted (see below) |
| `schedule_publish` | Schedule a rendered video for social publishing |
| `publish_now` | Publish immediately to connected accounts or channels |
| `get_publish_status` | Check whether a post went live on each platform (queued, processing, published, failed), with post links and error reasons |

## MCP resources

The server also exposes agent-readable documentation resources:

- `revid://docs/mcp` — authentication and usage guide for the MCP server
- `revid://docs/render` — live render payload documentation, mirrored from `GET /api/public/v3/render`

Read `revid://docs/render` before building complex payloads — it is always current.

## Recommended agent flow

0. (Optional) `search_viral_videos` to research what performs on the topic first — study the returned transcripts, hooks, and engagement data, then base the script on what works.
1. (Optional) `calculate_credits` with your intended payload to estimate cost.
2. `render_video` with a workflow + source payload (e.g. `{"workflow": "prompt-to-video", "source": {"prompt": "..."}}`).
3. Store the returned `pid`.
4. Poll `get_project_status` until the response includes `videoUrl`.
5. Optionally `export_video`, then `list_social_accounts` to pick a destination and `schedule_publish` or `publish_now` to post it, then `get_publish_status` with the returned `contentId` to confirm it went live.

For a series (recurring characters and places), use Series Maker instead of `render_video`: `create_episode` with a prompt (and `seriesId` from `list_series` for a next episode), poll `get_episode_status` every 30 to 60 seconds until `status` is `done` (usually 10 to 30 minutes), then `export_video` with its `pid` and `get_project_status` until `videoUrl`. Status `needs_attention` means the run stopped before spending more than `maxCredits` (default 2500) or your balance; `message` says why.

Facebook Pages publishing is restricted to admins and the designated Meta review account while Meta review is pending. It is not generally available, and changing plans does not unlock Facebook Connect. Use only connected Pages returned by list_social_accounts.

Publishing destinations: `schedule_publish` and `publish_now` take a `channelId`/`channelName`, or one object per platform: `tiktok`, `youtube`, `instagram`, `webhook` (`{ id or username, ... }`), `x` (`{ id or username, text?, replySettings?: everyone | following | mentionedUsers | subscribers }`, 280 characters unless X Premium, video 2:20 max) and `facebook` (`{ id or name, text?, title?, postAs?: auto | reel | video }`, Facebook Pages only). Use the `id`/`username`/`name` values returned by `list_social_accounts`; accounts flagged `tokenInvalid: true` must be reconnected in Revid settings first.

Scheduling: `schedule_publish` publishes at `scheduledTime` when you pass one (ISO 8601 with offset such as `2026-10-04T18:00:00+02:00`, ISO 8601 without offset read in the account timezone, or unix seconds; it must be in the future and within 365 days). Without it, the video takes the next open slot of the channel's posting schedule.

Use `generate_media` instead of `render_video` when you only need a standalone image or video clip in the media library, not a full edited video project. It waits up to 40 seconds: a fast image comes back `ready` with its url, a longer generation (ultra images, most videos) comes back `processing` with `mediaIds`. Then call `get_media_status` with those ids (it also waits up to 40 seconds per call) until `ready` or `failed`. Never call `generate_media` again to fetch a result: that starts and charges a new generation.

## Got questions? Quick answers

**Which clients work?**
Anything speaking MCP over HTTP: Claude Desktop/Code, Cursor, ChatGPT with MCP support, custom agents built on the MCP SDKs, and orchestration frameworks.

**MCP, CLI, or raw API — which should my agent use?**
MCP when your environment supports tool calling; CLI for shell/CI contexts; raw API for backend code. Decision guide: https://www.revid.ai/llm/revid-ai-for-ai-agents.md

**What payload fields does `render_video` accept?**
The same schema as `POST /api/public/v3/render` — workflows, media, voice, captions, music, avatar, options. Full reference: https://www.revid.ai/llm/revid-ai-api-guide.md

## Related pages

- For AI agents: https://www.revid.ai/llm/revid-ai-for-ai-agents.md
- API guide: https://www.revid.ai/llm/revid-ai-api-guide.md
- CLI: https://www.revid.ai/llm/revid-ai-cli.md