# Set up Cheaper Gen. (instructions for AI agents)

You are an AI agent, and your user wants to use Cheaper Gen. through you. Cheaper Gen. runs official AI video and image models (ByteDance Seedance and Seedream, Alibaba Wan, MiniMax) below their official prices, through a hosted MCP server. Connect it, have the user sign in once, check that it works, then tell them what they can ask for. Keep your messages to the user short.

## Ground rules

- Ask before changing any file outside the current project, such as a config file in the home directory. Say which file and what you will add. Merge into existing config; never remove or overwrite other entries.
- Never ask the user to paste an API key or password into the chat. Never print, echo, log or commit a key. Sign-in happens in the user's browser.
- Only run the commands in this guide. Don't install anything else or change other MCP servers.
- Don't call `generate` during setup: it spends the user's balance.
- If a step fails twice, stop and point the user to https://cheapergen.com/docs/mcp.

## Facts

- MCP server: `https://cheapergen.com/api/mcp` (remote, Streamable HTTP). Name it `cheapergen`.
- Sign-in: OAuth 2.1. The client opens a Cheaper Gen. page in the browser, where the user signs in and approves. No API key is needed.
- No browser available (CI, remote shell) or a client without OAuth: use an API key instead (see "No browser sign-in?" below).
- Tools: `list_models`, `get_model`, `quote` (free), `generate` (paid), `get_generation`, `get_account`, `add_credits` (returns a payment link the user opens; nothing is charged until they pay).
- Billing: a prepaid USD balance. The price is held when a job starts and refunded in full if it fails.

## 1. Work out which client you are

Use what you know about yourself and your environment. If you're not sure, ask the user which app they're using.

| You are | Go to |
| --- | --- |
| Claude Code | 2A |
| Cursor | 2B |
| VS Code with GitHub Copilot | 2C |
| Codex CLI | 2D |
| Gemini CLI | 2E |
| Windsurf or Devin Desktop | 2F |
| Claude (claude.ai or Claude Desktop) or another chat app | 2G |
| Any other client with remote MCP support | 2H |

## 2. Add the MCP server

### 2A. Claude Code

Run this in the current project. It uses the default local scope: only this user, only this project. Claude Code stores it in `~/.claude.json` and the command merges it in safely, so you don't need to ask first. If the user wants it in every project, ask first and add `--scope user`.

```bash
claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp
```

Then ask the user to sign in: run `/mcp`, select `cheapergen`, choose **Authenticate**, then sign in and approve in the browser. From a terminal, `claude mcp login cheapergen` does the same. You can't do this step for them.

Alternatively, the plugin adds the server and the Agent Skill in one step, for every project (ask first, and then skip `claude mcp add`). The user can type `/plugin marketplace add CheaperGen/skills` and `/plugin install cheapergen@cheapergen`, or you can run:

```bash
claude plugin marketplace add CheaperGen/skills
claude plugin install cheapergen@cheapergen
```

Sign-in works the same; the server shows up as `plugin:cheapergen:cheapergen`.

### 2B. Cursor

Add this to `~/.cursor/mcp.json` (all projects; ask first) or `.cursor/mcp.json` (this project), merged into any existing `mcpServers`:

```json
{
  "mcpServers": {
    "cheapergen": {
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}
```

Then ask the user to sign in: in Cursor, open **Customize → MCPs** (older versions: Settings → MCP) and connect `cheapergen`. In the Cursor CLI, run `agent mcp login cheapergen` (older versions: `cursor-agent mcp login cheapergen`).

### 2C. VS Code (GitHub Copilot)

Add this to `.vscode/mcp.json`, merged into any existing `servers`:

```json
{
  "servers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}
```

VS Code asks the user to sign in the first time the server starts. The tools work in Copilot Chat's agent mode.

### 2D. Codex CLI

This writes to `~/.codex/config.toml` (all projects), so ask first. It then opens the browser for sign-in right away and waits until the user approves. If your sandbox can't write `~/.codex`, or nobody is at the browser, give the user the command to run in their terminal instead.

```bash
codex mcp add cheapergen --url https://cheapergen.com/api/mcp
```

If the sign-in was skipped or fails, the user runs `codex mcp login cheapergen`.

### 2E. Gemini CLI

```bash
gemini mcp add --transport http cheapergen https://cheapergen.com/api/mcp
```

This writes `.gemini/settings.json` in the project; add `-s user` for every project (ask first). Gemini loads project servers only in trusted folders: if `gemini mcp list` shows `cheapergen` as disabled, ask the user to trust the folder (Gemini asks on start, or use `/permissions`). Then ask the user to run `/mcp auth cheapergen` and sign in in the browser.

### 2F. Windsurf or Devin Desktop

Add this to the MCP config, merged into any existing `mcpServers` (ask first). Devin Desktop: `~/.config/devin/mcp_config.json` on macOS and Linux, `%APPDATA%\devin\mcp_config.json` on Windows. Older Windsurf versions: `~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "cheapergen": {
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}
```

Then refresh the MCP servers and sign in when asked.

### 2G. Claude and other chat apps

You can't add connectors yourself. Tell the user:

1. In Claude, open **Customize → Connectors** and add a custom connector. In other apps, look for custom connectors or MCP servers.
2. Name it `Cheaper Gen` and paste `https://cheapergen.com/api/mcp`.
3. Choose **Connect**, sign in to Cheaper Gen. and approve. Then turn it on in the chat's tools menu.

### 2H. Any other MCP client

Clients with remote (HTTP) servers only need the URL. Some use `serverUrl` instead of `url`.

```json
{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}
```

Clients that only run local (stdio) servers can use the `mcp-remote` bridge, which needs Node.js and handles the sign-in:

```json
{
  "mcpServers": {
    "cheapergen": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cheapergen.com/api/mcp"
      ]
    }
  }
}
```

### No browser sign-in? Use an API key

Only when OAuth isn't possible:

1. Ask the user to create a key at https://cheapergen.com/dashboard/keys and set it themselves as the `CHEAPERGEN_API_KEY` environment variable. Don't ask for the key in the chat.
2. Point the config at the variable, never at the literal key. Keep the single quotes below: they store the variable's name, and the client reads its value when it connects.

```bash
# Claude Code
claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  --header 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'

# Codex CLI (no browser sign-in when a token variable is set)
codex mcp add cheapergen --url https://cheapergen.com/api/mcp \
  --bearer-token-env-var CHEAPERGEN_API_KEY

# Gemini CLI
gemini mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  -H 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'
```

JSON configs, such as a project `.mcp.json` in Claude Code. Cursor, VS Code and Devin write the variable as `${env:CHEAPERGEN_API_KEY}` instead.

```json
{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CHEAPERGEN_API_KEY}"
      }
    }
  }
}
```

## 3. Optional: install the Agent Skill

Only if the user writes code that calls the Cheaper Gen. REST API. The skill teaches that API, and it prefers the MCP tools when they're connected. Ask first.

```bash
npx skills add CheaperGen/skills
```

The skills CLI installs into Claude Code, Cursor, Codex, Gemini CLI and other agents. In Claude Code, `npx skills add CheaperGen/skills -a claude-code --skill cheapergen -y` skips the questions. Or download the file directly:

```bash
# This project
mkdir -p .claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o .claude/skills/cheapergen/SKILL.md

# Every project
mkdir -p ~/.claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o ~/.claude/skills/cheapergen/SKILL.md
```

## 4. Check that it works

You can check the config itself with `claude mcp get cheapergen`, `codex mcp list` or `gemini mcp list`. Until the user signs in, they show "Needs authentication", "Not logged in" or "Disconnected". That's expected.

New MCP servers often load only in a new session. If you can't see the `cheapergen` tools yet, tell the user to restart or reload their client (or start a new chat) and then ask you to "check Cheaper Gen". Stop there.

When the tools are available:

1. Call `get_account`. If it says sign-in is required, ask the user to finish the browser sign-in from step 2.
2. Call `list_models` and count the video and image models.

Don't call `generate`.

## 5. Tell the user they're set

Send one short message, for example:

> Cheaper Gen. is connected. Your balance is $X.XX. You can now ask me things like:
> - "Make a 5-second 720p clip with Seedance 2.0 Fast of a paper boat drifting down a rainy neon street. Tell me the price first."
> - "Make four product shots of this photo with Seedream 5.0 Lite: <image URL>"
> - "Which video models accept reference videos, and what would 5 seconds at 720p cost on each?"
>
> I'll show you the price before anything runs, and failed runs are refunded automatically.

If the balance is 0, add: "Add credits at https://cheapergen.com/dashboard/billing first."

## Later, when you generate

- Call `quote` first and tell the user the price. For anything expensive (1080p or 4K, long clips, many images), wait for a yes, and pass `max_cost_usd` to `generate`.
- Videos take one to several minutes: after `generate`, call `get_generation` with `wait_seconds` until the status is `succeeded` or `failed`.
- Output links expire after one day by default. Tell the user to download what they want to keep.

More: https://cheapergen.com/docs/mcp · https://cheapergen.com/llms.txt · https://cheapergen.com/skills/cheapergen/SKILL.md