Guides

MCP server

rodiumai-mcp plugs the RodiumAI API into your AI assistant. You describe what you want, it picks a suitable model, runs it with your own API key and saves the result on your computer.

What it is

MCP (Model Context Protocol) is the standard way for an AI assistant to use outside tools. rodiumai-mcp is a small server that runs on your computer, next to your assistant, and gives it 12 tools backed by the RodiumAI API: images, video, speech, transcription, embeddings, any chat model, the model catalogue, your wallet and these docs.

No account sign-in. The server only needs your rd_sk_ API key. It never sees your RodiumAI password and has nothing to do with your dashboard session.
Nothing is stored on RodiumAI servers. Generated files are saved in a folder on your machine (~/RodiumAi/generated by default).
It runs locally over stdio. There is no URL to configure and no endpoint to expose.
Free to install. You only pay, in RODI, for the generations you ask for, at the usual model prices.

No need to know model ids

Name a model if you care (nano banana pro, gpt-image-2, veo 3.1 fast), or say what matters (cheapest, best) and the server chooses. Every result tells you which model was used.

Before you start

Node.js 22 or newer. The server is started with npx, which comes with Node.js. Check with node --version.
An API key. Create an rd_sk_ key in Dashboard → API keys. See Authentication for how keys work.
Some RODI in your wallet. Top up by Mobile Money in Dashboard → Billing. Listing models, reading the docs and checking your wallet are free.

Install in your assistant

The server is published on npm as rodiumai-mcp. There is nothing to install by hand: your assistant starts it through npx the first time. Replace rd_sk_YOUR_KEY with your own key.

Claude Desktop. Open Settings, Developer, Edit Config, and add the server to claude_desktop_config.json, then restart Claude Desktop. Cursor uses the same entry in .cursor/mcp.json (this project) or ~/.cursor/mcp.json (all projects).

claude_desktop_config.json or .cursor/mcp.json

…

Claude Code. One command, from any terminal:

…

VS Code. Add this to .vscode/mcp.json. VS Code asks for the key when the server starts, so it never sits in a file.

.vscode/mcp.json

…

On Windows

If your client cannot start npx directly, use the cmd /c form shown below as the server entry.

Windows fallback

…

Check that it works

Run this in a terminal at any time. It tests your key, reads your wallet, loads the model catalogue and the docs index, and spends nothing. It never prints your key.

…

Then restart your assistant and look for the rodiumai server in its tools list. If it is missing, see Troubleshooting.

What you can ask

Just talk to your assistant. It calls the right tool and shows you the result.

You say	What happens
"Generate an image of a red fox in the snow with Nano Banana Pro."	The image appears in the chat and is saved to your output folder.
"Make an 8 second video of a paper boat on a pond, with Veo."	The assistant checks the cost with you first, then renders in the background and saves the clip.
"Transcribe ~/Downloads/meeting.m4a in French."	The audio file is transcribed and the text comes back in the chat.
"Read this paragraph aloud."	An audio file is generated and saved.
"Ask Gemini what it thinks of this approach."	The prompt goes to another model, and the answer comes back with the cost.
"How do I edit an image through the RodiumAI API?"	It reads the real docs and answers from them, with working code.
"How much RODI do I have left?"	It shows your balance and what this session has spent.

Example

…

The 12 tools

Tool	What it does	Costs RODI
generate_image	Create or edit images. Nano Banana 2 by default, Nano Banana Pro for best quality, GPT Image on request. Images are shown and saved to disk.	Yes
generate_video	Start a video with Veo 3.1 (Fast by default, Lite for the cheapest, full for best), from text or from an image. Runs in the background and is saved to disk. Billed per second, so the assistant asks you first.	Yes
get_video	Check a video in progress, or list this session's videos.	No
text_to_speech	Turn text into an audio file.	Yes
transcribe_audio	Transcribe a local audio file (mp3, mp4, m4a, wav, webm, ogg, flac, up to about 10 MiB).	Yes
embed_text	Create embedding vectors, saved to a JSON file.	Yes
ask_model	Send a prompt to any text model, or let RodiumAI route it by priority.	Yes
list_models	The catalogue with prices, tiers and rate limits, filtered by task or provider.	No
recommend_model	Which model the server would use for a task, and why.	No
get_wallet	Your spendable RODI balance and what this session has spent.	No
search_docs	Search the RodiumAI documentation.	No
read_doc	Read a docs page as markdown. The same pages are also exposed as MCP resources.	No

How a model is chosen

If you name a model or a nickname, it is used: nano banana, nano banana pro, a full id such as google/gemini-3-pro-image, or a unique part of a name. A name that matches several models is refused with the candidates listed, and a model that cannot do the task is refused with what it is for.
Otherwise the server picks from the live catalogue by task and priority, as in the table below. balanced is the default.

Task	cheapest	balanced (default)	best
Image	Nano Banana 2 Lite	Nano Banana 2	Nano Banana Pro
Video	Veo 3.1 Lite	Veo 3.1 Fast	Veo 3.1
Speech	Gemini 2.5 Flash TTS	GPT-4o mini TTS	Gemini 2.5 Pro TTS
Transcription	GPT-4o mini transcribe	GPT-4o mini transcribe	GPT-4o transcribe
Embedding	text-embedding-3-small	text-embedding-3-small	text-embedding-3-large
Chat	`rodium/basic`	`rodium/auto`	`rodium/max`

If a preferred model is unavailable, the server falls back to the best match in the live catalogue. For chat it uses the RodiumAI routing profiles described in Smart routing.

Costs and safeguards

Every paid call reports about how much RODI it used, measured from your wallet before and after, plus the total for the session. The API itself does not return an amount, so the figure is an observation and can be off if something else spends from the same wallet at the same moment. To give a sense of scale, measured in October 2026 with the default models (prices can change, see each model page):

Call	About
One 1024x1024 image, Nano Banana 2 Lite	25 RODI
A 4 second video, Veo 3.1 Lite	198 RODI
53 characters of speech, gpt-4o-mini-tts	1 RODI
A short transcription, gpt-4o-mini-transcribe	0.2 RODI
One embedding, text-embedding-3-small	0.1 RODI

Spend limit. The default is 1000 RODI per server session, and new paid calls stop once it is reached. Raise it with RODIUMAI_MCP_MAX_SPEND, or set it to off. If you plan several videos, raise it.
Ask first for video. The price per second is only on each model page, not in the API, so the assistant must ask you before it starts a video.
Your key stays put. It lives in the server's environment and is never put in tool results or error messages. Plain http base URLs are refused, so the key is never sent unencrypted (localhost is the only exception).
Only audio and images are read from disk, checked on the real path and size limited, so a hostile prompt cannot use transcribe_audio or image references to upload other files.
Untrusted text stays data. Text from other models, transcripts and documents is treated as data, and the server tells the assistant not to follow instructions found inside it.

About video

The RodiumAI video endpoint is synchronous: the request stays open until the clip is ready, which can take up to about ten minutes (see Video generation). generate_video therefore runs the request in the background and returns a job id, unless the clip is ready within wait_seconds. Ask for the status at any time and get_video reports progress.

The API returns the video as base64 inside the response, with no link. The server saves it to your output folder. If a model ever answers with a link instead, it is downloaded without any credentials, so your key is never sent to another host.
Jobs live in the server process, so they are lost if you close the assistant while a video is still being generated (the request may already have been billed).
Video models have low rate limits, so at most two videos run at once.

Configuration

All settings are environment variables, set in the env block of the server entry.

Variable	Default	Meaning
RODIUMAI_API_KEY	none	Your `rd_sk_` key. Without it the docs and model listing still work, generation does not.
RODIUMAI_MCP_MAX_SPEND	1000	Spend limit per server session, in RODI. `off` removes it.
RODIUMAI_MCP_OUTPUT_DIR	~/RodiumAi/generated	Where images, audio, video and embeddings are saved.
RODIUMAI_BASE_URL	https://api.rodiumai.io/v1	API base URL. Must be https, except for localhost.
RODIUMAI_DOCS_URL	https://www.rodiumai.io	Site that serves the docs.

What leaves your machine

Prompts, text to speak, audio and reference images are sent to the RodiumAI API, and from there to the provider of the model you chose. Docs pages are fetched from www.rodiumai.io. There is no telemetry and no other network traffic.

Troubleshooting

Symptom	What to do
The tools do not show up	Restart the client fully. Run `npx rodiumai-mcp --check` in a terminal to see what is wrong.
`RODIUMAI_API_KEY is not set`	Add the key to the `env` block of the server configuration, then restart the client.
`401` or "API key was rejected"	The key is revoked or mistyped. Create a new `rd_sk_` key in Dashboard → API keys.
"The wallet does not hold enough RODI"	Top up from Dashboard → Billing.
`Spend ceiling reached`	The session hit its limit. Raise `RODIUMAI_MCP_MAX_SPEND` and restart the server.
`429` or rate limit	The model's per-key limit was reached, wait a moment or choose another model. Video models are the strictest. See Rate limits.
The client cannot start `npx` on Windows	Use the `cmd /c npx` entry shown in Install.

Learn more

rodiumai-mcp on npm
Under the hood the tools call the Images, Videos, Transcriptions, Speech and Embeddings endpoints. The same calls work from your own code.
Costs and wallet: Pricing & billing. Failures: Error handling.