# MCP

Connect VidLab to Claude, Cursor, Codex or ChatGPT and your agent can find models, price them, make images, video and audio, and run our ad formats, as tools.

The quickest way is the [Connect page](https://vidlab.ai/connect): one click adds VidLab to Claude, with one-click or copy-paste setup for Claude Code, Cursor, ChatGPT and Codex.

Or one command that sets up every client it finds and installs the skill:

```bash
npx @vidlab/cli setup
```

## The endpoint

```text
https://vidlab.ai/api/developers/v1/mcp?profile=api
```

- Remote, streamable HTTP. Nothing to install and no local package.
- `?profile=api` serves the 14 tools below, in the order an agent uses them. Without it you also get the rest of the VidLab app's tools, including the [viral video library](https://docs.vidlab.ai/viral-videos).
- Stateless: each message is one authenticated `POST`, so reconnecting is always safe. A plain `GET` answers `405` by design.
- Sign in with **OAuth** (Claude Code, Claude desktop and claude.ai, ChatGPT, Cursor), or send an **API key** as a header (Cursor, Codex and any client with fixed headers): `Authorization: Bearer vidlab_sk_...` or `x-api-key: vidlab_sk_...`.

> Keep API keys out of installation commands and config files. Every setup below reads the key from the `VIDLAB_API_KEY` environment variable, or signs in with OAuth and stores nothing.

## Billing

Generations and format runs bill your **API wallet**, whichever way you sign in: the price is held when a run starts and charged only if it succeeds. A failed run costs nothing. `get_wallet` shows the balance; add credit on the [billing page](https://vidlab.ai/vidlab-api/billing).

## Set your key

Clients that send a header read the key from your environment. Add it once to your shell profile (`~/.zshrc` or `~/.bashrc`), then open a new terminal:

```bash
export VIDLAB_API_KEY="vidlab_sk_your_key_here"
```

## Claude Code

Sign in with OAuth, so no key is stored at all:

```bash
claude mcp add --transport http --scope user vidlab "https://vidlab.ai/api/developers/v1/mcp?profile=api"
```

Then run `/mcp` inside Claude Code, pick `vidlab` and sign in to VidLab. Leave out `--scope user` to add it to the current project only.

To use your key instead, keep the placeholder in single quotes. Claude Code fills in `${VIDLAB_API_KEY}` from your environment when it starts, so nothing secret is stored:

```bash
claude mcp add --transport http --scope user vidlab "https://vidlab.ai/api/developers/v1/mcp?profile=api" --header 'Authorization: Bearer ${VIDLAB_API_KEY}'
```

Or add a `.mcp.json` to your project:

```json
{
  "mcpServers": {
    "vidlab": {
      "type": "http",
      "url": "https://vidlab.ai/api/developers/v1/mcp?profile=api",
      "headers": { "Authorization": "Bearer ${VIDLAB_API_KEY}" }
    }
  }
}
```

## Cursor

Add this to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project). Cursor fills in `${env:VIDLAB_API_KEY}` from your environment:

```json
{
  "mcpServers": {
    "vidlab": {
      "url": "https://vidlab.ai/api/developers/v1/mcp?profile=api",
      "headers": { "Authorization": "Bearer ${env:VIDLAB_API_KEY}" }
    }
  }
}
```

Leave out `headers` to sign in with OAuth instead: Cursor shows a sign-in button on the server.

## Codex

With a key, one command. Codex reads the key from the variable you name:

```bash
codex mcp add vidlab --url "https://vidlab.ai/api/developers/v1/mcp?profile=api" --bearer-token-env-var VIDLAB_API_KEY
```

That writes this to `~/.codex/config.toml`:

```toml
[mcp_servers.vidlab]
url = "https://vidlab.ai/api/developers/v1/mcp?profile=api"
bearer_token_env_var = "VIDLAB_API_KEY"
```

To sign in with OAuth instead, put the same block without the `bearer_token_env_var` line in `~/.codex/config.toml` and run `codex mcp login vidlab`. (`codex mcp add` without the key flag opens the browser sign-in at once and waits for it.)

## ChatGPT

1. Open **Settings**, then **Apps and Connectors**, and add a custom connector (this may need developer mode turned on).
2. Paste `https://vidlab.ai/api/developers/v1/mcp?profile=api` as the URL.
3. Sign in to VidLab and choose **Allow access**.

No key or client id is needed: the connector signs in with OAuth.

## Claude desktop and claude.ai

The **Connect** button on the [Connect page](https://vidlab.ai/connect) opens Claude's own dialog with VidLab's name and URL filled in: press **Add**, then **Connect**, and allow VidLab. By hand:

1. Open **Customize**, then **Connectors**, and choose **Add custom connector**.
2. Paste `https://vidlab.ai/api/developers/v1/mcp?profile=api` as the URL.
3. Sign in to VidLab and choose **Allow access**.

OAuth access tokens last an hour and refresh on their own. Remove the connector in the client to revoke it.

## Other clients

Most remote MCP clients take this shape. Put the key in the client's secret or environment setting, not in the file:

```json
{
  "type": "http",
  "url": "https://vidlab.ai/api/developers/v1/mcp?profile=api",
  "headers": { "Authorization": "Bearer ${VIDLAB_API_KEY}" }
}
```

A client that only speaks stdio can bridge with `mcp-remote`. It signs in with OAuth in your browser, so no key is involved:

```bash
npx -y mcp-remote "https://vidlab.ai/api/developers/v1/mcp?profile=api"
```

## Tools

`tools/list` is the source of truth. With `?profile=api`:

| Tool | What it does |
| - | - |
| `list_models` | Image, video, audio, lip sync and upscale models: id, maker, kind, price from, the inputs each takes. Free. |
| `get_model` | One model in full: `input_schema` (the exact input for this model), every price option. Free. |
| `estimate_price` | The exact price of one generation before it starts. Free. |
| `generate` | Starts a generation. Paid from the API wallet, only on success. Send `max_price_usd` and `idempotency_key`; `wait` blocks up to 60 seconds. |
| `get_generation` | Status, price and the output links. Free. |
| `list_formats`, `run_format`, `answer_format_questions`, `get_format_run`, `cancel_format_run` | Run an [ad format](https://docs.vidlab.ai/formats): start it, answer its questions (the price included), read the finished video, stop it. |
| `get_wallet` | The API wallet balance and where to add credit. Free. |
| `account_status` | Which account the key belongs to. Free. |
| `stage_file` | Turn a local file or a URL into an upload id for a format's image input. |
| `send_feedback` | Tell VidLab where something got in your way. Free. |

Other profiles: `?profile=readonly` serves only tools that change nothing, and `?profile=no_media` hides the paid generation tools. Without a profile you also get `ask_vidlab` and the rest of the VidLab app's tools.

## Access

A key with scopes needs the `mcp` scope (dashboard keys have full access). An account without API access gets `403` with "Developer access required".

## Check it works

Ask your assistant something free first:

```text
Use VidLab to list three video models and the price of a 5 second clip at 720p.
```