mcp

<h1 align="center">RunAPI MCP Server</h1>

<p align="center">
  <strong>AI image generation, video generation, music creation, text-to-speech, prompt search, and model discovery — 160+ executable models across 4 modalities in one MCP server.</strong>
</p>

<p align="center">
  <sub>Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Roo Code, and any MCP-compatible host.</sub>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@runapi.ai/mcp"><img src="https://img.shields.io/npm/v/%40runapi.ai/mcp?style=flat-square&color=blue" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square" alt="Apache-2.0 license"></a>
  <img src="https://img.shields.io/badge/Type-MCP_Server-blue?style=flat-square" alt="MCP Server">
  <img src="https://img.shields.io/badge/Models-160+-green?style=flat-square" alt="160+ models">
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> |
  <a href="#tools">Tools</a> |
  <a href="#examples">Examples</a> |
  <a href="#catalog-coverage">Catalog</a> |
  <a href="#platform-setup">Platforms</a>
</p>

---

## What Is This?

RunAPI MCP Server connects MCP-compatible coding tools to RunAPI.
It lets an assistant browse the RunAPI catalog, inspect model inputs, check current runtime pricing, create media tasks, poll task status, and check account balance.

The discovery tools work without an API key because they use the embedded build-time catalog.
Authenticated operations use the `login` tool, `runapi login`, `RUNAPI_API_KEY`, or shared RunAPI config.

This package is a pure client.
It does not run a local generation backend and only needs RunAPI sign-in for authenticated tools.

---

## Hosted MCP

Remote MCP clients can connect directly to:

```text
https://mcp.runapi.ai/mcp
```

No Node.js installation is required. Use OAuth when the client supports remote MCP authorization, or configure a RunAPI API key as the bearer credential. See the [Hosted MCP setup page](https://runapi.ai/mcp) for Cursor, Claude Desktop, VS Code, and Windsurf configurations.

Hosted MCP exposes the eight Business Tools documented below. Local Login remains available only in the Local MCP package.

---

## Quick Start

For Local MCP over stdio, install RunAPI with Claude Code's MCP command:

```bash
claude mcp add runapi -s user -- npx -y @runapi.ai/mcp
```

The scope flag controls where the MCP server is stored:

- `-s user`: global, available in all projects for your user.
- `-s project`: team-shared, written to `.mcp.json` in the current repo so it can be committed.

Use project scope when you want the whole team to share the same server config:

```bash
claude mcp add runapi -s project -- npx -y @runapi.ai/mcp
```

Compatibility fallback for non-Claude Code platforms or manual JSON config:

```json
{
  "mcpServers": {
    "runapi": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/mcp"]
    }
  }
}
```

If your host needs a generated config file, use the legacy `init` command as a fallback:

```bash
npx @runapi.ai/mcp init claude
npx @runapi.ai/mcp init cursor
npx @runapi.ai/mcp init vscode
npx @runapi.ai/mcp init windsurf
npx @runapi.ai/mcp init roo
```

Free catalog tools work before sign-in.
For task creation, task status, and balance checks, ask your assistant to call the `login` tool. It opens a browser login and saves credentials to `~/.config/runapi/config.json`, the same file used by `runapi login`.
Headless and CI hosts can still set `RUNAPI_API_KEY` before starting the MCP host.

---

## Tools

| Tool | Auth | Purpose |
|---|---|---|
| `list_models` | No | List RunAPI models from the embedded catalog. Supports `modality`, `service`, and `action` filters. |
| `get_model_info` | No | Return service, action, modality, input constraints, and current runtime pricing for a model slug. Use `service` + `action` when a model appears in multiple endpoints. |
| `list_actions` | No | Group endpoint action names by modality. |
| `check_pricing` | No | Return current runtime pricing for a `service` + `action` + `model` combination. |
| `search_prompts` | No | Search reusable prompt examples by `modality`, `category`, `tags`, `q`, `model`, `featured`, and pagination. |
| `login` | No | Start browser login and save RunAPI credentials to shared local config. |
| `create_task` | Yes | Create a media task with a required caller-generated `idempotency_key`; wait for completion by default or return immediately with `wait: false`. |
| `get_task` | Yes | Fetch status and latest payload for an existing media task. |
| `check_balance` | Yes | Return account balance and spending metrics. |

The catalog, pricing, and prompt search tools are designed for funnel-top discovery inside coding tools.
The task and balance tools are designed for authenticated workflows.

---

## Examples

Ask your assistant natural-language questions.
The assistant should use the tools to discover current model slugs and pricing instead of relying on memorized names.

### Browse The Catalog

```text
What RunAPI image models are available?
```

Expected behavior:

1. The assistant calls `list_models` with `modality: "image"`.
2. It summarizes the returned model slugs, services, actions, and required fields.
3. It avoids quoting stale prices unless it calls `check_pricing`.

### Search Prompt Examples

```text
Find image prompt examples for a logo.
```

Expected behavior:

1. The assistant calls `search_prompts` with `modality: "image"` and `q: "logo"`.
2. It summarizes returned titles, prompt text, model slugs, categories, and tags.
3. It uses the selected prompt with `get_model_info` before creating a task.

### Inspect A Model

```text
Show me the required parameters for this model slug: <model-slug>
```

Expected behavior:

1. The assistant calls `get_model_info`.
2. If the response is ambiguous, it chooses the relevant service/action from the returned matches and calls `get_model_info` again with `service` and `action`.
3. It shows required fields, enum constraints, range constraints, conditional input rules, supported action, and current runtime pricing if available.
4. It tells you to choose another slug with `list_models` if the slug is not found.

### Create A Media Task

```text
Generate a square product image with RunAPI. Pick a suitable image model.
```

Expected behavior:

1. The assistant calls `list_models` to choose a compatible image model.
2. It calls `get_model_info` with the selected service/action/model to validate parameters and any conditional input rules.
3. It asks for confirmation if the request is expensive, long-running, or a batch.
4. It generates one opaque `idempotency_key` for this logical task and calls `create_task`.
5. It returns task ID, status, output URLs, and cost fields when available.

### Wait For Completion

Hosted MCP keeps an asynchronous `create_task` call with `wait: true` open as request-scoped SSE for up to 300 seconds. It polls about every 5 seconds, sends an SSE heartbeat about every 15 seconds, and sends standard `notifications/progress` only when the MCP client supplied a `progressToken`. The terminal JSON-RPC response arrives in that same stream and then closes it.

The terminal tool result includes matching `structuredContent` and text content with `task_id`, final `status`, `completed: true`, and the RunAPI `result`. See [`examples/create-task-and-wait.arguments.json`](examples/create-task-and-wait.arguments.json).

### Submit Without Waiting

```text
Create the task but do not wait for completion.
```

Expected behavior:

1. The assistant generates one opaque `idempotency_key` and calls `create_task` with `wait: false`.
2. It returns the task ID.
3. You can later ask for status with `get_task`.

### Replay A Task Creation Safely

`create_task` requires an opaque `idempotency_key` from 1 to 512 characters. Generate one new key for each logical task and retain it with the exact `service`, `action`, `model`, and `params` used for that task.

If the create result is unknown because the connection closed or timed out, do not automatically create another task. Retry only when intended, using the same key with the same input. Reusing the key with different input returns a conflict. Do not derive the key from a JSON-RPC request ID or `X-Client-Request-Id`.

When Completion Wait reaches its deadline, task creation remains successful. The non-error result has matching structured and text content with `task_id`, latest `status`, `completed: false`, `wait_deadline_reached: true`, and `next_action: "get_task"`. Continue with `get_task`; do not create a replacement task.

If polling fails or the connection closes after task creation, the task may still be processing. Continue with `get_task`; do not create a replacement task.

See [`examples/create-task.arguments.json`](examples/create-task.arguments.json) for submit-only arguments.

### Check Account Balance

```text
Check my RunAPI balance.
```

Expected behavior:

1. The assistant calls `check_balance`.
2. If no key is configured, it calls `login` for browser login, or explains `RUNAPI_API_KEY` for headless hosts.

## Catalog Coverage

The MCP Embedded Catalog is generated from RunAPI's contract snapshot.
It includes only models executable by this server release.

| Modality | What To Use |
|---|---|
| Image | `list_models` with `modality: "image"` |
| Video | `list_models` with `modality: "video"` |
| Audio and music | `list_models` with `modality: "audio"` |
| Utility | `list_models` with `modality: "utility"` |

Catalog contents can change between releases.
Use `list_models` for current service/action/model slugs and `get_model_info` for each model's current constraints.

---

## Pricing

RunAPI pricing is exposed through the `check_pricing` tool and the public pricing page.
Do not rely on examples in README files for exact prices.

Useful flows:

1. Call `list_models` to find a candidate model.
2. Call `check_pricing` with `service`, `action`, and `model