> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatorline.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Give Claude Code, Cursor, or any MCP client the ability to generate and publish.

Creatorline runs a **remote, stateless** MCP server. There is nothing to install and no local process, point your client at the URL with your API key.

* **Endpoint:** `https://api.creatorline.io/mcp`
* **Transport:** streamable HTTP (MCP revision `2026-07-28`)
* **Auth:** `Authorization: Bearer <CREATORLINE_API_KEY>` on every request

Every harness below connects to the same endpoint. The only thing that changes is where you paste the config.

## Connect a harness

<Tabs>
  <Tab title="Claude Code">
    Add the server from the terminal:

    ```bash theme={null}
    claude mcp add --transport http creatorline https://api.creatorline.io/mcp \
      --header "Authorization: Bearer $CREATORLINE_API_KEY"
    ```

    Or add it by hand to `~/.claude.json` (user scope) or `.mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "creatorline": {
          "type": "http",
          "url": "https://api.creatorline.io/mcp",
          "headers": { "Authorization": "Bearer ${CREATORLINE_API_KEY}" },
          "timeout": 600000
        }
      }
    }
    ```

    Verify with `claude mcp list`, then `/mcp` inside a session to inspect tools.

    <Warning>
      Set `timeout` to at least `60000`. Claude Code applies a 60-second first-byte timer to HTTP MCP servers and a 5-minute idle timer; the default is too tight for a video run's first poll.
    </Warning>
  </Tab>

  <Tab title="Codex CLI">
    Codex CLI (OpenAI) reads `~/.codex/config.toml`. HTTP MCP servers live under `[mcp_servers.<name>]` with `experimental_use_rmcp_client = true`:

    ```toml theme={null}
    experimental_use_rmcp_client = true

    [mcp_servers.creatorline]
    url = "https://api.creatorline.io/mcp"
    bearer_token_env_var = "CREATORLINE_API_KEY"
    ```

    Export the key in the shell you launch `codex` from:

    ```bash theme={null}
    export CREATORLINE_API_KEY="crl_sk_live_…"
    codex
    ```

    Inside Codex, run `/mcp` to confirm the server is listed and its tools loaded.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "creatorline": {
          "type": "http",
          "url": "https://api.creatorline.io/mcp",
          "headers": { "Authorization": "Bearer ${CREATORLINE_API_KEY}" }
        }
      }
    }
    ```

    Restart Cursor, then open **Settings → MCP** and confirm `creatorline` is green.
  </Tab>

  <Tab title="Windsurf">
    Windsurf (Cascade) reads `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "creatorline": {
          "serverUrl": "https://api.creatorline.io/mcp",
          "headers": { "Authorization": "Bearer ${CREATORLINE_API_KEY}" }
        }
      }
    }
    ```

    Reload the MCP list from **Cascade → MCP servers → Refresh**.
  </Tab>

  <Tab title="VS Code / Copilot">
    GitHub Copilot in VS Code supports HTTP MCP servers via `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "creatorline": {
          "type": "http",
          "url": "https://api.creatorline.io/mcp",
          "headers": { "Authorization": "Bearer ${input:creatorline_key}" }
        }
      },
      "inputs": [
        {
          "id": "creatorline_key",
          "type": "promptString",
          "description": "Creatorline API key",
          "password": true
        }
      ]
    }
    ```

    Open the **MCP: List Servers** command to start it. VS Code will prompt for the key once and store it in the secret store.
  </Tab>

  <Tab title="Zed">
    In `~/.config/zed/settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "creatorline": {
          "source": "custom",
          "url": "https://api.creatorline.io/mcp",
          "headers": { "Authorization": "Bearer ${CREATORLINE_API_KEY}" }
        }
      }
    }
    ```

    Then enable it under **agent panel → tools**.
  </Tab>

  <Tab title="Other (raw HTTP)">
    Any MCP-compatible client that speaks streamable HTTP works. Give it:

    ```text theme={null}
    URL:     https://api.creatorline.io/mcp
    Method:  POST (streamable HTTP)
    Header:  Authorization: Bearer <CREATORLINE_API_KEY>
    ```

    No session id, no OAuth handshake, no local binary. If the client only supports `stdio`, wrap the URL with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

    ```json theme={null}
    {
      "mcpServers": {
        "creatorline": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote",
            "https://api.creatorline.io/mcp",
            "--header", "Authorization: Bearer ${CREATORLINE_API_KEY}"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Prefer the CLI to write the config for you: `crl mcp config` prints the snippet for your harness, and `crl mcp install` runs `claude mcp add` on your behalf.
</Tip>

## Tools

<CardGroup cols={2}>
  <Card title="Discovery" icon="magnifying-glass">
    `list_models` · `list_voices` · `list_accounts` · `get_credit_balance` · `estimate_generation_cost`
  </Card>

  <Card title="Generation" icon="sparkles">
    `create_generation` · `get_generation` · `list_assets`
  </Card>

  <Card title="Publishing" icon="paper-plane">
    `create_post` · `publish_post` · `list_posts`
  </Card>
</CardGroup>

Eleven coarse tools, not one per model. A tool per model would consume an agent's context for no benefit; instead `create_generation` takes a `tool` and the model schema comes from `list_models` — which returns each model's full shape: every input slot with its cap, every parameter with its allowed values **or** numeric bounds, what opaque values mean, whether a prompt is required, and how long a take can be. `list_voices` covers the one thing the catalog cannot enumerate, the live voice list the audio tools take.

## How an agent should use it

<Steps>
  <Step title="Find out what exists">
    `list_models` for the catalog, `list_accounts` for the creators. Never guess an id.
  </Step>

  <Step title="Price it if the user asked">
    `estimate_generation_cost` is free and does not start anything. Give it the same `inputs` / `source_url` the real run will use: the source-billed tools (`lipsync`, `motion-control`, `scene-video`, `change-voice`, `short-clip`) charge per second of the source, so an estimate without the media is only a default-length guess.
  </Step>

  <Step title="Start and poll">
    `create_generation` returns a job handle **immediately** and reports the credits it charged. Poll `get_generation` every few seconds — a video takes minutes, and holding the tool call open would hit the client's idle timer.

    Beyond `tool` / `prompt` / `inputs` / `params`, it carries `source_url` (work from a video link, for a tool whose catalog entry has `accepts_source_url`) and `include_account_avatar` (set false when the creator must not appear in the output).
  </Step>

  <Step title="Publish only on request">
    `create_post` puts a post in the review queue. `publish_post` makes it public — it is annotated as destructive so your client prompts first, and the tool description tells the model to confirm with the user.

    `create_post` carries the full composition: `format`, `hashtags`, `draft`, `made_with_ai`, `auto_add_music`, `photo_cover_index` and per-platform overrides in `platform_settings`. See [Publishing](/publishing) for what each one does. A setting the platform cannot take comes back as a plain-English error the model can act on, rather than a post that publishes wrong.
  </Step>
</Steps>

## Multi-tenancy

The workspace comes from the **API key**, never from a tool argument. There is no `workspace_id` parameter anywhere in the tool surface, so a model cannot be talked into reading another organization's data.

A `read`-scope key gets a plain-English refusal from the writing tools rather than a protocol error, so the agent can explain the problem instead of retrying.

## Stateless

The server implements the 2026-07-28 MCP revision: no session id, no handshake, no resumable streams. Every request builds a fresh server instance bound to the calling key. In practice that means it never gets into a bad session state, it scales horizontally, and reconnecting costs nothing.

<Accordion title="claude.ai connectors">
  Custom connectors on claude.ai currently support OAuth only — there is no field for a custom header — so the API-key connection above works with **Claude Code and Cursor** today. OAuth support for claude.ai connectors is planned.
</Accordion>

## Results stay small

Media comes back as URLs, never inline. Lists default to 20 rows and page. Claude Code truncates tool output at 25,000 tokens, so the tools are built to stay well under that — if you need everything, page rather than raising the limit.


## Related topics

- [Creatorline API](/index.md)
- [Errors and idempotency](/errors.md)
- [CLI](/cli.md)
- [Authentication](/authentication.md)