MCP server
The VidMachine MCP server connects your account to AI assistants and coding agents that speak the Model Context Protocol — Claude Code, OpenAI Codex, Cursor, and other MCP clients. It uses the same API keys, credit balance, and business rules as the REST API, 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 (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.
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.{
"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.[mcp_servers.vidmachine] url = "https://vidmachine.ai/api/mcp" bearer_token_env_var = "VIDMACHINE_MCP_KEY"
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
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
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.Related
API reference — the REST API that the MCP tools call. AI models — the catalog returned by
list_models. Programmatic overview.