WaveSpeed MCP Server
The WaveSpeed MCP server lets an AI tool search the live model catalog, read a model’s real input schema, check prices, and run image, video, audio, and 3D models on your WaveSpeed account.
For one-click setup in Claude, ChatGPT, Cursor and VS Code, or a setup prompt to paste into Claude Code, Codex and other agents, see wavespeed.ai/mcp.
There are two ways to connect, with the same tools:
| Remote (URL) | Local (command) | |
|---|---|---|
| Address | https://api.wavespeed.ai/mcp | npx -y @wavespeed/mcp@latest |
| Runs on | WaveSpeed | Your computer |
| Sign in | OAuth in your browser, or an API key header | WAVESPEED_API_KEY, or wavespeed login |
| Good for | ChatGPT, Claude, Claude Code, Codex, Grok Bot, and other tools that add a server by URL | Claude Code, Codex, Claude Desktop, Cursor, Cline, and other tools that start a local command |
| Local files | Pass public URLs | "@./photo.jpg" is uploaded for you |
Remote server
The address is:
https://api.wavespeed.ai/mcpClaude
Works in Claude on the web and Claude Desktop. On a Pro or Max plan, open Customize → Connectors, choose Add, then Add custom connector. Enter a name and the address above, and approve the connection on the WaveSpeed page that opens. On Team and Enterprise plans an owner adds the connector in Organization settings → Connectors, and each member then connects individually. The Free plan allows one custom connector.
Claude Code also picks up the connectors you add to your Claude account.
ChatGPT
ChatGPT connects to remote servers only, which suits the address above. In ChatGPT on the web:
- Open Plugins, select the plus button, and choose Add custom MCP server.
- Enter a name, set the server URL to
https://api.wavespeed.ai/mcp(keep the/mcp), and choose OAuth for authentication. - Confirm the notice about connecting to a custom server, then create it. Approve the connection on the WaveSpeed page that opens.
- Review the tools ChatGPT found and install it. Install it before you start a chat; it is not available in conversations until then.
Custom MCP servers are available on selected ChatGPT plans, and a workspace can limit who may add them. See OpenAI’s help article for the current plans and menu names, which OpenAI changes from time to time. Older instructions ask you to turn on Developer Mode and use Apps → Create; that is the previous flow.
In a workspace where an admin has to approve the connection, ChatGPT keeps the tool list it saw at approval. When WaveSpeed adds tools, they appear after an admin reviews and publishes the update.
Claude Code
As a plugin, which adds the server and the WaveSpeed skill together:
claude plugin marketplace add WaveSpeedAI/claude-plugins
claude plugin install wavespeed@wavespeedThen run /mcp, pick wavespeed and approve the connection in your browser. Or add only the server:
# Sign in through your browser the first time you use it.
claude mcp add --transport http wavespeed https://api.wavespeed.ai/mcpOr skip the browser and use an API key:
claude mcp add --transport http wavespeed https://api.wavespeed.ai/mcp \
--header "Authorization: Bearer $WAVESPEED_API_KEY"Codex
As a plugin, which adds the server and the WaveSpeed skill together:
codex plugin marketplace add WaveSpeedAI/codex-pluginsThen install WaveSpeed from /plugins and approve the connection in your browser when asked. Or add only the server and sign in through your browser:
codex mcp add wavespeed --url https://api.wavespeed.ai/mcp
codex mcp login wavespeedOr use an API key. Put the key in an environment variable and name it in ~/.codex/config.toml:
[mcp_servers.wavespeed]
url = "https://api.wavespeed.ai/mcp"
bearer_token_env_var = "WAVESPEED_API_KEY"OpenCode
As a plugin, which adds the server and the WaveSpeed skill together. Add it to your OpenCode config (~/.config/opencode/opencode.json, or opencode.json in a project):
{
"plugin": ["@wavespeed/opencode"]
}Then sign in once through your browser:
opencode mcp auth wavespeedOr add only the server:
opencode mcp add wavespeed --url https://api.wavespeed.ai/mcp
opencode mcp auth wavespeedCursor
{
"mcpServers": {
"wavespeed": {
"url": "https://api.wavespeed.ai/mcp",
"headers": { "Authorization": "Bearer YOUR_WAVESPEED_API_KEY" }
}
}
}Grok Bot
- In the Grok Bot desktop app, open Connect apps → Add a custom connector.
- Name the connector WaveSpeedAI, choose Remote HTTPS, paste
https://api.wavespeed.ai/mcp, and select Add plugin. - Click Connect and approve the connection in your browser. The WaveSpeed approval page displays Cursor because Grok Bot uses Cursor’s OAuth callback.
VS Code
Add this to .vscode/mcp.json:
{
"servers": {
"wavespeed": {
"type": "http",
"url": "https://api.wavespeed.ai/mcp",
"headers": { "Authorization": "Bearer YOUR_WAVESPEED_API_KEY" }
}
}
}Tools that only start local commands
If a tool can only run a local command and cannot add a server by URL, connect it to the remote server through mcp-remote, which runs the connection on your computer and handles the browser sign-in:
{
"mcpServers": {
"wavespeed": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.wavespeed.ai/mcp"]
}
}
}The first time it starts, a browser window opens. Approve the connection on the WaveSpeed page and the tool is connected. This needs Node.js 18 or later. To work with files on your computer, use the local server instead.
Machines without a browser
On a server, in a container, or in CI, send an API key instead of signing in through a browser. Create a key at wavespeed.ai/accesskey from any device and pass it in the Authorization: Bearer header, as in the examples above.
Local server
The local server runs on your computer, so it can read files you point it at. It needs Node.js 18 or later.
It signs in with WAVESPEED_API_KEY, or, if you have the WaveSpeed CLI and ran wavespeed login, with that login, so one sign-in covers both. Create a key at wavespeed.ai/accesskey.
Claude Code
claude mcp add wavespeed -- npx -y @wavespeed/mcp@latestClaude Desktop, Cursor, Cline, and other tools
Add this to the tool’s MCP config (usually an mcpServers section):
{
"mcpServers": {
"wavespeed": {
"command": "npx",
"args": ["-y", "@wavespeed/mcp@latest"],
"env": { "WAVESPEED_API_KEY": "YOUR_WAVESPEED_API_KEY" }
}
}
}If you signed in with wavespeed login, you can leave out env.
@latest makes npx fetch the newest release each time the tool starts. Without it, npx runs a copy of @wavespeed/mcp already installed on your computer, however old.
Signing in
When a tool connects with OAuth, WaveSpeed creates a new API key for that connection and names it MCP · <app>, for example MCP · Claude. The app can run models and use your credits with that key, the same as any other API key on your account.
To disconnect, delete the key on the API Keys page. The next request from that app is refused.
If you are asked to approve an app that WaveSpeed has not verified, the page shows its address and an unverified warning. Only approve it if you started that connection yourself.
Tools
| Tool | What it does |
|---|---|
list_models | Search the live catalog by text or type (for example text-to-image, image-to-video) |
get_model_schema | Show a model’s required fields, accepted inputs, and defaults |
upload_attachment | Remote server only: import a ChatGPT attachment and return a download_url for generation (maximum 200 MB) |
create_upload | Remote server only: get a temporary address to upload a file from a tool that can send HTTP requests, and the download_url to use as an input |
run_model | Run a model and return the output URLs |
get_price | Estimate the cost of a run before you spend |
get_balance | Show your credit balance, with the link to top up |
get_prediction | Check on, or keep waiting for, a run that has not finished |
list_predictions | List your past runs. Defaults to the last 24 hours; filter by model, status, or time range |
list_billings | List itemized charges and refunds. Needs an API key with Billing access |
get_usage | Show spend, request counts, and a per-model breakdown. Defaults to the last 7 days. Needs an API key with Billing access |
delete_predictions | Delete finished runs from your history, up to 100 at a time. The assistant asks you first, and a deleted run cannot be recovered |
Files
Model inputs that take a file take a URL.
- Local server: write
"@./photo.jpg"as the value and the file is uploaded for you, or callupload_fileto get a hosted URL. - ChatGPT attachments: attach your image, video, audio, or other source file in the chat. The remote server’s
upload_attachmenttool imports it into WaveSpeed and returns adownload_urlto use in the model’s file input. Importing a file does not start a generation. Files use the same temporary media storage and account upload limits as other WaveSpeed uploads, with a 200 MB limit per file. If the attachment link has expired, attach the file again. After the server is updated, refresh the connector’s tools to discover the attachment tool. - Remote server: it cannot read files on your computer. Pass a public URL. If the tool you use can send HTTP requests itself (a coding agent with a shell, for example), call
create_uploadwith the file name and exact size, send the file with an HTTPPUTto the address it returns using the headers it returns, and pass the returneddownload_urlas the input. The upload address works for a short time and takes the file directly; do not send your API key to it. If the environment blocks the upload address (some sandboxes only allow listed domains, and report an error such ashost_not_allowed), either add the address’s host to that environment’s allowed domains and retry (in Claude, under Settings > Capabilities), or upload the files yourself at wavespeed.ai/upload (up to 200 MB each, several at once) and give the assistant the file links.
Running models
run_model takes the model ID and an input object whose keys come from get_model_schema.
- Unknown input names are rejected. The API ignores input names a model does not accept and still charges for the run, so the server refuses the request before it is submitted and suggests the closest valid name. Older names a model still accepts are allowed.
- Getting the result.
run_modelstarts the run and returns its prediction ID right away, withdone: false. The assistant then callsget_predictionwith that ID andwait_secondsuntildoneistrue, and gets the output links. The run keeps going on its own, so checking is free and a dropped connection loses nothing. Do not submit the same run again: a new run is billed again. For a model that finishes in seconds, passwait_secondstorun_modelto get the result in the same call.wait_secondscan be up to 100 on the remote server and 1800 on the local one. - Files. See Files above.
Checking prices
get_price returns an estimate for the inputs you pass. Pricing for some models depends on inputs such as duration or resolution, so pass the same inputs you would pass to run_model: a quote made without them can be lower than the real charge. If the price cannot be worked out from the inputs, the tool returns the error as it is, and you can fix the inputs and ask again. get_price and get_model_schema also return playground_url, the model’s page on wavespeed.ai, where you can see its inputs and try it. The amount actually charged for a run is what counts.
Troubleshooting
| Problem | What to do |
|---|---|
| Requests are refused after it worked before | The key for that connection was deleted or disabled. Reconnect, or create a new key. |
Invalid API key | Check the key on the API Keys page. |
| A tool says an input is not accepted | Call get_model_schema and use the names it lists. |
A run returns done: false | The run is still going. Call get_prediction with the ID. |
| A new tool is missing in ChatGPT or Claude | Refresh the connector’s tools. In a ChatGPT workspace with admin approval, an admin has to publish the update first. |
| ChatGPT cannot connect | Use the full address with /mcp, and choose OAuth. Check that your workspace allows custom MCP servers. |
list_billings or get_usage is refused | They need an API key with Billing access. Use a key created by an owner, admin, or billing member. |
| You cannot create more keys | An organization has a limit on active keys. Delete ones you no longer use. |