Kairogen MCP

Model Context Protocol server for Kairogen. Connect Claude, Cursor, ChatGPT (custom connectors), Hermes, OpenClaw, or any MCP-compatible agent and generate images and videos using Kairogen's full model catalog (Seedream, Flux, Nano Banana, GPT Image, Sora, Veo, Kling, Seedance, KairoClone, Topaz).

Authentication is OAuth 2.0. No API keys to copy or rotate.

Connect in 30 seconds

Claude.ai (Custom Connector)

1. Settings → Connectors → Add custom connector

2. URL: https://mcp.kairogen.ai/mcp

3. Click Connect → sign in with Kairogen → approve

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "kairogen": {
      "url": "https://mcp.kairogen.ai/mcp"
    }
  }
}

Restart Cursor and click Connect when prompted.

ChatGPT (Custom Connector)

Settings → Connectors → New custom connector → paste https://mcp.kairogen.ai/mcp. Sign in when ChatGPT prompts.

Claude Code

claude mcp add --transport http kairogen https://mcp.kairogen.ai/mcp

The --transport http flag is required for remote OAuth-protected MCP servers. Without it, the CLI assumes stdio and tries to exec the URL as a local binary.

Hermes / OpenClaw / NemoClaw (chat-only agents)

Paste this prompt into the agent:

Connect the Kairogen MCP at https://mcp.kairogen.ai/mcp. It supports OAuth device flow,
discovery at https://mcp.kairogen.ai/.well-known/oauth-protected-resource. Run the device
flow and reply with: Authorize here: https://app.kairogen.ai/device?code=XXXX-XXXX. Then
poll the token endpoint until I authorize and confirm once it succeeds.

The agent will reply with a link. Open it, click Permitir acesso, you're connected.

Local stdio (Claude Desktop, headless dev, offline)

{
  "mcpServers": {
    "kairogen": {
      "command": "npx",
      "args": ["-y", "@kairogen/mcp"]
    }
  }
}

On first launch the CLI runs the OAuth device flow, opens your browser, and caches the tokens at ~/.kairogen/tokens.json with auto-refresh. No env vars required.

Tools

All generate_* tools support wait_for_completion: false to return the generation_id immediately and let you poll via get_generation. They emit MCP notifications/progress heartbeats every 5 seconds during the poll, so Claude Desktop / Cursor / etc. show a live progress indicator and the connection never times out mid-render.

Configuration

Environment variables (all optional, sensible defaults):

Local development

git clone https://github.com/kairogenai/kairogen-mcp.git
cd kairogen-mcp
npm install
npm run build

# stdio mode (with OAuth device flow on first run):
node dist/stdio.js

# remote HTTP mode (validates Bearer tokens against api.kairogen.ai/.well-known/jwks.json):
PORT=8080 node dist/http.js

Smoke test (no agent needed):

KAIROGEN_API_KEY=eyJ... node -e "
const init = JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2025-11-25',capabilities:{},clientInfo:{name:'smoke',version:'0'}}});
const initd = JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'});
const list = JSON.stringify({jsonrpc:'2.0',id:2,method:'tools/list'});
process.stdout.write(init+'\\n'+initd+'\\n'+list+'\\n');
" | node dist/stdio.js

Deploy (mcp.kairogen.ai)

fly launch --no-deploy --copy-config --name kairogen-mcp
fly secrets set \
  MCP_RESOURCE=https://mcp.kairogen.ai \
  OAUTH_ISSUER=https://api.kairogen.ai \
  OAUTH_AUDIENCE=kairogen-api \
  MCP_AUTH_SERVERS=https://api.kairogen.ai \
  KAIROGEN_API_BASE=https://api.kairogen.ai
fly deploy
fly certs add mcp.kairogen.ai

MCP_AUTH_SERVERS is required: it populates the authorization_servers field in /.well-known/oauth-protected-resource, which is how MCP clients discover where to run the OAuth flow. Comma-separated if you ever need multiple issuers.

Backend env vars the OAuth issuer needs

The auth server (kairogen-backend-development) needs these set in its own deploy environment:

DNS: point mcp.kairogen.ai (CNAME) to the Fly app hostname.

Architecture

• Frontend (kairogen-frontend-development) hosts the consent screens at /oauth/consent, /device, and /settings/connections.

• Backend (kairogen-backend-development) is the OAuth issuer. Mounts /.well-known/oauth-authorization-server, /.well-known/jwks.json, /oauth/authorize/approve, /oauth/token, /oauth/device_authorization, /oauth/device/approve, /oauth/connections.

• MCP server (this repo) is a Resource Server. Validates Bearer JWTs issued by the backend against the published JWKS, then proxies tool calls to api.kairogen.ai with the user's token.

Roadmap

• v0.1 stdio + sAccessToken paste (deprecated)

• v0.2 OAuth device flow on stdio first run

• v0.3 hosted Streamable HTTP at mcp.kairogen.ai

• v0.4 Resources (kairogen://models, kairogen://prompt-guide/{model})

• v0.5 Marketing Studio + Cinema Control flows as higher-level tools

License

MIT