{
  "markdown": "<h1 align=\"center\">RunAPI MCP Server</h1>\n\n<p align=\"center\">\n  <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>\n</p>\n\n<p align=\"center\">\n  <sub>Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Roo Code, and any MCP-compatible host.</sub>\n</p>\n\n<p align=\"center\">\n  <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>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square\" alt=\"Apache-2.0 license\"></a>\n  <img src=\"https://img.shields.io/badge/Type-MCP_Server-blue?style=flat-square\" alt=\"MCP Server\">\n  <img src=\"https://img.shields.io/badge/Models-160+-green?style=flat-square\" alt=\"160+ models\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#quick-start\">Quick Start</a> |\n  <a href=\"#tools\">Tools</a> |\n  <a href=\"#examples\">Examples</a> |\n  <a href=\"#catalog-coverage\">Catalog</a> |\n  <a href=\"#platform-setup\">Platforms</a>\n</p>\n\n---\n\n## What Is This?\n\nRunAPI MCP Server connects MCP-compatible coding tools to RunAPI.\nIt lets an assistant browse the RunAPI catalog, inspect model inputs, check current runtime pricing, create media tasks, poll task status, and check account balance.\n\nThe discovery tools work without an API key because they use the embedded build-time catalog.\nAuthenticated operations use the `login` tool, `runapi login`, `RUNAPI_API_KEY`, or shared RunAPI config.\n\nThis package is a pure client.\nIt does not run a local generation backend and only needs RunAPI sign-in for authenticated tools.\n\n---\n\n## Hosted MCP\n\nRemote MCP clients can connect directly to:\n\n```text\nhttps://mcp.runapi.ai/mcp\n```\n\nNo 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.\n\nHosted MCP exposes the eight Business Tools documented below. Local Login remains available only in the Local MCP package.\n\n---\n\n## Quick Start\n\nFor Local MCP over stdio, install RunAPI with Claude Code's MCP command:\n\n```bash\nclaude mcp add runapi -s user -- npx -y @runapi.ai/mcp\n```\n\nThe scope flag controls where the MCP server is stored:\n\n- `-s user`: global, available in all projects for your user.\n- `-s project`: team-shared, written to `.mcp.json` in the current repo so it can be committed.\n\nUse project scope when you want the whole team to share the same server config:\n\n```bash\nclaude mcp add runapi -s project -- npx -y @runapi.ai/mcp\n```\n\nCompatibility fallback for non-Claude Code platforms or manual JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"runapi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@runapi.ai/mcp\"]\n    }\n  }\n}\n```\n\nIf your host needs a generated config file, use the legacy `init` command as a fallback:\n\n```bash\nnpx @runapi.ai/mcp init claude\nnpx @runapi.ai/mcp init cursor\nnpx @runapi.ai/mcp init vscode\nnpx @runapi.ai/mcp init windsurf\nnpx @runapi.ai/mcp init roo\n```\n\nFree catalog tools work before sign-in.\nFor 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`.\nHeadless and CI hosts can still set `RUNAPI_API_KEY` before starting the MCP host.\n\n---\n\n## Tools\n\n| Tool | Auth | Purpose |\n|---|---|---|\n| `list_models` | No | List RunAPI models from the embedded catalog. Supports `modality`, `service`, and `action` filters. |\n| `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. |\n| `list_actions` | No | Group endpoint action names by modality. |\n| `check_pricing` | No | Return current runtime pricing for a `service` + `action` + `model` combination. |\n| `search_prompts` | No | Search reusable prompt examples by `modality`, `category`, `tags`, `q`, `model`, `featured`, and pagination. |\n| `login` | No | Start browser login and save RunAPI credentials to shared local config. |\n| `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`. |\n| `get_task` | Yes | Fetch status and latest payload for an existing media task. |\n| `check_balance` | Yes | Return account balance and spending metrics. |\n\nThe catalog, pricing, and prompt search tools are designed for funnel-top discovery inside coding tools.\nThe task and balance tools are designed for authenticated workflows.\n\n---\n\n## Examples\n\nAsk your assistant natural-language questions.\nThe assistant should use the tools to discover current model slugs and pricing instead of relying on memorized names.\n\n### Browse The Catalog\n\n```text\nWhat RunAPI image models are available?\n```\n\nExpected behavior:\n\n1. The assistant calls `list_models` with `modality: \"image\"`.\n2. It summarizes the returned model slugs, services, actions, and required fields.\n3. It avoids quoting stale prices unless it calls `check_pricing`.\n\n### Search Prompt Examples\n\n```text\nFind image prompt examples for a logo.\n```\n\nExpected behavior:\n\n1. The assistant calls `search_prompts` with `modality: \"image\"` and `q: \"logo\"`.\n2. It summarizes returned titles, prompt text, model slugs, categories, and tags.\n3. It uses the selected prompt with `get_model_info` before creating a task.\n\n### Inspect A Model\n\n```text\nShow me the required parameters for this model slug: <model-slug>\n```\n\nExpected behavior:\n\n1. The assistant calls `get_model_info`.\n2. 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`.\n3. It shows required fields, enum constraints, range constraints, conditional input rules, supported action, and current runtime pricing if available.\n4. It tells you to choose another slug with `list_models` if the slug is not found.\n\n### Create A Media Task\n\n```text\nGenerate a square product image with RunAPI. Pick a suitable image model.\n```\n\nExpected behavior:\n\n1. The assistant calls `list_models` to choose a compatible image model.\n2. It calls `get_model_info` with the selected service/action/model to validate parameters and any conditional input rules.\n3. It asks for confirmation if the request is expensive, long-running, or a batch.\n4. It generates one opaque `idempotency_key` for this logical task and calls `create_task`.\n5. It returns task ID, status, output URLs, and cost fields when available.\n\n### Wait For Completion\n\nHosted 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.\n\nThe 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).\n\n### Submit Without Waiting\n\n```text\nCreate the task but do not wait for completion.\n```\n\nExpected behavior:\n\n1. The assistant generates one opaque `idempotency_key` and calls `create_task` with `wait: false`.\n2. It returns the task ID.\n3. You can later ask for status with `get_task`.\n\n### Replay A Task Creation Safely\n\n`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.\n\nIf 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`.\n\nWhen 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.\n\nIf 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.\n\nSee [`examples/create-task.arguments.json`](examples/create-task.arguments.json) for submit-only arguments.\n\n### Check Account Balance\n\n```text\nCheck my RunAPI balance.\n```\n\nExpected behavior:\n\n1. The assistant calls `check_balance`.\n2. If no key is configured, it calls `login` for browser login, or explains `RUNAPI_API_KEY` for headless hosts.\n\n## Catalog Coverage\n\nThe MCP Embedded Catalog is generated from RunAPI's contract snapshot.\nIt includes only models executable by this server release.\n\n| Modality | What To Use |\n|---|---|\n| Image | `list_models` with `modality: \"image\"` |\n| Video | `list_models` with `modality: \"video\"` |\n| Audio and music | `list_models` with `modality: \"audio\"` |\n| Utility | `list_models` with `modality: \"utility\"` |\n\nCatalog contents can change between releases.\nUse `list_models` for current service/action/model slugs and `get_model_info` for each model's current constraints.\n\n---\n\n## Pricing\n\nRunAPI pricing is exposed through the `check_pricing` tool and the public pricing page.\nDo not rely on examples in README files for exact prices.\n\nUseful flows:\n\n1. Call `list_models` to find a candidate model.\n2. Call `check_pricing` with `service`, `action`, and `model`.\n3. Show the returned current price or link to [runapi.ai/pricing](https://runapi.ai/pricing).\n\nFree catalog tools do not create tasks and do not consume account balance.\n\n---\n\n## Platform Setup\n\n### Claude Code, Cursor, Windsurf, And VS Code\n\nRun:\n\n```bash\nclaude mcp add runapi -s user -- npx -y @runapi.ai/mcp\n```\n\nUse `-s user` for a global install available in all projects.\nUse `-s project` when you want Claude Code to write `.mcp.json` in the repo for team-shared config.\n\nRestart or reload your MCP host after changing MCP configuration.\n\n### Compatibility Fallback: Generated Config\n\nUse `init` only when a host needs a platform-specific JSON file or cannot use the Claude Code MCP command.\n\nClaude Code fallback:\n\n```bash\nnpx @runapi.ai/mcp init claude\n```\n\nThis writes `.mcp.json` in the current directory.\n\nCursor fallback:\n\n```bash\nnpx @runapi.ai/mcp init cursor\n```\n\nThis writes `.cursor/mcp.json`.\nOpen Cursor settings to verify the MCP server is enabled.\n\nVS Code fallback:\n\n```bash\nnpx @runapi.ai/mcp init vscode\n```\n\nThis writes `.vscode/mcp.json`.\nVS Code uses a top-level `servers` key and `type: \"stdio\"` in generated config.\n\nWindsurf fallback:\n\n```bash\nnpx @runapi.ai/mcp init windsurf\n```\n\nThis writes the generated config for the Windsurf target used by the init command.\n\n### Roo Code\n\nRun:\n\n```bash\nnpx @runapi.ai/mcp init roo\n```\n\nThis writes `.roo/mcp.json`.\n\n### Manual Configuration\n\nUse the example files in `examples/` as starting points.\nEach platform has slightly different wrapper keys and file paths, but all run the same command:\n\n```bash\nnpx -y @runapi.ai/mcp\n```\n\n---\n\n## Configuration\n\nThe server reads configuration in this order:\n\n1. `RUNAPI_API_KEY` environment variable, useful for headless and CI hosts\n2. `~/.config/runapi/config.json`, created by the MCP `login` tool or `runapi login`\n3. No key, which still allows free catalog tools\n\nThe config file is normally managed by login. A pre-provisioned headless config can use:\n\n```json\n{\n  \"apiKey\": \"your_runapi_key\"\n}\n```\n\nYou can also set a custom base URL for local testing:\n\n```json\n{\n  \"apiKey\": \"your_runapi_key\",\n  \"baseUrl\": \"https://runapi.ai\"\n}\n```\n\nDo not commit real API keys.\n\n---\n\n## Data Sync\n\nThis package ships build-time contract data:\n\n- `data/contract.json`: catalog, actions, model slugs, and input constraints\n\nRefresh data from the RunAPI source tree before a release:\n\n```bash\nnpm run sync:data\n```\n\nContract updates require a new package release. Pricing is queried from the RunAPI runtime API and does not use a package snapshot.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\nnpm pack --dry-run\n```\n\nRun the server locally:\n\n```bash\nnpm run dev\n```\n\nManual initialize smoke test:\n\n```bash\nprintf '%s\\n' '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0.1.0\"}},\"id\":1}' | npx tsx src/index.ts\n```\n\n---\n\n## Package Contents\n\nThe npm package includes:\n\n- compiled `dist/` files\n- embedded `data/` files\n- platform examples\n- eval scenarios, when generated by this repo\n- README, changelog, license, and package metadata\n\nIt does not include `node_modules`, `.env`, local config files, or API keys.\n\n---\n\n## Also Available Via CLI\n\nRunAPI also has a separate command-line client for terminal workflows.\nUse this MCP server when you want RunAPI available inside an MCP host.\nUse the CLI when you want direct shell commands, scripts, or CI integration.\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n",
  "bytes": 13563,
  "sha": "0957a72ac0585889ab0a9fbddb18e0b266adef4bdb196df95addd9dbbcce3d84",
  "repo_slug": "runapi-ai/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_runapi_builder_runapi_mcp_1dab79aa/readme"
}