RunAPI Core MCP server
Commit Oct 29, 2026Provides TypeScript primitives and a factory to build RunAPI Model Context Protocol servers with integrated pricing, contract, and client support.
Also known as runapi-ai/mcp-core, @runapi.ai/mcp-core
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 29, 2026
- License
- Apache-2.0
What is RunAPI Core MCP?
RunAPI Core provides TypeScript primitives and a factory to build RunAPI Model Context Protocol servers with integrated pricing, contract, and client support.
Summary generated from the project's README
About RunAPI Core MCP server
Building custom Model Context Protocol servers for the RunAPI ecosystem is the primary function of this TypeScript library. Developers use these primitives to transform embedded contract and tool metadata into functional MCP tools using the createModelServer factory. It serves as the foundational layer for both the aggregate RunAPI MCP server and specific per-model-line implementations.
The library provides a RunApiClient to manage tasks, search prompts, and check account balances through the RunAPI API. It includes specialized helpers for resolving contract actions, looking up runtime pricing schedules, and formatting JSON tool responses. To handle authentication, developers can provide a RUNAPI_API_KEY via environment variables or use a local configuration file.
This package is designed for developers who need to build their own specialized servers rather than using the ready-to-run @runapi.ai/mcp package. It requires Node.js 22 or newer and operates as an ESM-only library. It focuses on providing schema hints and response formatting while leaving strict business logic validation to the service itself.
What you can do with it
- 1Generate specialized model serversA developer can use the createModelServer function to turn specific catalog data into a set of MCP tools.
- 2Manage RunAPI task lifecyclesYou can use the integrated client to create, fetch, and poll tasks while monitoring your account balance.
- 3Implement runtime pricing lookupsThe library allows your server to retrieve current price schedules or request specific price quotes during execution.
- 4Ensure safe task retriesDevelopers can implement idempotency keys to prevent duplicate task creation during network retries.
Written from the project's README. Every use case is checked against a quote from it.
How to install RunAPI Core MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall RunAPI Core MCP in Claude Code
$ claude mcp add mcp-core -- npx -y @runapi.ai/mcp-coreInstall RunAPI Core MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-core": {
"command": "npx",
"args": [
"-y",
"@runapi.ai/mcp-core"
]
}
}
}Install RunAPI Core MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-core": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@runapi.ai/mcp-core"
]
}
}
}Install RunAPI Core MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-core","type":"stdio","command":"npx","args":["-y","@runapi.ai/mcp-core"]}'Install RunAPI Core MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-core": {
"command": "npx",
"args": [
"-y",
"@runapi.ai/mcp-core"
]
}
}
}Install RunAPI Core MCP in Codex
$ codex mcp add mcp-core -- npx -y @runapi.ai/mcp-coreInstall RunAPI Core MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-core] command = "npx" args = ["-y", "@runapi.ai/mcp-core"]
Install RunAPI Core MCP in Gemini CLI
$ gemini mcp add -s user mcp-core npx -- -y @runapi.ai/mcp-coreInstall RunAPI Core MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-core": {
"command": "npx",
"args": [
"-y",
"@runapi.ai/mcp-core"
]
}
}
}Configuration
RUNAPI_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerunapi-ai/mcp-core is public and reachablegithub.com/runapi-ai/mcp-core ↗Pass
- Package names this repository as its source@runapi.ai/mcp-core names runapi-ai/mcp-core as sourcenpmjs.com/package/@runapi.ai/mcp-core ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-29github.com/runapi-ai/mcp-core ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @runapi.ai/mcp-corePass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRunAPI 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/mcpfor the full RunAPI catalog.@runapi.ai/<model-line>-mcpfor 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:
RUNAPI_API_KEY, useful for headless and CI hosts.~/.config/runapi/config.json, created by the MCPlogintool orrunapi 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
RunAPI Core MCP questions
How do I add RunAPI Core MCP to Claude Code?
Run claude mcp add mcp-core -- npx -y @runapi.ai/mcp-core in your terminal. Add --scope user to make it available in every project.
How do I add RunAPI Core MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I install the RunAPI MCP core library?
You can install it using npm with the command npm install @runapi.ai/mcp-core.
What are the authentication methods for RunAPI?
Authentication is handled via the RUNAPI_API_KEY environment variable or a configuration file located at ~/.config/runapi/config.json.
Is this a ready-to-run MCP server?
No, this is a library. For a ready-to-run server, you should use @runapi.ai/mcp for the full catalog or @runapi.ai/<model-line>-mcp for specific model lines.
What version of Node.js is required?
You must use Node.js version 22 or newer.