> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rockapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RockAPI MCP：让 AI 智能体用一把 Key 接入 50+ 模型

> RockAPI 已支持 Model Context Protocol。了解 MCP 对 AI 智能体意味着什么，如何在 Claude Code、Cursor、Codex 和 Claude Desktop 中添加 RockAPI MCP 服务器，以及如何验证连接是否可用。

RockAPI 现已支持 **Model Context Protocol（MCP）**。你不再需要为每个智能体框架单独写适配代码，只要在客户端里添加一个 MCP 服务器，智能体就能用现有的 API Key 调用 RockAPI。

本文说明 MCP 到底改变了什么、需要分别配置的两个层面，以及完整的接入与验证步骤。

![RockAPI MCP 架构图 展示 AI 智能体通过 MCP 客户端连接 RockAPI MCP 服务器 再访问 OpenAI Claude 和 Gemini 模型](https://mintcdn.com/rockapi/H_B3LeAF53GjlC9D/images/blog/rockapi-mcp-architecture.svg?fit=max\&auto=format\&n=H_B3LeAF53GjlC9D\&q=85\&s=e510582e3dffb537393cef696ce25283)

## MCP 到底改变了什么

MCP 是一套标准，让 AI 客户端可以发现并调用服务器上的工具。在 MCP 之前，每个智能体框架都有自己的插件格式，同一个能力要在 Claude Code、Cursor、Codex 里各实现一遍。

| 没有 MCP | 有了 MCP |
| - | - |
| 每个客户端、每个供应商都要单独写集成 | 一份服务器配置，任何 MCP 客户端都能加载 |
| 工具 schema 手动复制进 prompt | 运行时通过 `tools/list` 自动发现 |
| 每个集成重复实现鉴权逻辑 | 一个地址，一个 Bearer Key |
| 模型和工具耦合在同一份配置里 | 模型选择与工具权限分开配置 |

实际收益很直接：智能体获得一套稳定的能力接口，你也不必再维护多份并行的集成代码。

## 需要分别配置的两个层面

这是最容易混淆的地方，开始前先分清楚。

| 层面 | 回答什么问题 | 在哪里配置 |
| - | - | - |
| 模型层 | 由哪个大模型完成推理和生成？ | 客户端的模型或供应商设置 |
| 工具层 | 智能体能调用哪些工具和数据？ | 客户端里的 MCP 服务器条目 |

把 RockAPI 添加为 MCP 服务器时，它属于工具层。通过 [OpenAI 兼容 API](https://docs.rockapi.ai/zh-cn/blog/buyers/ai-api-gateway.md) 使用 RockAPI 作为模型供应商时，它属于模型层。两者可以同时使用，但是两条独立的配置项。

## 开始前准备

1. **创建 API Key。** 在 [rockapi.ai/keys](https://rockapi.ai/keys) 生成，放进环境变量，不要写进会提交到仓库的文件。
2. **复制 MCP 配置。** 控制台的 MCP 页面会展示你账号对应的 MCP 地址和请求头格式，用页面上给出的值，不要凭记忆手写 URL。
3. **确认客户端支持 MCP。** Claude Code、Cursor、Codex、VS Code 和 Claude Desktop 都已支持。如果下面的命令被拒绝，先检查客户端版本。
4. **确定使用的模型。** 无论用哪个客户端，智能体仍然需要一个 LLM，在客户端的供应商设置里选择，或者经由 RockAPI 调用。

```bash theme={null}
export ROCKAPI_API_KEY="sk-your-key"
export ROCKAPI_MCP_URL="<控制台 MCP 页面展示的地址>"
```

## 添加 MCP 服务器

各客户端的命令不同，但输入项一样：一个地址、一种传输方式、一个 `Authorization: Bearer` 请求头。

### Claude Code

```bash theme={null}
claude mcp add --transport http rockapi "$ROCKAPI_MCP_URL" \
  --header "Authorization: Bearer $ROCKAPI_API_KEY"
```

确认是否注册成功：

```bash theme={null}
claude mcp list
```

### Codex

在 `~/.codex/config.toml` 中加入服务器条目。通过环境变量读取 token，可以避免密钥落在文件里：

```toml theme={null}
[mcp_servers.rockapi]
url = "https://your-mcp-endpoint-from-console"
bearer_token_env_var = "ROCKAPI_API_KEY"
```

### Cursor 和 VS Code

两者都在 JSON 配置里接受 HTTP 类型的 MCP 服务器。请使用客户端支持的环境变量插值语法，避免把密钥明文写进配置：

```json theme={null}
{
  "mcpServers": {
    "rockapi": {
      "type": "http",
      "url": "${env:ROCKAPI_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${env:ROCKAPI_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Claude Desktop 启动的是命令行型服务器，所以要用 `mcp-remote` 做桥接：

```json theme={null}
{
  "mcpServers": {
    "rockapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-endpoint-from-console",
        "--header",
        "Authorization: Bearer ${ROCKAPI_API_KEY}"
      ]
    }
  }
}
```

## 验证连接

服务器显示已连接，并不等于可以上生产。请确认下面四项行为。

| 检查项 | 怎么验 | 正常表现 |
| - | - | - |
| 服务器已注册 | `claude mcp list` 或客户端的 MCP 面板 | 状态为已连接，而不是报错 |
| 工具可被发现 | 让智能体列出可用工具 | 返回非空工具列表，且没有 401 |
| 调用能成功 | 让智能体执行一个只读操作 | 返回结构化结果，而不是超时 |
| 错误可读 | 临时换成一个错误的 Key | 返回明确的鉴权错误，而不是静默的空结果 |

如果服务器连上了但调用失败，问题通常在 token 而不是传输方式。先轮换 Key 重试，再排查其他原因。

## 避免事故的几条规则

* **给 Key 划范围。** MCP 集成用独立的 Key，不要复用主账号的生产 Key，这样吊销其中一个不会影响另一个。
* **先只读。** 只授予完成任务所需的最小能力，确有工作流需要时再放开。
* **单独观察花费。** 工具型智能体会产生大量小请求，独立 Key 能让每个智能体的成本在面板里可分辨。
* **密钥放环境变量。** 把 Key 粘贴进已提交的配置文件是智能体配置中最常见的泄漏方式，参见 [API Key 安全管理](https://docs.rockapi.ai/zh-cn/blog/buyers/secure-api-key-management.md)。
* **记录工具调用。** 智能体行为异常时，工具调用序列比最终答案更能说明问题。

## 常见问题

### MCP 和 OpenAI 兼容 API 是一回事吗？

不是。OpenAI 兼容 API 规范的是代码怎么调用模型；MCP 规范的是 AI 客户端怎么发现和调用工具。RockAPI 两者都提供，配置位置不同。

### 用了 MCP 还需要 API Key 吗？

需要。MCP 服务器是可访问的，但 Key 才是识别账号、执行限流和记录计费的依据。

### 一个 MCP 服务器能给多个智能体用吗？

可以，这正是重点。同一份服务器配置可以跨客户端复用，Claude Code 和 Cursor 用同一把 Key 访问同一套能力。

### MCP 会改变模型计费方式吗？

不会。计费仍按实际模型调用计算，计费规则见 [价格与计费](https://docs.rockapi.ai/zh-cn/pricing-and-billing.md)。

### 客户端还不支持 HTTP 类型的 MCP 服务器怎么办？

用 Claude Desktop 示例里的 `mcp-remote` 桥接。它把 HTTP 地址转成本地 stdio 进程，任何命令行型客户端都能启动。

## 下一步

如果还没发过请求，先跟 [快速开始](https://docs.rockapi.ai/zh-cn/quickstart.md) 跑通，再看 [模型与供应商](https://docs.rockapi.ai/zh-cn/models-and-providers.md) 选择智能体背后的模型。需要跨多个智能体控制成本时，可以参考 [AI API 网关](https://docs.rockapi.ai/zh-cn/blog/buyers/ai-api-gateway.md) 的思路。

> [card] [创建 API Key 并接入智能体](https://rockapi.ai/sign-up?utm_source=docs\&utm_medium=referral\&utm_campaign=blog_buyers_mcp)
>
> 生成 Key，从控制台复制 MCP 配置，在接入生产流量前先验证连接。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.