> ## Documentation Index
> Fetch the complete documentation index at: https://modelrunner.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Connect Claude Desktop, Claude Code, Cursor, and other MCP clients directly to ModelRunner — run models, manage files, and inspect requests from your AI assistant.
## Overview
ModelRunner ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the platform as a set of tools your AI assistant can call directly. Once connected, your assistant can browse models, run inference, upload files, and inspect your request history without ever leaving the chat. For a plain-language overview with FAQs, see the [ModelRunner MCP page](https://modelrunner.ai/mcp); the server is listed in the official MCP registry as `ai.modelrunner/mcp`.
Connection uses **OAuth 2.1** with Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) — clients register themselves on first connect, then prompt you to log in to ModelRunner in your browser. You never paste an API key into the client config.
## Quick start
Add ModelRunner to your `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"modelrunner": {
"url": "https://mcp.modelrunner.run/mcp"
}
}
}
```
Restart Claude Desktop. On the first tool call, you'll be redirected to ModelRunner to authorize the client.
```bash theme={null}
claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp
```
Then run `/mcp` inside Claude Code and complete the browser-based authorization flow.
Add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"modelrunner": {
"url": "https://mcp.modelrunner.run/mcp"
}
}
}
```
Reload Cursor and approve the OAuth prompt.
Create `.vscode/mcp.json` in your workspace:
```json theme={null}
{
"servers": {
"modelrunner": {
"type": "http",
"url": "https://mcp.modelrunner.run/mcp"
}
}
}
```
Start it from the **Start** action on the server entry (or run **MCP: List Servers**), authorize in the browser, then call the tools from Copilot Chat's **Agent** mode.
Using a client that only speaks local (stdio) servers? Bridge to the remote endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
```json theme={null}
{
"mcpServers": {
"modelrunner": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
}
}
}
```
After authorization, ask your assistant "list the recommended image models on ModelRunner" — it should return a curated shortlist via the `recommended_models` tool.
## What you can run
Every public model in the catalog is callable through the same `run_model` tool — one connection covers all of it. Browse live model lists and per-model pricing by capability:
Generate images from prompts — priced per image or per megapixel.
Edit, restyle, and upscale existing images.
Generate video from prompts — priced per second of output.
Animate still images into video.
Restyle, edit, extend, or upscale footage.
Full tracks and instrumentals, flat per-output pricing.
Transcribe audio files to text.
Turn a single image into a textured 3D mesh.
The full catalog lives at [modelrunner.ai/models](https://modelrunner.ai/models); each model page shows the same endpoint, inputs, and price your assistant sees through `get_model`.
## Tools
The server exposes 23 tools, grouped by what they do.
### Discovery
| Tool | Purpose |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `list_models` | Paginated list of public models. Filters: `search`, `category`, `page`, `limit`. |
| `recommended_models` | Admin-curated shortlist for a category (`image` / `video` / `utility`). Fastest pick path. |
| `get_model` | Compact, LLM-friendly description of one model (inputs, outputs, pricing, examples). |
| `get_model_raw_schema` | Raw JSON Schema for a model's input — use this when you need exact field types. |
| `list_wrappers` | Paginated list of wrappers (prompt-templated products built on base models). |
| `recommended_wrappers` | Curated shortlist of wrappers by category. |
| `get_wrapper` | Details for one wrapper, including its base model and template. |
| `search` | Free-text search across models and wrappers in one call. |
### Inference
| Tool | Purpose |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_model` | Submits an async inference request. Returns `requestId` immediately. Input field for files must be a URL — see the file tools below. Optional `metadata` (flat string map, max 16 keys) tags the request for later filtering. |
| `get_request` | Returns current status, output (if completed), pricing, and error for a request. |
| `wait_for_request` | Polls server-side until terminal state. Args: `timeoutSeconds` (default 120, max 600), `pollIntervalSeconds` (default 2). |
### Files & history
| Tool | Purpose |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_upload_url` | Preferred path for local files: returns presigned PUT URLs plus the final `fileUrl`. The assistant PUTs the bytes with its shell, so file contents never pass through the conversation. |
| `upload_file` | Uploads raw `base64` bytes **or** a remote `url` to ModelRunner storage. Fallback for clients with no shell; 200 MiB cap. |
| `list_my_requests` | Authenticated user's request history, newest first. Filters: `status`, `modelEndpoint`, `metadata` (exact key=value tags, AND-ed), `page`, `limit`. |
| `list_my_wrappers` | Authenticated user's own wrappers, drafts included. |
Local filesystem paths are **not** accepted — the MCP server is remote. For a local file, `create_upload_url` + a shell `PUT` is the fast, token-free path; `upload_file` with `base64` bytes is the fallback when the assistant has no shell.
### Authoring wrappers
These tools let your assistant build and manage [wrappers](/docs/guides/wrappers/overview) — your own products composed on top of base models.
| Tool | Purpose |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `wrapper_authoring_guide` | Returns the canonical authoring rulebook. The assistant reads this before drafting a wrapper. |
| `get_wrapper_raw_schema` | A wrapper's full input schema with untruncated enums. |
| `get_wrapper_prompt_template` | A wrapper's Handlebars prompt template and `templateContext`. |
| `get_wrapper_field_mappings` | A wrapper's per-base-model field mappings and default base model, shaped for `patch_wrapper`. |
| `preview_wrapper` | Dry-run a wrapper's prompt template + field mappings against a sample input. Creates nothing. |
| `create_wrapper` | Create a wrapper you own. Defaults to `visibility: private`, `status: draft`. Ownership is derived from your identity. |
| `patch_wrapper` | Update one of your wrappers by `id`. |
| `delete_wrapper` | Delete one of your wrappers. |
See [Build a wrapper](/docs/guides/wrappers/authoring) for a full worked example of this flow — from reading a base model's schema to publishing a live endpoint. The three focused getters exist so the assistant fetches only the part it is editing — a large wrapper's template alone can run tens of thousands of characters.
## Typical assistant flow
A common end-to-end pattern your assistant will run:
```text theme={null}
1. recommended_models(category="image") → pick "bytedance/sdxl-lightning-4step"
2. get_model(endpoint="bytedance/sdxl-...") → confirm input fields
3. run_model(endpoint=..., input={...}) → returns requestId
4. wait_for_request(requestId=...) → returns final output URLs
```
For an image-to-image flow, prepend `create_upload_url` (or `upload_file`) to convert local bytes to a URL the model can consume.
## OAuth flow (for client implementers)
If you're building a third-party MCP client and want to support ModelRunner natively, the server publishes the standard discovery documents:
* **Protected Resource Metadata** ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)): `GET /.well-known/oauth-protected-resource`
* **Authorization Server Metadata** ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)): `GET /.well-known/oauth-authorization-server`
Supported flows:
* `authorization_code` with PKCE (S256)
* `refresh_token`
* Dynamic Client Registration via `POST /oauth/register`
* Token revocation via `POST /oauth/revoke` ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009))
Scope: `mcp`.
Unauthorized requests to `/mcp` get a `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata document — the standard MCP auth discovery handshake.
## Troubleshooting
* **`401 Unauthorized` on every tool call** — Your token expired or was revoked. Disconnect and re-authorize in your client.
* **Tool list missing or empty** — The client must send an `InitializeRequest` as the first POST to `/mcp` with no `Mcp-Session-Id` header. Most clients handle this automatically; check that you're using a current MCP SDK build.
* **`upload_file` returns "exceeds the 200 MiB upload cap"** — Use the [direct multipart upload flow](/docs/guides/file-uploads#multipart-upload-large-files) instead and pass the resulting `fileUrl` to `run_model`.