MCP server

The MCP server exposes Clip Foundry to Claude Code, Claude Desktop, Cursor, and any MCP client over stdio.

Claude Code (CLI) — one command, copy-paste (swap in your key):

bash

claude mcp add clipfoundry -e CLIPFOUNDRY_API_KEY=cf_live_... -- npx -y @clipfoundry/mcp

Claude Desktop / Cursor — add to the client's MCP config:

json

{
  "mcpServers": {
    "clipfoundry": {
      "command": "npx",
      "args": ["-y", "@clipfoundry/mcp"],
      "env": { "CLIPFOUNDRY_API_KEY": "cf_live_..." }
    }
  }
}

Get your key at https://app.clipfoundry.pl/settings/keys.

Tools: create_short, get_job, list_jobs, cancel_job, list_styles, list_voices, get_balance. create_short takes the script you want narrated (the full voice-over text, 10–5000 chars) plus a voiceId from list_voices — not a topic. The engine speaks the script verbatim and produces the images, captions and music. Give your assistant the script and a voice and it queues a job through your account.

Run against a local engine

The MCP server just calls the HTTP API, so local generation needs the engine running. Point the client at your local API with CLIPFOUNDRY_API_URL:

json

{
  "mcpServers": {
    "clipfoundry-local": {
      "command": "npx",
      "args": ["-y", "@clipfoundry/mcp"],
      "env": {
        "CLIPFOUNDRY_API_KEY": "cf_...",
        "CLIPFOUNDRY_API_URL": "http://localhost:4000"
      }
    }
  }
}

Run the API (pnpm --filter @shorts-engine/engine http:watch) and the dispatcher (pnpm --filter @shorts-engine/engine dispatcher:watch), and mint a key at http://localhost:3000/app/settings/keys. From a clone you can also run the server from source: pnpm --filter @clipfoundry/mcp dev.

Remote / web clients (Streamable HTTP)

For browser or hosted clients, run the HTTP transport instead of stdio:

bash

clipfoundry-mcp-http   # serves POST/GET/DELETE /mcp on :4100

It speaks the modern Streamable HTTP transport (SSE under the hood) with mcp-session-id sessions. Auth is per session — each client sends Authorization: Bearer <your-key> on initialize, so one server can serve many users. Point your remote MCP client at https://<host>/mcp.