# MCP server

> Give your agent an editing timeline. MCP connects Claude, ChatGPT, Cursor or your own agent to Vidmoat's editing and media tools.

REST suits a fixed integration where your code decides every step. MCP lets an agent choose tools as it works: inspect footage, edit, look at the frames it produced, fix what is wrong, and export. Both run on the same engine and the same accounts.

| | |
| --- | --- |
| Endpoint | `https://api.vidmoat.com/api/mcp` |
| Transport | Streamable HTTP, JSON-RPC 2.0 over `POST` (no server-sent stream) |
| Protocol versions | `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Auth | OAuth sign-in from the client, or a Vidmoat API key as a bearer token |

## Connect your client

Clients that support OAuth (Claude and ChatGPT connectors, for example) only need the URL: they discover the authorization server from the `401` response and ask you to sign in. Every plan can connect this way. Personal API keys and live developer keys need Studio.

**Claude**

In Claude, add a custom connector and paste `https://api.vidmoat.com/api/mcp` as its URL. Claude opens the Vidmoat sign-in and consent screen.

**ChatGPT**

Add a connector (in developer mode where your workspace requires it) with `https://api.vidmoat.com/api/mcp` as the server URL, and sign in to Vidmoat when asked.

**Claude Code**

```bash
claude mcp add --transport http vidmoat https://api.vidmoat.com/api/mcp \
  --header "Authorization: Bearer $VIDMOAT_KEY"
```

**Cursor**

```json .cursor/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_VIDMOAT_KEY" }
    }
  }
}
```

> **Note.** Client configuration formats change; if one of these does not match your client version, the endpoint and the `Authorization` header are all it needs. Keep keys in the client's secret settings or your server environment, never in a shared file.

## Discover the tools

Let the client initialise and call `tools/list`. Use the names and input schemas it returns rather than a list copied from an old example: tools are added often.

```bash
curl --fail-with-body -sS https://api.vidmoat.com/api/mcp \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

There are over eighty core tools: projects, editing, previews, analysis (shots, faces, audio, dead air, on-screen text), transcription, generation, stock media, renders, scheduling and more. Two of them reach everything else:

- `search_agent_capabilities` finds a capability by describing it, including the tools of plugins you have installed.
- `call_plugin` calls a plugin tool. To list a plugin's tools directly in `tools/list`, add `?scope=<plugin_namespace>` to the endpoint URL.

`get_command_schema` returns the same command vocabulary as `GET /v1/schema/commands`.

## Give it a usable brief

```text
Use my product footage to make a 20-second vertical launch video.
Start with the product reveal, then show three benefits.
Use our orange brand accents and readable captions.
Keep music beneath the narration. Do not generate paid media
without telling me the cost. Preview the opening, each text
change and the ending before exporting.
```

Say the audience, duration, aspect ratio, source media and any budget. A style reference guides the edit; it does not have to appear in the finished video. Character references are optional: use them when continuity matters.

## Review, then export

Have the agent inspect the source, apply edits, review rendered frames and correct visible problems. A successful edit call is not proof that the composition looks right. `edit_project` accepts `previewAt` (up to three timestamps) and returns those frames with the result, so the model sees what it did in the same turn. Check the finished export too. You can open the same project in the Vidmoat editor and adjust the timeline yourself.

## Limits

- Plan features, ownership and credit costs apply to each tool exactly as in the editor. Generation tools state their cost.
- MCP requests share a limit of 60 a minute per account. Over it you get `429` with `Retry-After`.
- A JSON-RPC batch carries at most 10 messages, and each `tools/call` after the first counts against the limit again.

- [Video preview](https://developer.vidmoat.com/developer/docs/preview): How frames and previewAt work.
- [Scopes](https://developer.vidmoat.com/developer/docs/scopes): What an API key may do.
- [Plugins](https://developer.vidmoat.com/developer/docs/plugins): Add your own tools to every agent.

---

Source: https://developer.vidmoat.com/developer/docs/mcp
Previous: [Webhooks and your users' data](https://developer.vidmoat.com/developer/docs/telegram/webhooks-and-data.md)
Next: [Plugins](https://developer.vidmoat.com/developer/docs/plugins.md)
All documentation: https://developer.vidmoat.com/llms-full.txt