How to Add the VdoBloom MCP Server to Codex and Other MCP Clients

Add VdoBloom to Codex by putting a [mcp_servers.vdobloom] block in ~/.codex/config.toml with url = "https://vdobloom.com/mcp" and a bearer token read from an environment variable. Any other MCP client that speaks Streamable HTTP connects the same way: the same URL, plus an Authorization: Bearer vdb_... header or a sign-in.

Quick facts

• Server URL: https://vdobloom.com/mcp (Streamable HTTP, one JSON answer per request, no SSE stream).
• Auth: a personal API key starting with vdb_, made in Settings → Developer, or a sign-in for clients that support OAuth (Claude and ChatGPT connectors).
• Tools: 13, from list_models and generate_video to run_tool for every other VdoBloom tool.
• Limits: 120 requests and 20 generations per minute per account, across all keys together.
• Cost: you pay credits per generation, the same prices as the website. Default image model Nano Banana is 6 credits; the default video model, Seedance 2 Fast, is 24 credits for 5 seconds at 480p. No subscription is needed, and bought credits never expire.

Create your VdoBloom API key

What you need before you start

You need a VdoBloom account with some credits. New accounts get 10 credits on sign-up, which covers a few test images. For a video, top up first.

Then make a key:

1. Open Settings → Developer.
2. Tick the API terms box.
3. Create a key and copy it right away. It starts with vdb_ and is shown once.

Keep the key out of config files you share or commit. Every client below can read it from an environment variable instead. In your shell profile, add a line like export VDOBLOOM_KEY=vdb_your_key and open a new terminal.

Add VdoBloom to Codex

As of November 2026, OpenAI's Codex docs keep MCP servers in ~/.codex/config.toml, or in .codex/config.toml inside a trusted project if you want the server for one project only. A remote server takes a url and the name of an environment variable that holds the bearer token. Add this block:

[mcp_servers.vdobloom]
url = "https://vdobloom.com/mcp"
bearer_token_env_var = "VDOBLOOM_KEY"

Codex sends the value of VDOBLOOM_KEY in the Authorization header for you, so the file itself never holds the key. Start Codex again and ask it to "list the VdoBloom tools". You should see the 13 tools in the next section.

Codex also has a command-line route: codex mcp add vdobloom --url https://vdobloom.com/mcp registers the server, and codex mcp login vdobloom starts an OAuth sign-in. The token route above is the one we suggest for Codex, because it works the same in every terminal and on remote machines.

The 13 tools your client will see

Videos take 1-10 minutes. The server tells the model to poll get_status every 30-60 seconds and to share the video link when the job completes. Result links are temporary, so download anything you want to keep.

Add VdoBloom to Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Its docs show headers with an environment variable, which keeps the key out of the file:

{
  "mcpServers": {
    "vdobloom": {
      "url": "https://vdobloom.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VDOBLOOM_KEY}"
      }
    }
  }
}

Reload Cursor and check that the server shows as connected in its MCP settings.

Claude Code, the Claude app and ChatGPT

Claude Code takes one line:

claude mcp add --transport http vdobloom https://vdobloom.com/mcp \
  --header "Authorization: Bearer vdb_your_key"

In the Claude app and in ChatGPT, add https://vdobloom.com/mcp as a custom connector and sign in to VdoBloom when asked. There is no key to paste: the sign-in creates one for that app. Our guide to generating images and video from Claude or ChatGPT walks through those screens.

Any other MCP client

If your client is not listed, look for these settings:

• Transport: "Streamable HTTP" or "HTTP". Pick that, not "stdio" or "SSE".
• URL: https://vdobloom.com/mcp.
• Header: Authorization: Bearer vdb_.... If the client supports OAuth instead, leave the header out. A request without a key gets a 401 that points the client to the sign-in.

The server supports MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05. It is stateless: no session ids, and GET or DELETE on the URL answer 405. That is normal and not an error in your setup.

How to do it on VdoBloom: your first job from a terminal agent

1. Make a key in Settings → Developer and export it as VDOBLOOM_KEY.
2. Add the server to your client with one of the snippets above and restart it.
3. Ask: "Check my VdoBloom balance and list video models with prices."
4. Ask for one image first, for example "Generate a 16:9 image of a rainy neon street at night with Nano Banana." It usually comes back in the same reply. To see the result first in the browser, try this prompt on Nano Banana.
5. Then ask for a 5-second image-to-video clip from that image. The agent starts the job and checks it until the video link is ready.
6. For tools outside the main six, such as the video upscaler or video effects, ask the agent to find them with list_tools and estimate the price before running.

Each connected app shows up as a key in Settings → Developer. Revoke it there to disconnect.

Read the full developer docs

Common errors and fixes

• 401 unauthorized: the key is missing, mistyped or revoked. Check that the environment variable is set in the shell that started the client.
• 402 insufficient credits: the message states the cost. Top up on the pricing page or pick a cheaper model or resolution.
• 429 rate limited: over 120 requests or 20 generations in a minute. Agents that poll too fast hit this; ask yours to wait 30-60 seconds between checks.
• "Image must be a public URL": tools take links. For a file on your computer, ask the agent to call create_upload, open the link it gives you, pick the file, then let it fetch the file_url. Limits are 10 MB for images, 100 MB for videos and 25 MB for audio, and the upload link works once for about 15 minutes.

For a non-MCP setup, the same key also works with the REST API described on the developers page.

Try image to video in the browser

FAQ

Does Codex need a feature flag to use remote MCP servers?

As of November 2026, OpenAI's Codex MCP docs do not list one for this setup. Add the config block and restart Codex.

Can I use the same key in several clients?

Yes. All keys on one account share the rate limits and the credit balance. Making one key per client makes it easy to revoke one without touching the others.

Which video model does the agent use if I do not name one?

Seedance 2 Fast. Ask the agent to run list_models with type video to see Kling, Veo, Wan, Hailuo and the rest with their prices, then name the one you want.

Is my key stored in the config file?

Not with the snippets above. Codex reads it from bearer_token_env_var and Cursor from ${env:...}. Only the Claude Code one-liner writes the key into its own config, so treat that machine's config as private.

Do generations made through MCP show up in my account?

Yes. They use your credits and appear in your creations, and the agent can list them with list_creations.

Related reading: How to make AI videos with ChatGPT or Claude, Seedance 2 Fast pricing and image-to-video best practices.