--- title: MCP integration | Runware Docs url: https://runware.ai/docs/platform/mcp description: Connect your AI agent to Runware over the Model Context Protocol. Run any Runware task from inside Claude, Cursor, Codex, and other MCP clients. relatedDocuments: - https://runware.ai/docs/platform/python - https://runware.ai/docs/platform/javascript - https://runware.ai/docs/platform/authentication --- ## Introduction Runware exposes a **hosted MCP server** at `https://mcp.runware.ai`. Connect any MCP-compatible agent (Claude, Cursor, Codex, Windsurf, VS Code, custom clients) and the agent gets a small, well-typed set of tools that cover image and video generation, model search, pricing lookup, and task inspection. Models are addressed by their **model identifier** (`xai:grok-imagine@image-quality`, `klingai:kling-video@3-4k`, `anthropic:claude@opus-4.8`), so any Runware-hosted model is one tool call away. Auth runs on **OAuth 2.1 with an API-key form** on first connect. The MCP client speaks standard OAuth, but the credential you provide is your Runware API key, entered once into a server-rendered page. The key stays server-side, encrypted in the OAuth session, and the client only ever holds the OAuth token. For environments that cannot do remote OAuth, a `mcp-remote` stdio bridge and a local `@runware/mcp` npx package are both supported. ## Quick connect Pick your client and follow the three steps: **Claude**: 1 Open Claude settings Launch Claude Desktop or open **claude.ai** and go to Settings → Connectors. [Open Claude connectors](https://claude.ai/settings/connectors) 2 Add a custom connector Click **Add custom connector**, set the name to `Runware`, and paste the server URL: ```text https://mcp.runware.ai ``` 3 Sign in Click **Connect**, sign in with your Runware account, and approve the OAuth scope. The tools appear in the Claude tool tray. **Claude Code**: 1 Add the MCP From a project directory, register the hosted server: ```bash claude mcp add --transport http runware https://mcp.runware.ai ``` [Claude Code MCP guide](https://code.claude.com/docs/en/mcp) 2 Sign in Start a session. Claude Code opens the OAuth flow in your browser on first tool call and caches the refresh token. 3 Use it Ask Claude to generate, search, or inspect anything Runware supports. The tool calls are visible in the conversation log. **Cursor**: 1 Open MCP settings Cursor → Settings → **MCP** → Add server. [Cursor MCP guide](https://cursor.com/docs/context/mcp) 2 Paste the URL Choose the **HTTP** transport and enter: ```text https://mcp.runware.ai ``` 3 Sign in Cursor opens the OAuth flow on first use. After approval the Runware tools become available to the agent in chat and Composer. **VS Code**: 1 Enable Copilot Agent VS Code → Settings → enable **Copilot: Chat → MCP**. [VS Code MCP guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 2 Add the server Open the MCP settings JSON and add: ```json { "mcp": { "servers": { "runware": { "url": "https://mcp.runware.ai" } } } } ``` 3 Sign in Run the **MCP: List Servers** command, pick `runware`, and complete the OAuth flow in your browser. **Codex**: 1 Edit ~/.codex/config.toml Add a server entry that goes through the `mcp-remote` bridge (Codex speaks stdio, not remote OAuth directly): ```toml [mcp_servers.runware] command = "npx" args = ["-y", "mcp-remote", "https://mcp.runware.ai"] ``` [Codex MCP guide](https://developers.openai.com/codex/mcp) 2 Sign in Start Codex. The bridge opens the OAuth flow once and caches the token under `~/.mcp-auth`. 3 Use it The Runware tools show up the same way as any other MCP server. **Other clients**: 1 Remote-capable clients If the client supports remote MCP with OAuth, point it at: ```text https://mcp.runware.ai ``` [MCP spec](https://modelcontextprotocol.io) 2 Stdio-only clients For clients that only speak stdio, use the `mcp-remote` bridge: ```json { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.runware.ai"] } ``` 3 Self-hosted Run the CLI locally instead. See [Local install](#local-install) below. ## How it works The hosted server runs at the edge and proxies tool calls into the Runware API on your behalf. **Your API key carries the account identity**, so the credit charge is recorded against your Runware balance, not against an anonymous service account. The first time a client connects, the server shows a branded page where you paste your Runware API key. The key is wrapped inside an OAuth 2.1 token and kept server-side. The MCP client only holds the token, and subsequent tool calls are silent. The agent selects the tool and model from your natural-language request and fills in the parameters. You don't have to memorize task type names or schema fields, but you can override either if you want a specific behavior. ## Tools The agent gets a small set of tools, grouped by intent. ### Generate `run` Run any Runware task. Image inference, video inference, audio inference, upscale, background removal, training, and anything else exposed by the API are all reachable through this one tool. Parameters are validated against the model's JSON Schema. ### Browse `list_models` List curated models, filtered by capability (`io:text-to-image`, `io:image-to-video`, etc.), category (`image`, `video`, `audio`, `text`, `3d`), creator, or free-text search. Returns model identifiers the agent can hand straight to `run`. `model_details` Full metadata for a single model: name, capabilities, description, creator, and cover image. `model_examples` Curated prompt and output samples for the model. Use this to inspect what a model can produce without spending credits on a generation. `model_pricing` Dedicated pricing lookup. Returns the model's pricing overview and example configurations. `list_capabilities` The full capability taxonomy (`io:*`, `op:*`, `form:*`). Useful for the agent to discover what kinds of tasks it can drive. ### Inspect `model_schema` Fetch the JSON Schema for a model. Returned as an MCP resource so the agent can validate parameters before calling `run`. `get_task_details` Look up a previously submitted task by `taskUUID`. Returns the same payload the agent would have received synchronously. ## Example flows Here's what an agent does when you give it a single sentence and the right tools. claude · runware Generate a cyberpunk street scene at 2K. Use xAI's image model. On it. Let me find the right xAI image model and check the cost. list\_models creator=xai · capability=io:text-to-image 2 models matched. Highest-weight is `xai:grok-imagine@image-quality`. model\_pricing air=xai:grok-imagine@image-quality $0.05 at 1K, $0.07 at 2K. **xai:grok-imagine@image-quality** at 2K. Running now. run taskType=imageInference · 2752 × 1504 Generated in 6.4s. Cost: $0.07. Done. Here's your cyberpunk street scene. ![Cyberpunk street scene generated by Grok Imagine](https://runware.ai/docs/assets/cyberpunk-street.TCdXX-qR_Z28alNK.webp) A few other patterns come up often. **Mimic a curated example.** > Make me an image like the third example on Flux 1 Dev SRPO. The agent calls `model_examples` for the slug, copies the prompt and parameters from the matching example, and feeds them to `run`. **Compare pricing.** > What does each Veo model cost for an 8-second 1080p clip? The agent calls `list_models` filtered by `category=video`, then `model_pricing` for each model, and compiles a side-by-side table. You don't have to script any of this. The agent decides the order on its own. ## Local install If you can't reach the hosted server (corporate egress block, air-gapped environment), run the CLI locally. It exposes the same tools but ships an API key in env rather than OAuth. Pin the version if you need reproducibility. ```bash npx -y @runware/mcp ``` Most clients launch the CLI per session, so the more common shape is a config block. Example for Claude Desktop: ```json { "mcpServers": { "runware": { "command": "npx", "args": ["-y", "@runware/mcp"], "env": { "RUNWARE_API_KEY": "your-api-key" } } } } ``` The hosted server is the default path. Reach for the CLI when OAuth or remote MCP isn't an option. ## Auth The hosted server uses **OAuth 2.1 with PKCE** as the protocol, but the credential is your Runware API key (entered into a server-rendered page, not collected by the client). The flow is: 1. Client opens `https://mcp.runware.ai/.well-known/oauth-authorization-server` and discovers the authorization endpoint. 2. Browser opens the MCP server's `/authorize` page. You paste your Runware API key and submit. 3. The server wraps the key inside an OAuth access + refresh token and redirects back to the client. 4. Subsequent tool calls send the access token in the `Authorization` header. The server unwraps it server-side to recover your API key and calls Runware on your behalf. The API key is stored encrypted in the OAuth session and never reaches the client. Your spend lands on your Runware balance because every call uses your key. To revoke access, **rotate or delete the API key** in your Runware dashboard. The OAuth token continues to exist, but every Runware call it tries to make starts failing, so the MCP effectively stops working until you reconnect with a fresh key. The local CLI skips OAuth entirely and reads the key from `RUNWARE_API_KEY` instead. Same charge path. > [!NOTE] > The legitimate flow asks you to paste your Runware API key into a Runware-branded page served by `mcp.runware.ai`. Any client prompting for an API key in its own UI before the browser redirect is bypassing OAuth. This is common for stdio-only clients connecting through a bridge. ## Troubleshooting The OAuth popup closes immediately and the connector shows as failed. ▸ The browser blocked the popup, or the popup was opened but never received the callback. Unblock popups for the client's domain (`claude.ai`, `cursor.com`, etc.) and try connecting again. If the popup opens but closes without completing, it's typically a cross-origin restriction on the popup window. Disconnect and reconnect the server. I see 'Token exchange failed' or an Authentication Error after submitting my key. ▸ Locally cached OAuth state is stale. Clear it and reconnect: - **Clients using `mcp-remote`**: `rm -rf ~/.mcp-auth` and restart the client. - **Claude Code**: open `/mcp`, choose **Clear authentication** on the Runware entry, then re-add the server. - **Claude Desktop / claude.ai**: Settings → Connectors → disconnect Runware and reconnect. The tools don't appear after I connect. ▸ Verify the server is actually registered in the client. The connector can show "connected" without the tool list having been fetched: - **Claude Desktop / claude.ai**: Settings → Connectors → Runware should read "Connected." If not, remove and re-add. - **Claude Code**: run `claude mcp list` and confirm the entry, then restart the session. - **Codex CLI**: run `codex mcp list` and start a new session. Then ask the agent a trivial Runware question (`check my account` or `list a few image models`). If it calls a tool, the connection is live. I rotated my API key and the connector is still billing the old one. ▸ The OAuth session stored the key at connect time, so rotating the key in your dashboard doesn't update the session. Disconnect the connector in your client and reconnect, then paste the new key on the OAuth page. A run failed with 'insufficient credits.' ▸ Your account balance was below the model's cost. Top up your balance and have the agent retry. The agent doesn't see your balance directly so it can't pre-check. Call `model_pricing` first if you want it to budget before running. ## Pricing MCP tool calls are billed at standard Runware pricing for whatever underlying task runs. **There is no MCP-specific surcharge.** If a `run` call generates an image that costs $0.05, MCP charges $0.05. Every other tool is free. See the [pricing page](https://runware.ai/platform/pricing) for how Runware bills (compute-based, no subscriptions). For per-model rates, call `model_pricing` from inside the agent or check the model's page directly.