Skip to content
RunAPI Developer Docs
EN 中文
Developer Resources
Developer Resources

Local MCP

Run the RunAPI MCP Server locally with Claude Code, Cursor, VS Code, Windsurf, or another stdio client.

View Markdown

Local MCP lets your MCP client start the RunAPI MCP Server on your machine. Use it when the client does not support Remote MCP or you explicitly need a local process.

Before you start

Install Node.js and confirm npx is available. Your MCP client must support local stdio servers.

Every client below starts the same command:

SHELL 
npx -y @runapi.ai/mcp

You can connect and use catalog tools without signing in.

Claude Code

Run:

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

Use -s user to make RunAPI available across your projects. Restart Claude Code if it was already running, then confirm RunAPI is listed as an MCP server.

Cursor

Add the server under mcpServers in .cursor/mcp.json or your user MCP configuration:

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

Open Customize in the Cursor sidebar, find RunAPI, and enable it. If the process does not start, open the Output panel and select MCP Logs.

VS Code

  1. Open the Command Palette and run MCP: Add Server.
  2. Choose Command (stdio) and enter npx -y @runapi.ai/mcp.
  3. Name the server RunAPI, choose its configuration scope, and start it.
  4. Trust the server when prompted. For errors, run MCP: List Servers, select RunAPI, and choose Show Output.

VS Code stores manual configuration under the top-level servers key and uses type: "stdio".

Windsurf

These steps apply to the Cascade agent. Devin Local uses Devin CLI configuration.

  1. Open Devin Settings > Cascade > MCP Servers.
  2. Open the raw MCP configuration at ~/.codeium/windsurf/mcp_config.json.
  3. Add RunAPI with the npx command and arguments shown in the Cursor example above.
  4. Save the file, refresh the MCP servers, and enable RunAPI.

Other MCP clients

Add a local stdio server named RunAPI. Set its command to npx and its arguments to -y and @runapi.ai/mcp. Restart or refresh the client after saving the configuration.

Verify the connection

Ask your client:

What RunAPI image models are available?

The client should call list_models and return available image models. This public discovery tool does not require authentication.

Sign in when needed

Keep using discovery tools without signing in. When you first ask RunAPI to create a task, retrieve a task, or check a balance, let the client call the login tool. It opens RunAPI in your browser and saves the credential to the shared local configuration.

If you prefer to sign in from a terminal, install the RunAPI CLI and run:

SHELL 
runapi login

For headless or CI clients, follow the Authentication Guide to create a dedicated standard API key, then provide it as RUNAPI_API_KEY through the client’s environment or secret configuration. An environment key takes precedence over the credential saved by Local MCP Login.

Troubleshoot

  • npx is not found: confirm node --version and npx --version work, then fully restart the MCP client so it receives the updated environment.
  • The local server exits immediately: run npx -y @runapi.ai/mcp in a terminal, correct the reported Node.js or package error, then restart the client.
  • RunAPI tools do not appear: confirm the server is enabled and that the command uses stdio, then check the client log described above.
  • An authenticated tool fails: ask the client to call the login tool. If RUNAPI_API_KEY is set, update or remove it before trying Local MCP Login again.

Prefer a connection without a local Node.js process? Set up Hosted MCP.