# MCP server

The VidMachine MCP server connects your account to AI assistants and coding agents that speak the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Code, OpenAI Codex, Cursor, and other MCP clients. It uses the same API keys, credit balance, and business rules as the [REST API](https://vidmachine.ai/docs/api.md), so anything you generate through an assistant is visible in your dashboard.

## Endpoint

The server speaks JSON-RPC 2.0 over a single stateless HTTPS `POST` and returns JSON responses:

```
https://vidmachine.ai/api/mcp
```

### Authentication

Authenticate with the same API key you use for the REST API, sent as a Bearer token. Create one under [API Keys](https://vidmachine.ai/api-keys) (after login).

```
Authorization: Bearer vidm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Set up a client

In every case you provide the endpoint URL above and an `Authorization: Bearer <key>` header.

### Claude Code

Put your key in the environment, then register VidMachine as an HTTP MCP server. The single quotes keep your shell from expanding the variable, so the key is not written to the config in plaintext.

```bash
export VIDMACHINE_API_KEY=vidm_...
claude mcp add --transport http vidmachine \
  https://vidmachine.ai/api/mcp \
  --header 'Authorization: Bearer ${VIDMACHINE_API_KEY}'
```

Run `claude mcp list` to confirm it connected.

### Project config (.mcp.json)

The same placeholder works in a project `.mcp.json`, which is the safer form when the file is committed.

```json
{
  "mcpServers": {
    "vidmachine": {
      "type": "http",
      "url": "https://vidmachine.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${VIDMACHINE_API_KEY}" }
    }
  }
}
```

### Codex CLI

Add an entry to `~/.codex/config.toml`. The `bearer_token_env_var` field names an environment variable that holds your key — it is not the key itself.

```toml
[mcp_servers.vidmachine]
url = "https://vidmachine.ai/api/mcp"
bearer_token_env_var = "VIDMACHINE_MCP_KEY"
```

```bash
export VIDMACHINE_MCP_KEY="vidm_..."   # raw key, no "Bearer " prefix
```

Open a new terminal and run `codex mcp list` to confirm.

### Cursor and other clients

In Cursor, add an MCP server of type **http** with the URL above and an `Authorization` header, or reuse the `.mcp.json` entry. Any client that supports Streamable HTTP and a custom header works the same way.

## Tools

Your assistant reads each tool's input schema automatically, so you rarely need to know the argument names. Read tools never change anything; write tools act on your account and use credits where noted.

### Read tools

| Tool | What it does |
|---|---|
| `list_projects` | List every project with its content types, model priorities, and schedule. |
| `list_videos` | List videos, filtered by project, status, limit, and offset. |
| `list_models` | Catalog of callable image and video models with inputs and credit pricing. |
| `list_generations` | List API generations, filtered by status and model. |
| `get_generation` | Poll one generation for its status, output URL, and credits charged. |

### Write tools

| Tool | What it does |
|---|---|
| `create_project` | Create a project; title is required, all other settings optional. |
| `update_project` | Update any subset of a project's settings. |
| `generate_ideas` | Generate 10 video ideas for a project. Uses credits. |
| `generate_video` | Run the full one-shot pipeline for an idea. Uses credits. |
| `update_video` | Edit a video's title, status, post time, or cover. Same rules as the dashboard. |
| `create_generation` | Queue any catalog model for image or video generation. |

## Errors

A missing or invalid API key returns HTTP `401` with a JSON-RPC error. Tool failures return a result with `isError: true` and the same codes as the REST API: `402` insufficient credits, `404` not found, `429` too many generations in flight.

## Credits

MCP usage draws on the same credit balance as your dashboard. `create_generation` charges only when the model succeeds and failed generations are free. Up to 10 queued or processing generations per account at a time. See [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md).

## Related

- [API reference](https://vidmachine.ai/docs/api.md) — the REST API that the MCP tools call.
- [AI models](https://vidmachine.ai/models) — the catalog returned by `list_models`.
- [Programmatic overview](https://vidmachine.ai/api)
- [Docs home](https://vidmachine.ai/docs/)
- [Manage API keys](https://vidmachine.ai/api-keys) (login required)