Skip to content

Overlume MCP

The Studio, inside your agent.

Overlume ships a Model Context Protocol server. Connect Claude, Cursor, or any MCP client and your agent can browse your library, price a render before spending, and generate images, video clips, and voiceovers with your lumens. Available on every plan, including free.

Connect in three steps

  1. Step 1

    Create a token

    In the app, open Account → Connected apps (MCP). Name a token and copy it right away: it starts with olm_ and is shown exactly once. You can revoke it from the same panel at any time.

  2. Step 2

    Add the server

    Point your client at http://localhost:3001/api/mcp with the token as a bearer header. The exact commands for Claude Code, Claude Desktop, and generic clients are below.

  3. Step 3

    Ask your agent

    “Check my lumen balance.” “Render a 9:16 product image.” Every generate tool accepts dryRun: true to preview the exact lumen cost before anything is spent.

Claude Code

One command in your terminal. This is the whole CLI setup.

claude mcp add --transport http overlume http://localhost:3001/api/mcp \
  --header "Authorization: Bearer olm_YOURTOKEN"

Cursor and other HTTP clients

Drop this block into your client’s MCP settings file.

{
  "mcpServers": {
    "overlume": {
      "url": "http://localhost:3001/api/mcp",
      "headers": { "Authorization": "Bearer olm_YOURTOKEN" }
    }
  }
}

Claude Desktop and other stdio-only clients

Bridge to the HTTP endpoint through mcp-remote.

{
  "mcpServers": {
    "overlume": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:3001/api/mcp",
        "--header", "Authorization: Bearer olm_YOURTOKEN"
      ]
    }
  }
}

Eleven tools, two kinds

Read tools are free to call. Generate tools spend lumens at the same rates as the app; live per-model prices come from list_models so they never drift from what you would pay in the Studio.

Read

Free to call

  • get_capabilities

    Start here: server overview, tool directory, how lumens work, current balance.

  • get_balance

    Your lumen balance plus reference prices and a top-up link.

  • list_models

    Every model your account can run: id, kind, lumen price, speed, quality, aspects.

  • list_voices

    Curated voice presets plus your own clones; ids feed generate_voiceover.

  • list_templates

    Ad templates available on your plan.

  • list_assets

    Your recent generations, newest first, with fresh 24-hour signed URLs.

  • get_job_status

    Poll async renders: status, error, signed URL, lumens spent.

Generate

Spends lumens · dryRun previews cost

  • generate_image

    Text to image, up to 4 at once, with optional reference images from your library.

  • generate_video

    Image to video from a first frame in your library; async, poll with get_job_status.

  • generate_voiceover

    A script spoken verbatim in any voice from list_voices, up to 3 takes.

  • upscale_image

    Upscale one of your ready images up to 4x.

The fine print, up front

Transport
Streamable HTTP. One endpoint, no SSE fallback needed.
Auth
Personal access tokens, sent as Authorization: Bearer olm_… on every call. Stored as a hash, shown once at creation, revocable anytime.
Scopes
read (lists, status, balance) and generate (anything that spends lumens).
Limits
120 tool calls per hour per token. Up to 10 active tokens per account.
Costs
Read tools are free. Generation spends lumens at the same rates as the app; pass dryRun: true to any generate tool for the exact cost with zero spend.
Availability
Every plan, including free. No separate API tier, no extra fee.

Questions developers ask

What is the Overlume MCP server?

MCP (Model Context Protocol) is the open standard AI assistants use to call outside tools. Overlume exposes its Studio through an MCP server, so an agent like Claude can check your balance, browse your library, and render images, clips, and voiceovers on your account without you opening the app.

Does it cost extra?

No. Connecting is free on every plan, read tools are free to call, and generation spends lumens at exactly the same rates as the app. Every generate tool accepts a dry-run flag that returns the precise cost without spending anything.

Which clients work today?

Claude Code connects with one command, Claude Desktop connects through the mcp-remote bridge, and Cursor or any other client that speaks MCP over HTTP works with the standard config block. Hosted claude.ai connectors need an OAuth flow we have not shipped yet.

Is there a CLI to install?

No separate install. The claude mcp add command wires the server into Claude Code directly, and other clients take the JSON config. Your terminal agent becomes the CLI.

How do I revoke access?

In the app, open Account and find Connected apps (MCP). Every token is listed with its last-used date; revoking one cuts that client off immediately.

Is my token safe?

Tokens are stored as a hash and displayed exactly once, at creation. Every request must carry the bearer header, failed auth returns nothing about why, and calls are rate limited per token. Treat a token like a password and revoke any you no longer use.

Create your token

Account → Connected apps (MCP)