---
title: MCP 接入
url: https://runapi.ai/zh-CN/docs/guides/mcp.md
canonical: https://runapi.ai/zh-CN/docs/guides/mcp
locale: zh-CN
---

# MCP 接入

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，并在浏览器中打开授权流程：

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

客户端会保存并刷新 OAuth credential，不会获得你的 RunAPI API Key。可在 [Authorized
apps](/settings#oauth-connections) 查看或撤销访问。

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_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 页面](/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](/zh-CN/docs/resources/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 选择。