MCP server

Connect any MCP client to the hosted Windpaint MCP server: authentication, all 20 tools, and the errors agents see.

The Windpaint MCP server gives an agent Windpaint’s generation API as MCP tools: list capabilities, estimate, upload, generate, wait, download, and run products. It’s a thin client of the public API, so every tool call is an ordinary API request made with your key, billed and scoped like one.

Hosted endpoint (streamable HTTP):

https://mcp.windpaint.ai/mcp

The quickest way to connect, from Claude Code:

claude mcp add --transport http windpaint https://mcp.windpaint.ai/mcp \
  --header "Authorization: Bearer $WINDPAINT_API_KEY"

For Claude Code, Codex and Cursor, the skills plugin installs this server along with instructions for using it. See Claude Code, Codex and Cursor.

Authentication

Every request to the hosted server must carry your API key:

The server passes the key through to the API for each call and stores nothing. There is no OAuth sign-in; clients that can only connect through OAuth can’t use the hosted server yet. Create a key in Settings → API Keys (API keys).

Projects

Every job and asset belongs to a project. For each tool call the project is, in order:

1. The tool’s project argument (id or slug), if given.
2. The X-Windpaint-Project header on the connection.
3. Your organization’s default project.

Asset ids only work as inputs inside the project they belong to.

Generic client config

Most MCP clients accept a JSON block like this. Check your client’s docs for where the file lives and whether it supports environment variable interpolation in headers, so the key doesn’t have to be written into the file.

{
  "mcpServers": {
    "windpaint": {
      "type": "http",
      "url": "https://mcp.windpaint.ai/mcp",
      "headers": {
        "Authorization": "Bearer aak_...",
        "X-Windpaint-Project": "my-project"
      }
    }
  }
}

Drop X-Windpaint-Project to use your default project.

Files

The server runs on Windpaint’s side, so it can’t see your disk:

• Uploading: upload_asset takes a public http(s) URL, which the server fetches, or the file contents as data_base64. URLs that point at private or local addresses, or that redirect, are refused. A local file path is refused.
• Downloading: download_asset returns a signed URL valid for 15 minutes. The agent fetches it itself, for example with curl -o out.png "<url>". The signed URL needs no key; don’t share it, and don’t store it. Call download_asset again for a fresh one.

If an agent mostly works with files on disk, it can also use the CLI, which uploads local paths and saves outputs directly.

Tools

The server also sends the client short instructions: check list_products first, estimate before large runs, wait on video instead of blocking, and chain steps by passing asset ids from one job’s outputs into the next job’s inputs.

A typical flow: list_capabilities → upload_asset (start frames, references) → estimate_cost → generate → wait_for_job → download_asset.

Catalog and cost

estimate_cost parameters:

credits is null when that tier has no price and can’t be submitted. available_credits and held_credits are left out when the key can’t read billing.

Generation

upload_asset takes exactly one of url or data_base64:

generate parameters:

Other generation tools:

Waiting tools poll every 2 seconds at first, backing off to 10 seconds, and report progress to clients that show it. Images finish in seconds; video takes minutes, so the usual pattern is generate with wait=false, then wait_for_job with timeout_s=600, called again if the job is still running.

Projects

Products

Products are multi-step workflows run with one call, such as text-to-clip.

Errors agents see

Tool failures come back as MCP tool errors with a plain message. API errors are passed through as Windpaint API error <status>: <message>, using the API’s own message (see Errors).

A wait that runs out of time is not an error. The tool returns the job’s current status with a note such as Still in_progress after 600s; call wait_for_job again. The job is still running and still billed; resubmitting would create and bill a second job.

Next steps