ModelRunner MCP Server
The ModelRunner MCP server is a hosted Model Context Protocol server that gives Claude, Cursor, VS Code, and any other MCP client the 164 public models in the ModelRunner catalog — image, video, audio, 3D, and text — as 23 callable tools, authorized over OAuth 2.1 with usage-based billing.
{
"mcpServers": {
"modelrunner": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
}
}
}
- Transport
- Streamable HTTP
- Auth
- OAuth 2.1 + PKCE
- Tools
- All annotated
- Billing
- Per run, from your balance
Connect your client
One paste plus one authorization. No API key is written to disk anywhere.
- 1
Add it to Claude Code
terminalPaste the snippet below — it already carries the server URL.
- 2
Authorize in your browser
Then run /mcp in Claude Code to finish browser authorization.
claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp- 1
Add it to Claude Desktop & claude.ai
Settings → Connectors- Open Settings → Connectors.
- Click Add, then “Add custom connector”.
- Paste the server URL below and confirm.
https://mcp.modelrunner.run/mcp - 2
Authorize in your browser
Sign in to ModelRunner when the authorization window opens. Custom connectors are subject to your Claude plan’s own limits.
- 1
Add it to Cursor
~/.cursor/mcp.jsonPaste the snippet below — it already carries the server URL.
- 2
Authorize in your browser
Reload Cursor, then approve the OAuth prompt.
{
"mcpServers": {
"modelrunner": {
"url": "https://mcp.modelrunner.run/mcp"
}
}
}- 1
Add it to VS Code
.vscode/mcp.jsonPaste the snippet below — it already carries the server URL.
- 2
Authorize in your browser
Start it from the server entry in the editor, or via the “MCP: List Servers” command.
{
"servers": {
"modelrunner": {
"type": "http",
"url": "https://mcp.modelrunner.run/mcp"
}
}
}- 1
Add it to Any stdio client
mcp config (bridge)Paste the snippet below — it already carries the server URL.
- 2
Authorize in your browser
For clients that speak stdio only — mcp-remote bridges them to the hosted server. Windsurf and other MCP clients connect this way.
{
"mcpServers": {
"modelrunner": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
}
}
}Ask for it in your own words
Search the ModelRunner catalog for text-to-video models, show me the three cheapest per second with their real prices, then run the cheapest one on: a paper boat drifting down a rain-flooded gutter at night.
Generate three reference frames for a misty-forest-at-dawn shot, let me pick one, then animate it into an 8-second clip and give me the hosted URLs.
Upload ./interview.m4a to ModelRunner, transcribe it, and write the transcript to notes.md with speaker turns.
Welcome to the show. Today we're talking about how AI assistants actually run models. Let's start simple. What is an MCP server? Thanks for having me. An MCP server is a bridge. Your assistant connects to it, discovers a set of tools, and can call them mid-conversation. In our case, those tools run image, video, and audio models in the cloud. And what happens to the files? Say I record an interview like this one. You upload it once, it becomes a hosted URL, and any transcription model can take it from there. The transcript comes back into the conversation with speaker turns.
Upscale every image in ./shots with an upscaling model from the catalog and write a JSON file mapping each filename to its hosted output URL.
List my ModelRunner runs from the last week grouped by model, with the total charged for each, and flag anything that failed.
Read the ModelRunner wrapper authoring guide, then turn the prompt we just tuned into a wrapper called product-hero that takes only a subject and a background colour. Preview it on two inputs before creating it.
All 23 tools
The complete surface, not a summary. Each badge is the tool’s own MCP annotation — the thing your client reads to decide what to prompt for.
Discover
5 toolsFind a model and read its real input schema before spending anything on it.searchreadlist_modelsreadrecommended_modelsreadget_modelreadget_model_raw_schemareadWhat each one does
- search
- Relevance-ranked free-text search across models and wrappers in one list.
- list_models
- Page the public catalog, filtered by category or input/output modality.
- recommended_models
- A curated shortlist per category — the opinionated alternative to paging.
- get_model
- One model's inputs, outputs, pricing and examples, trimmed for reading.
- get_model_raw_schema
- The untruncated OpenAPI-style JSON Schema, for when the summary elides an enum.
Run
3 toolsSubmit a job and collect the result. Media runs are async — submit, then poll; language (chat) models answer in the same call.run_modelspendwait_for_requestreadget_requestreadWhat each one does
- run_model
- Run a catalog model or wrapper by its owner/alias endpoint. The one tool that spends money.
- wait_for_request
- Poll server-side for up to 2 minutes by default (10 max), returning the run’s latest status. The run continues regardless — call again to keep waiting.
- get_request
- Status, hosted output URLs, price snapshot and error for one of your requests.
Files & history
3 toolsGet local media to a URL a model input accepts, and find your past runs again.create_upload_urlwriteupload_filewritelist_my_requestsreadWhat each one does
- create_upload_url
- A presigned URL to PUT bytes to directly — the path that keeps files out of the context window.
- upload_file
- Re-host a remote URL, or push base64 bytes when the assistant has no shell.
- list_my_requests
- Your own run history, newest first, filterable by status, endpoint and metadata tags.
Author wrappers
12 toolsTurn a working prompt into a named endpoint you and your team can re-run.wrapper_authoring_guidereadlist_wrappersreadlist_my_wrappersreadrecommended_wrappersreadget_wrapperreadget_wrapper_raw_schemareadget_wrapper_prompt_templatereadget_wrapper_field_mappingsreadpreview_wrapperreadcreate_wrapperwritepatch_wrapperdestructivedelete_wrapperdestructiveWhat each one does
- wrapper_authoring_guide
- The full authoring guide as text, so the assistant reads the rules before writing one.
- list_wrappers
- Public wrappers in the catalog, as compact summaries.
- list_my_wrappers
- Your own wrappers, including the private and draft ones the public list hides.
- recommended_wrappers
- The curated shortlist per category.
- get_wrapper
- One wrapper's inputs, base models and description, trimmed for reading.
- get_wrapper_raw_schema
- Just the input schema, with the full enum lists the summary abbreviates.
- get_wrapper_prompt_template
- Just the Handlebars prompt template and its template context.
- get_wrapper_field_mappings
- Just the base-model wiring — default base model and per-model field mappings.
- preview_wrapper
- Render the prompt and mapped payload for sample inputs without running anything.
- create_wrapper
- Create a new wrapper owned by you — a private draft until you publish it.
- patch_wrapper
- Change one of your wrappers; only the fields you pass are touched.
- delete_wrapper
- Permanently remove one of your wrappers. Cannot be undone.
Turn a working prompt into an endpoint
12 of the 23 tools exist for one thing: once you and your assistant have tuned a prompt that works, publish it as a wrapper — a base model plus a prompt template and a simplified input schema, at your own owner/alias endpoint.
wrapper_authoring_guideThe assistant reads the authoring rules first, so what it writes is valid rather than plausible.
preview_wrapperRenders the prompt and mapped payload for sample inputs without running anything, so nothing is charged while you iterate.
create_wrapperCreates it under your own owner name as a private draft — nothing is public until you publish it.
What your assistant gets access to
Seedance 2.5 Image to Video
bytedance
from $0.154 per second of video
Happy Horse 1.1 Text to Video
alibaba
from $0.14 per second of video
Lyria 3 Clip
$0.04 per audio clip
Nano Banana 2 Lite Text to Image
$0.034 per image
Kling 3.0 Motion Control
kuaishou
$0.168 per second of video
Seedream 5.0 Pro Text to Image
bytedance
from $0.045 per image
Stable Audio 2.5 Audio-to-Audio
stability-ai
$0.2 per audio clip
Recraft V4.1 Pro
recraft
$0.21 per image
Frequently asked questions
What is the ModelRunner MCP server?
It is a hosted Model Context Protocol server at https://mcp.modelrunner.run/mcp that exposes the public ModelRunner catalog — image, video, audio, 3D and text models — as 23 tools any MCP client can call. Your assistant can search models, read their input schemas, run them, upload files, and get hosted result URLs back in the conversation.
What is the Model Context Protocol?
The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools and data through one common interface: a client such as Claude, Cursor, or VS Code connects to an MCP server, discovers the tools it exposes, and calls them during a conversation. The ModelRunner MCP server implements that standard, so any MCP client can work with the public ModelRunner catalog without a custom integration.
How is it different from a single-vendor MCP server?
A vendor MCP server exposes one company’s models. The ModelRunner MCP server exposes the public cross-provider catalog through one config entry, so your assistant can search the catalog and choose a model per task — or you name one — and models published to the catalog become available without you changing anything.
Which clients does it work with?
Any client that speaks MCP. Setup is verified for Claude Code, Claude Desktop and claude.ai (as a custom connector), Cursor, and VS Code with Copilot. Clients that only speak stdio connect through the mcp-remote bridge.
Do I need an API key in my MCP config?
No. The server speaks Streamable HTTP at https://mcp.modelrunner.run/mcp and authorizes over OAuth 2.1 — authorization code with PKCE (S256), scope mcp — so the first connection opens a browser window to authorize your ModelRunner account. It supports dynamic client registration (RFC 7591), refresh tokens, and revocation (RFC 7009), and advertises itself at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, so a client discovers all of this from the URL alone. No credential is written into a config file — your client holds a token it can refresh, and disconnecting the server in your client ends its access.
How does pricing work through MCP?
Exactly as it does through the API: usage-based, charged per run against your account balance. Running a model costs that model’s published price; running a wrapper costs the wrapper’s published price, which includes whatever markup its author set over the base model. Connecting over MCP adds nothing on top of either. run_model is the only tool that spends money — the upload and wrapper-authoring tools change your own data, and are annotated so your client can prompt before each one.
How long does a generation take?
It depends entirely on the model and the parameters, so runs are asynchronous: run_model returns a request id immediately and never blocks your assistant. wait_for_request then watches that request server-side for up to 2 minutes per call (10 at most) and returns its latest status. The run keeps going regardless of whether anyone is waiting, so if a long render outlasts the wait, calling wait_for_request or get_request again picks it up — nothing is lost and nothing is charged twice.
What happens to my files and results?
Every file input is a URL, so a local file needs hosting first: create_upload_url returns a presigned URL your assistant PUTs the bytes to directly, which keeps them out of the conversation entirely. Inputs you upload and outputs a model produces are stored on ModelRunner and returned as hosted URLs. Requests are private to your account by default; list_my_requests reads only your own history and can filter by status, endpoint, and metadata tags you set at submit time.
Can my assistant spend money without asking?
Every tool is annotated, and clients use those annotations to decide what to prompt for: run_model is marked as a spending, destructive operation, so a client that honours annotations asks before each run. Runs are also gated on your account balance when they are submitted, which does not depend on client behaviour.
What happens if my balance cannot cover a run?
The run is rejected at submission: run_model returns an insufficient-balance error stating your current balance and the minimum that endpoint requires, no request is created, and nothing is charged. Runs that were already accepted keep going. Top up your balance and submit again.
Can I turn a prompt I keep reusing into something callable?
Yes — that is what wrappers are. A wrapper is a base model plus a prompt template and a simplified input schema, living at your own owner/alias endpoint. It is created as a private draft and is yours to publish when you are ready. 12 of the tools are for authoring them, including a guide the assistant reads first and a preview tool that renders the mapped payload without running anything.
Can I use it alongside the REST API and SDKs?
Yes. MCP, the REST API, and the JavaScript and Python SDKs all hit the same catalog, the same endpoints and the same balance. A run started from your assistant appears in your dashboard next to one started from code.