MCP Server

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)
Addresshttps://api.wavespeed.ai/mcpnpx -y @wavespeed/mcp@latest
Runs onWaveSpeedYour computer
Sign inOAuth in your browser, or an API key headerWAVESPEED_API_KEY, or wavespeed login
Good forChatGPT, Claude, Claude Code, Codex, Grok Bot, and other tools that add a server by URLClaude Code, Codex, Claude Desktop, Cursor, Cline, and other tools that start a local command
Local filesPass public URLs"@./photo.jpg" is uploaded for you

Remote server

The address is:

https://api.wavespeed.ai/mcp

Claude

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:

  1. Open Plugins, select the plus button, and choose Add custom MCP server.
  2. Enter a name, set the server URL to https://api.wavespeed.ai/mcp (keep the /mcp), and choose OAuth for authentication.
  3. Confirm the notice about connecting to a custom server, then create it. Approve the connection on the WaveSpeed page that opens.
  4. 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@wavespeed

Then 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/mcp

Or 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-plugins

Then 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 wavespeed

Or 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 wavespeed

Or add only the server:

opencode mcp add wavespeed --url https://api.wavespeed.ai/mcp
opencode mcp auth wavespeed

Cursor

{
  "mcpServers": {
    "wavespeed": {
      "url": "https://api.wavespeed.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_WAVESPEED_API_KEY" }
    }
  }
}

Grok Bot

  1. In the Grok Bot desktop app, open Connect apps → Add a custom connector.
  2. Name the connector WaveSpeedAI, choose Remote HTTPS, paste https://api.wavespeed.ai/mcp, and select Add plugin.
  3. 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@latest

Claude 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

ToolWhat it does
list_modelsSearch the live catalog by text or type (for example text-to-image, image-to-video)
get_model_schemaShow a model’s required fields, accepted inputs, and defaults
upload_attachmentRemote server only: import a ChatGPT attachment and return a download_url for generation (maximum 200 MB)
create_uploadRemote 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_modelRun a model and return the output URLs
get_priceEstimate the cost of a run before you spend
get_balanceShow your credit balance, with the link to top up
get_predictionCheck on, or keep waiting for, a run that has not finished
list_predictionsList your past runs. Defaults to the last 24 hours; filter by model, status, or time range
list_billingsList itemized charges and refunds. Needs an API key with Billing access
get_usageShow spend, request counts, and a per-model breakdown. Defaults to the last 7 days. Needs an API key with Billing access
delete_predictionsDelete 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 call upload_file to get a hosted URL.
  • ChatGPT attachments: attach your image, video, audio, or other source file in the chat. The remote server’s upload_attachment tool imports it into WaveSpeed and returns a download_url to 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_upload with the file name and exact size, send the file with an HTTP PUT to the address it returns using the headers it returns, and pass the returned download_url as 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 as host_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_model starts the run and returns its prediction ID right away, with done: false. The assistant then calls get_prediction with that ID and wait_seconds until done is true, 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, pass wait_seconds to run_model to get the result in the same call. wait_seconds can 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

ProblemWhat to do
Requests are refused after it worked beforeThe key for that connection was deleted or disabled. Reconnect, or create a new key.
Invalid API keyCheck the key on the API Keys page.
A tool says an input is not acceptedCall get_model_schema and use the names it lists.
A run returns done: falseThe run is still going. Call get_prediction with the ID.
A new tool is missing in ChatGPT or ClaudeRefresh the connector’s tools. In a ChatGPT workspace with admin approval, an admin has to publish the update first.
ChatGPT cannot connectUse the full address with /mcp, and choose OAuth. Check that your workspace allows custom MCP servers.
list_billings or get_usage is refusedThey need an API key with Billing access. Use a key created by an owner, admin, or billing member.
You cannot create more keysAn organization has a limit on active keys. Delete ones you no longer use.
© 2026 WaveSpeedAI. All rights reserved.