MCP integration

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:

https://mcp.runware.ai

claude mcp add --transport http runware https://mcp.runware.ai

https://mcp.runware.ai

{
      "mcp": {
        "servers": {
          "runware": { "url": "https://mcp.runware.ai" }
        }
      }
    }

[mcp_servers.runware]
    command = "npx"
    args = ["-y", "mcp-remote", "https://mcp.runware.ai"]

https://mcp.runware.ai

{
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.runware.ai"]
    }

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.

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.

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.

npx -y @runware/mcp

Most clients launch the CLI per session, so the more common shape is a config block. Example for Claude Desktop:

{
  "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.

Troubleshooting

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 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.