# Kairogen MCP

Model Context Protocol server for [Kairogen](https://kairogen.ai). 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`)

```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

```bash
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)

```json
{
  "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

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

```bash
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)

```bash
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