MCP & AI agents

Use with AI agents#

Use the MCP server when you want an assistant to make media for you, for example in Claude Code or Cursor chat. Use the Agent Skill when an agent is writing code against the API. You can use both: the skill also tells agents to prefer the MCP tools when they are connected.

Server URL and sign-in#

• Transport: Streamable HTTP, stateless. It works with clients on both the 2025 and 2026-07-28 MCP protocol versions.
• Sign-in: OAuth 2.1, as in the MCP authorization spec. The first time a client connects, it opens a Cheaper Gen. page in your browser. Sign in and approve the app. Approved apps are listed under Dashboard → API keys → Connected apps, where you can disconnect them at any time.
• Headless and CI: send an API key instead, as Authorization: Bearer cg_live_…. See Use an API key.

Connect a client#

Claude (claude.ai and Claude Desktop)#

1. Open Settings → Connectors and choose Add custom connector.
2. Name it Cheaper Gen, paste the URL above, and choose Add.
3. Choose Connect, sign in to Cheaper Gen. and approve. Then enable the connector in a chat from the tools menu.

On Team and Enterprise plans, an owner may need to add the connector for the organization first. Connectors you add on claude.ai also show up in Claude Desktop.

Claude Code#

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

Then run /mcp, select cheapergen and choose Authenticate. Your browser opens to sign in and approve. Add --scope user to use it in every project. Or install the plugin, which adds the server and the Agent Skill in one step:

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

Cursor#

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Then, under Settings → MCP, choose Login next to cheapergen.

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

VS Code (GitHub Copilot)#

Add this to .vscode/mcp.json, or run MCP: Add Server… and pick HTTP. VS Code asks you to sign in the first time the server starts. Then use the tools in Copilot Chat's agent mode.

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

Other clients#

Clients with remote servers and OAuth only need the URL (some use "serverUrl" instead of "url"). Clients that only run local (stdio) servers can use the mcp-remote bridge, which needs Node.js and handles the sign-in.

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

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

Use an API key (headless, CI)#

Where nobody can sign in through a browser, send an API key from Dashboard → API keys. Create a separate key for each agent so you can revoke it on its own. Keep it in an environment variable, as below; Claude Code expands ${CHEAPERGEN_API_KEY} in a committed .mcp.json from each developer's environment.

claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  --header "Authorization: Bearer $CHEAPERGEN_API_KEY"

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

npx @modelcontextprotocol/inspector --cli https://cheapergen.com/api/mcp --transport http \
  --header "Authorization: Bearer $CHEAPERGEN_API_KEY" --method tools/list

Tools#

Every tool wraps the same code as the REST API (API reference), so prices, validation and errors match. Results are compact JSON. Output files also come back as resource links, so clients can show or download them.

Images usually finish within one generate call. Videos take one to several minutes, so the agent submits the job, then calls get_generation with wait_seconds until it's done. A finished generate returns:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "status": "succeeded",
  "endpoint": "bytedance/seedream-5.0-lite/text-to-image",
  "outputs": [
    "https://cdn.cheapergen.ai/outputs/gen_8c2QmX1nq0k4Lw7Z.png"
  ],
  "cost": {
    "amount_usd": 0.0303,
    "official_usd": 0.035,
    "saved_usd": 0.0047,
    "final": true
  },
  "created_at": "2026-10-16T09:12:43.545Z",
  "completed_at": "2026-10-16T09:12:49.058Z",
  "outputs_expire_at": "2026-10-17T09:12:49.058Z",
  "next": "Done. Show or download the output URLs before outputs_expire_at."
}

Example prompts#

• “Which Cheaper Gen. video models accept reference videos, and what would 5 seconds at 720p cost on each?”
• “Generate a 5-second 720p video with Seedance 2.0 Fast: a paper boat drifting down a rainy neon street, slow dolly-in. Tell me the price first.”
• “Make four product shots of this mug with Seedream 5.0 Lite, each under $0.05: https://example.com/mug.png”
• “Animate this photo into a 6-second vertical clip with Wan 3.0: https://example.com/portrait.jpg”
• “Reference-to-video with Seedance 2.0: @Image1 is the character, @Image2 the street; move the camera like @Video1. Here are the URLs: …”
• “What's my Cheaper Gen. balance, and how many 10-second 1080p Seedance 2.0 clips can I afford?”

Agent Skill#

The Cheaper Gen. skill is a single SKILL.md in the Agent Skills format. It teaches an agent the whole workflow: choose a model, read the schema, quote, submit, poll or verify webhooks, reference mentions, uploads, pricing and errors. Agents load it only when a task needs it. For REST calls it reads your key from CHEAPERGEN_API_KEY, and it prefers the MCP tools when they're connected. Its source is github.com/CheaperGen/skills.

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

npx skills add CheaperGen/skills

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

mkdir -p .claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o .claude/skills/cheapergen/SKILL.md

The skills CLI installs into Claude Code, Cursor, Codex, Gemini CLI and other agents (-a picks one, -g installs for all projects). In the Claude apps, zip the cheapergen folder and upload it as a custom skill.

Limits and billing#

• The same rate limits as REST apply per connected app or key (every MCP request counts), as does the per-account limit on generations in progress.
• The price is held when generate submits and refunded in full if the generation fails or is canceled. See Billing & credits.
• Generations made through MCP show up in your dashboard and in GET /api/v1/generations with source: "mcp".
• Sign-in tokens last an hour and the client refreshes them on its own. Disconnecting the app in the dashboard ends its access immediately.
• Output URLs are public and expire with your API retention setting (one day by default). Download what you want to keep.

Troubleshooting#

• The client says the server needs authentication: finish the sign-in it started (in Claude Code: /mcp → cheapergen → Authenticate). If you disconnected the app or haven't used it for 90 days, sign in again.
• The sign-in page says the app isn't registered, or the redirect doesn't match: remove the server from the client and add it again, so the client registers itself again.
• A tool call times out: lower wait_seconds. The generation keeps running either way; fetch it later with get_generation.
• invalid_request: the input doesn't match the endpoint's schema. The error names the field in param; ask the agent to call get_model first.