Agents

MCP server

Kinoseed is a remote MCP server, so any agent that speaks the Model Context Protocol can list the models, price a run, generate images and video, and follow the job, with your key and your credits.

Connection

Setting	Value
Server URL	https://kinoseed.app/api/mcp
Transport	Streamable HTTP (POST)
Header	Authorization: Bearer ks_live_YOUR_KEY
Or this header	X-Kinoseed-Key: ks_live_YOUR_KEY
Server card	https://kinoseed.app/api/mcp/server-card

The key is an ordinary API key from your account page; see Authentication. Give the agent a key with only the scopes it needs, and revoke it when you are done. Send it in X-Kinoseed-Key instead when a client cannot set the Authorization header; never put it in the URL.

Without a key the server still answers initialize and tools/list, so a client or a directory can see the tools before you connect an account. Calling any tool needs the key and answers 401 without one. The tool list is also published as a static card at https://kinoseed.app/.well-known/mcp/server-card.json.

Tools

Six tools, each the MCP face of a REST operation, with the same inputs, prices and errors.

Tool	What it does	Arguments	REST
list_models	The model catalog: ids, inputs, aspects, durations and an example price in credits.	kind? (image \| video \| edit)	listModels
get_credits	The balance behind the key and the plan, if any.	none	getCredits
quote	What a run would cost, without starting it. Call it before every generate.	the generate_image or generate_video arguments plus kind	quote
generate_image	Start an image run. Waits for the result by default and returns the image URLs.	prompt, model?, aspect?, count?, referenceImageUrls?, seed?, wait?, idempotency_key?	createImage
generate_video	Start a video run. Returns the job at once by default; follow it with get_job.	prompt, model?, aspect?, duration?, resolution?, audio?, startImageUrl?, endImageUrl?, referenceImageUrls?, seed?, wait?, idempotency_key?	createVideo
get_job	One job, optionally held until it finishes.	id, wait_seconds?	getJob

generate_image waits for the images by default and returns their URLs. generate_video returns the job at once; call get_job with wait_seconds until it is final.
Retrying a generate call after a timeout never starts a second run. Identical calls within 10 minutes return the same job (the result starts with Replayed:); pass idempotency_key to control this for 24 hours, the way Idempotency-Key does on REST, or change the prompt to force a new run.
Results are URLs, never inline base64, so a long clip does not flood the context window.
A business error (no credits, a bad model id) is a tool result with isError: true carrying the same error envelope as REST, so the agent can read the code and act.

Setup

Claude Code

One command in a terminal

claude mcp add --transport http kinoseed https://kinoseed.app/api/mcp --header "Authorization: Bearer ks_live_YOUR_KEY"

Add --scope project to write it to the repository's .mcp.json instead (keep the key in an environment variable there, not in the file).

Claude Desktop

Settings, Developer, Edit config (claude_desktop_config.json)

{
  "mcpServers": {
    "kinoseed": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://kinoseed.app/api/mcp",
        "--header",
        "Authorization:${KINOSEED_AUTH}"
      ],
      "env": {
        "KINOSEED_AUTH": "Bearer ks_live_YOUR_KEY"
      }
    }
  }
}

The custom connector dialog (Settings, Connectors, Add custom connector) asks for a URL and signs in with OAuth, which Kinoseed does not offer yet. Until it does, the config above bridges the same server through mcp-remote with your key in the header. Restart Claude Desktop after saving.

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project)

{
  "mcpServers": {
    "kinoseed": {
      "url": "https://kinoseed.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ks_live_YOUR_KEY"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "kinoseed": {
      "serverUrl": "https://kinoseed.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ks_live_YOUR_KEY"
      }
    }
  }
}

OpenClaw

The mcpServers block of your OpenClaw config

{
  "mcpServers": {
    "kinoseed": {
      "transport": "streamable-http",
      "url": "https://kinoseed.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ks_live_YOUR_KEY"
      }
    }
  }
}

Any client that speaks streamable HTTP works the same way: the URL above and the Authorization header.

Smithery and other gateways

Any client or gateway that cannot set the Authorization header

{
  "mcpServers": {
    "kinoseed": {
      "url": "https://kinoseed.app/api/mcp",
      "headers": {
        "X-Kinoseed-Key": "ks_live_YOUR_KEY"
      }
    }
  }
}

Send the same key without the Bearer prefix in X-Kinoseed-Key. It is checked exactly like the Authorization header. Never put a key in the URL: query strings end up in logs.

OpenAI API (Responses)

The mcp tool of a Responses API call (Python SDK shown)

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "kinoseed",
        "server_url": "https://kinoseed.app/api/mcp",
        "headers": {"Authorization": "Bearer ks_live_YOUR_KEY"},
        "require_approval": "always",
    }],
    input="What does a 5-second Kling 3.0 clip cost on Kinoseed? Quote it, do not generate.",
)
print(response.output_text)

The ChatGPT app's connector dialog offers OAuth or no sign-in, and cannot send an API key or a custom header, so it cannot connect to Kinoseed yet. The OpenAI API can: its mcp tool takes headers. Keep require_approval on so every generate call waits for you.