RunAPI MCP Core

Reusable TypeScript primitives for building RunAPI Model Context Protocol servers.

@runapi.ai/mcp-core is the shared library used by the aggregate RunAPI MCP server and the per-model-line MCP servers. It provides the RunAPI HTTP client, contract helpers, runtime pricing lookup, tool response helpers, and createModelServer for turning embedded RunAPI catalog data into MCP tools.

This package is a library. If you want a ready-to-run MCP server, use one of these packages instead:

• @runapi.ai/mcp for the full RunAPI catalog.
• @runapi.ai/<model-line>-mcp for a focused model-line server.

Installation

npm install @runapi.ai/mcp-core

Node.js 22 or newer is required.

What It Includes

| Export area | Purpose | |---|---| | RunApiClient | Create tasks, fetch tasks, poll tasks, list models, search prompts, and check balance through the RunAPI API. | | createModelServer | Build an MCP server from embedded contract and tool metadata. | | Contract helpers | Resolve actions, models, fields, declared tool schemas, and action groups. | | Runtime pricing helpers | Look up the current Price Schedule or request a Price Quote. | | Schema helpers | Describe RunAPI fields in permissive tool schemas without enforcing API business constraints. | | Response helpers | Format JSON MCP tool responses and friendly errors. |

Basic Usage

import {
  RunApiClient,
  createModelServer,
  type Contract,
  type ModelServerTool
} from "@runapi.ai/mcp-core";

const contract: Contract = {
  actions: {
    "example/text_to_image": {
      model: "example",
      endpoint: "text_to_image",
      models: ["example-model"],
      fields_by_model: {
        "example-model": {
          prompt: {
            type: "string",
            required: true,
            description: "Image prompt."
          }
        }
      }
    }
  }
};

const tools: ModelServerTool[] = [
  {
    name: "text_to_image",
    description: "Create an example image task on RunAPI.",
    service: "example",
    action: "text_to_image",
    models: ["example-model"]
  }
];

const server = createModelServer({
  name: "@runapi.ai/example-mcp",
  version: "0.1.0",
  lineSlug: "example",
  contract,
  tools,
  client: new RunApiClient()
});

Connect the returned server with an MCP transport, for example StdioServerTransport from @modelcontextprotocol/sdk.

Authentication

Authenticated RunAPI calls resolve auth in this order:

1. RUNAPI_API_KEY, useful for headless and CI hosts.
2. ~/.config/runapi/config.json, created by the MCP login tool or runapi login.

Headless hosts can set:

export RUNAPI_API_KEY=your_key_here

RunApiClient also accepts an injected config object and fetch implementation for tests or custom hosts.

Safe Task Creation

Pass a caller-generated opaque idempotency key when creating a task. Generate one key per logical task and reuse it only when retrying the exact same request after an unknown result. The key is sent as the public Idempotency-Key request header and is not added to the JSON body.

const task = await client.createTask(
  "example",
  "text_to_image",
  {model: "example-model", prompt: "A product photo"},
  "opaque-logical-task-1"
);

Do not derive the key from a JSON-RPC request ID or X-Client-Request-Id, and do not reuse it with different input.

Package Design

@runapi.ai/mcp-core does not read catalog or pricing files at runtime. Server packages pass their embedded Input Contract into the library; pricing is resolved from the current RunAPI Price Schedule.

The package is ESM-only and ships TypeScript declarations.

API request parameters are validated by the service, not against embedded model lists, enum values, ranges, required fields, or cross-field rules. Explicit future model ids and parameter values are forwarded unchanged; service errors retain their message in the normal MCP error response. Discovered tool schemas retain declared field types, array items, and required-field hints for clients and completion. These hints do not enforce business inputs in the server; MCP-owned polling controls remain validated.

Links

• RunAPI: https://runapi.ai
• Full MCP server: https://www.npmjs.com/package/@runapi.ai/mcp
• GitHub: https://github.com/runapi-ai/mcp-core
• npm: https://www.npmjs.com/package/@runapi.ai/mcp-core
• License: Apache-2.0