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

Tool	What it does	Scope
list_models	Discover all image/video models	(public)
get_credits	Check remaining credit balance	kairogen:read
estimate_cost	Preview the credit cost before generating	(public)
generate_image	Generate one or more images. Blocks until done (default 10 min).	kairogen:generate
generate_video	Generate a video (text-to-video or image-to-video). Blocks until done (default 15 min).	kairogen:generate
upscale_image	Upscale an image 2x or 4x with Topaz Photo AI	kairogen:generate
get_generation	Poll the status of a previous generation	kairogen:read

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):

Var	Default	Purpose
KAIROGEN_API_BASE	https://api.kairogen.ai	Override for staging or self-hosted
KAIROGEN_ISSUER	https://api.kairogen.ai	OAuth issuer base URL
KAIROGEN_CLIENT_ID	kairogen-mcp	Pre-registered OAuth client id
KAIROGEN_API_KEY	(empty)	Override OAuth and use a static token (CI / headless)
KAIROGEN_CONFIG_DIR	~/.kairogen	Where to cache OAuth tokens

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:

Var	Required	Purpose
OAUTH_JWT_PRIVATE_KEY	yes (prod)	RSA PEM. Generate with openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048.
OAUTH_ISSUER	recommended	Default https://api.kairogen.ai. Must match what MCP server expects.
OAUTH_AUDIENCE	recommended	Default kairogen-api. Must match what MCP server expects.
OAUTH_WEBSITE_DOMAIN	yes	Origin of the frontend hosting /oauth/consent and /device. Default https://app.kairogen.ai. In dev, override to http://localhost:3000 (or wherever your Nuxt dev server runs) or the consent endpoints will 403.
OAUTH_INTROSPECTION_SECRET	optional	32+ char random string. Empty value disables /oauth/introspect.
CORS_ORIGINS	yes (prod)	Comma-separated allowlist of origins. Empty in production now refuses all cross-origin requests. Set to https://app.kairogen.ai (plus any other UI origins) to allow the consent page.

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

• [x] v0.1 stdio + sAccessToken paste (deprecated)
• [x] v0.2 OAuth device flow on stdio first run
• [x] 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