指南

MCP 接入

通过 OAuth、API Key 或本地 stdio Server 将 MCP 客户端接入 RunAPI。

Claude Desktop、Cursor、VS Code 和 Windsurf 可以通过 OAuth 连接 Hosted MCP，也可以在直接配置 credential 时使用 API Key；需要本地进程时可通过 stdio 运行 Local MCP。

使用 OAuth 连接

将下面的 Streamable HTTP endpoint 添加为远程 MCP Server：

TEXT

https://mcp.runapi.ai/mcp

四类受支持的桌面客户端都应优先使用 OAuth：

客户端配置方式连接成功信号 Claude Desktop 使用上述 endpoint 添加自定义远程 connector。 RunAPI 显示为已连接，并可在对话中使用其工具。 Cursor 使用上述 endpoint 添加远程 MCP Server。 Server 状态为已连接，并成功加载工具清单。 VS Code 使用上述 endpoint 添加 HTTP MCP Server。 MCP Server 启动时没有认证错误，并显示工具清单。 Windsurf 使用上述 endpoint 添加远程 MCP Server。 RunAPI 显示为已连接，助手可以使用其工具。

客户端会从 Hosted MCP endpoint 自动发现 RunAPI OAuth，并在浏览器中打开授权流程：

登录或创建 RunAPI 账户。
选择允许客户端使用的 Account。
批准访问并返回客户端。

客户端会保存并刷新 OAuth credential，不会获得你的 RunAPI API Key。可在 Authorized apps 查看或撤销访问。

OAuth discovery 使用以下资源：

Hosted MCP resource：https://mcp.runapi.ai
Protected Resource Metadata：https://runapi.ai/.well-known/oauth-protected-resource
Authorization Server Metadata：https://runapi.ai/.well-known/oauth-authorization-server

OAuth resource 是 Hosted MCP origin，而 transport endpoint 带有 /mcp。不要把 https://mcp.runapi.ai/mcp 作为 OAuth resource value。

使用 API Key

标准 API Key 是一条独立、手动的认证路径，适用于支持配置 bearer token 的客户端和无人值守环境。

在 API Keys 页面为该客户端创建专用的标准 API Key。把密钥保存在客户端 secret input、环境变量或权限为 600 的文件中；不要直接写入会提交到代码仓库的 JSON。

Cursor

JSON

{
  "mcpServers": {
    "runapi": {
      "url": "https://mcp.runapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:RUNAPI_API_KEY}"
      }
    }
  }
}

在 macOS GUI session 中，打开 Cursor 前设置环境变量，并彻底重启应用：

SHELL

launchctl setenv RUNAPI_API_KEY "YOUR_API_KEY"

不再使用时运行 launchctl unsetenv RUNAPI_API_KEY。同一登录 session 中稍后打开的 GUI 应用可能读取该变量，因此请使用可单独撤销的专用密钥。

Windsurf

JSON

{
  "mcpServers": {
    "runapi": {
      "serverUrl": "https://mcp.runapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${file:~/.config/runapi/mcp_api_key}"
      }
    }
  }
}

用以下命令创建密钥文件，避免密钥进入 shell history：

SHELL

install -d -m 700 ~/.config/runapi
umask 077
printf 'RunAPI API key: ' >&2
read -r -s RUNAPI_API_KEY
printf '\n' >&2
printf '%s' "$RUNAPI_API_KEY" > ~/.config/runapi/mcp_api_key
unset RUNAPI_API_KEY
chmod 600 ~/.config/runapi/mcp_api_key

VS Code

JSON

{
  "inputs": [
    {
      "type": "promptString",
      "id": "runapi-api-key",
      "description": "RunAPI API key",
      "password": true
    }
  ],
  "servers": {
    "runapi": {
      "type": "http",
      "url": "https://mcp.runapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:runapi-api-key}"
      }
    }
  }
}

密码输入可避免密钥出现在配置文件中。停止使用某台主机或怀疑密钥泄漏时，到 API Keys 页面撤销该密钥。

运行 Local MCP

Local MCP 通过 stdio 运行 @runapi.ai/mcp，并且需要 Node.js。将 MCP host 配置为执行：

JSON

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

交互使用时，先安装 RunAPI CLI并登录，再启动 MCP 进程。MCP 的 login 工具使用同一份本地配置。

SHELL

runapi login
npx -y @runapi.ai/mcp

在无头主机或 CI 中，运行时注入专用 API Key：

SHELL

RUNAPI_API_KEY="YOUR_API_KEY" npx -y @runapi.ai/mcp

通过运行平台的 secret manager 保存密钥，不要让它进入日志或命令历史；工作负载下线后应撤销密钥。

可用工具

Hosted MCP 提供八个工具：

工具用途 list_models 列出模型，并可按模态、service 或 action 筛选。 get_model_info 查看一个模型的操作、输入、约束和定价。 list_actions 按模态分组列出可用 action。 check_pricing 查询 service、action 和模型的当前定价。 search_prompts 搜索可复用的 prompt 示例。 check_balance 查询已认证 Account 的余额与消费指标。 create_task 使用 idempotency key 创建媒体 Task。 get_task 查询 Task 的当前状态和结果。

Local MCP 还提供 login，用于通过浏览器完成本地认证。

验证连接

MCP 客户端会自动完成协议交互。通过客户端 Server log 或 MCP Inspector，依次确认以下三个操作。

首先，initialize 应返回 RunAPI Server 信息和协议 capabilities：

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {"name": "connection-check", "version": "1.0.0"}
  }
}

客户端发送 notifications/initialized 后，tools/list 应返回八个 Hosted MCP 工具名称：

JSON

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

最后调用 list_models({})。成功结果包含模型条目，证明工具分发正常：

JSON

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {"name": "list_models", "arguments": {}}
}

故障排查

401 Unauthorized：重新发起 OAuth 连接并确认授权完成，或确认配置的 API Key 未被撤销。
403 Forbidden：重新连接，并选择你仍有权限的 Account。使用 API Key 时，确认密钥属于目标 Account。
429 Too Many Requests：等待 Retry-After 指定的时间后重试。Hosted MCP 会按客户端 IP 和已认证 principal 限制请求。
已建立连接但没有工具：删除后重新添加准确的 https://mcp.runapi.ai/mcp endpoint，再次执行 initialize 和 tools/list。
工具清单成功但 list_models({}) 失败：重试一次，然后从客户端 log 中查找 JSON-RPC error 和 RunAPI request identifier。
浏览器或浏览器扩展报告 CORS：不支持浏览器直接调用。请通过 MCP 客户端或 server-side/headless MCP host 连接。
Local MCP 无法认证：运行 runapi auth status，再次执行 runapi login，或确认启动 npx 的进程可以读取 RUNAPI_API_KEY。

遇到临时 5xx 响应时使用退避重试。不要循环重试 401 或 403；应先修正 credential 或 Account 选择。