---
title: MCP 服务器
description: 通过 /mcp 处的内置 MCP 端点将 AI 助手（Claude、Cursor、VS Code 等）连接到您的安装版 API —— 包含身份验证、客户端配置、工具和安全规则。
url: https://nexcmp.com/zh-cn/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# MCP 服务器 {#mcp-server}

> **门户位置：** API reference › Tools (`https://<your-domain>/apidoc`) 展示了端点与客户端代码片段；密钥在 API keys (`/api-keys`) 中创建。管理后台中没有相应设置：该端点属于面板本身。

## 功能说明 {#what-it-does}

**Model Context Protocol (MCP)** 允许 AI 助手调用工具。NexCMP 在 `https://<your-domain>/mcp` 提供了一个 MCP 端点。每个公开的 API 操作都会成为一个**工具**（`vm_list`、`vm_start`、`billing_wallet` 等），因此客户可以向他们的助手询问“我的哪些虚拟机正在运行？”或“停止 staging 虚拟机”。助手仅使用客户自己的 API 密钥和权限进行操作。

::: tip 使用 AI 配置 NexCMP 本身？
此页面是**客户**端 MCP 端点 (`/mcp`)。若要让 AI 助手作为管理员配置您自己的面板，请参阅 [Configure with AI](https://nexcmp.com/zh-cn/docs/configure-with-ai/mcp-admin/)（端点 `/mcp/admin`，管理员密钥 `ak_`）。
:::

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 服务器 | 无需安装：该端点由面板提供，面板部署在哪里，它就在哪里可访问。您的反向代理必须将 `/mcp` 转发至面板。 |
| 客户 | 具有助手所需作用域的 [API key](https://nexcmp.com/zh-cn/docs/developers/api-keys/) (`vk_...`)。 |
| 客户端 | 支持 **Streamable HTTP** 传输协议以及自定义 `Authorization` 标头的 MCP 客户端：Claude Code、Claude Desktop（通过 `mcp-remote` 桥接）、Cursor、带有 Copilot 代理模式的 VS Code 等类似客户端。 |
| 协议版本 | 2025-11-25、2025-06-18 和 2025-03-26。 |

## 准备基础设施 {#prepare-the-infrastructure}

无需其他操作，只需确保 `https://<your-domain>/mcp` 未被防火墙或代理规则拦截。来自其他来源的基于浏览器的 MCP 客户端将被拒绝，除非允许该来源；命令行和桌面客户端不发送 `Origin` 标头且可直接正常工作。

## 连接（客户侧） {#connect-customer-side}

1. 在门户中创建一个 API 密钥（**API keys › Create key**），只赋予您希望助手使用的作用域、较短的过期时间，并且可能的话设置 IP 限制。
2. 将服务器添加到您的客户端。替换 `cloud.example.com` 以及密钥。

   **Claude Code**

   ```bash
   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"
   ```

   **Cursor** (`~/.cursor/mcp.json` 或 `.cursor/mcp.json`；在 Cursor 启动所用的环境中设置 `CLOUD_API_KEY`)：

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop**（需要 Node.js 18+；`claude_desktop_config.json`），通过 `mcp-remote` 桥接：

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   编写标头时冒号后不要加空格，并将整个值放入环境变量中，如上所示。

3. 重启客户端并让它列出您的工具。


在没有客户端的情况下检查连接：

```bash
curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 工作原理 {#how-it-works}

| 项目 | 详情 |
|---|---|
| 端点 | 带有 JSON-RPC 2.0 消息的 `POST /mcp`；响应为 `application/json`。`GET /mcp` 返回 405（无服务器到客户端的数据流）；`DELETE /mcp` 结束会话。 |
| 认证 | 仅限 `Authorization: Bearer vk_...`（会话令牌、Cookie 和管理员密钥会被拒绝并返回 401 以及 `WWW-Authenticate: Bearer` 标头）。 |
| 会话 | `Mcp-Session-Id` 由 `initialize` 签发，绑定到该密钥，有效期 24 小时；每个密钥最多 16 个会话。 |
| 工具 | 对应密钥可见的每个公开 API 操作一个。工具名称是将 CLI 命令中的空格和破折号替换为 `_`（`vm firewall add` 变为 `vm_firewall_add`）并与 OpenAPI `operationId` 相同。仅当密钥拥有相应作用域且模块已启用时，才会列出工具。 |
| 功能 | 仅工具（无资源或提示词）。 |
| 大小 | 请求体最大 1 MB；工具结果文本最大约 100 KB（超出部分会被截断并附带说明）；单次调用最多持续 55 秒。 |

### 安全规则 {#safety-rules}

- **与REST相同的网关。** 每个`tools/call`都通过面板自身的请求管线：作用域、站点、IP限制、速率限制、幂等性、所有权检查（对他人资源返回404）和配额全部适用。MCP不能授予密钥本身没有的任何权限。
- **确认。** 收费、删除或返回凭据（控制台工单、kubeconfig、S3或SSH密钥、密码重置、新密钥）的工具需要参数`confirm: true`。工具描述会指示助手仅在用户批准后才传递该参数，因此网页或日志中隐藏的指令无法独自触发它。
- **幂等性。** 付费工具接受`idempotency_key`；如果省略，则会从工具名称和参数推导出一个稳定的键，因此相同的重试不会被重复收费。
- **不作为工具公开：** 流式端点（AI Agent聊天）、一次性SSH或控制台WebSocket票据、二进制下载以及VPN应用端点（`/v1/ext/*`）。
- **绝不可能：** API绝不允许充值、更改密码、删除账号或创建密钥，因此任何助手都无法执行这些操作。

### 限制 {#limits}

| 限制 | 默认值 |
|---|---|
| 每个密钥的工具调用数 | 每分钟60次 |
| 每个密钥的MCP请求数 | 每分钟240次 |
| 外加正常的密钥和账号限制 | 参见[REST API](https://nexcmp.com/zh-cn/docs/developers/api/#rate-limits) |

超出限制时，端点会返回带有JSON-RPC错误和`Retry-After`的HTTP 429。

## 验证 {#verify}

1. 上述`curl`命令会返回带有`tools`列表的JSON-RPC结果。只有匹配密钥作用域的工具才会显示。
2. 在你的客户端中提问“列出我的虚拟机”：助手会调用`vm_list`并显示结果。
3. 在门户中，密钥的**Last used**时间会更新，且写操作调用会出现在**Key usage log**中。

## 限制与注意事项 {#limits-notes}

- **浏览器登录（OAuth）。** 参考页面还介绍了针对支持MCP OAuth的客户端通过浏览器登录的方式。在自托管的NexCMP中，受支持且经过测试的方法是API密钥（或者针对CLI的`cmp login`）。
- **分销商站点**不显示MCP部分；其客户使用分销商的域名进行API调用。
- **最小权限。** 为每个助手创建一个专用密钥，优先赋予读取作用域；仅在需要时添加写入作用域。
- 在**API keys**中吊销密钥可立即切断助手的访问权限。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| 带有`WWW-Authenticate: Bearer`的401 | 无密钥、错密钥或会话令牌 | 发送`Authorization: Bearer vk_...`。 |
| 关于`Origin`的403 | 来自其他源的浏览器页面 | 使用桌面或CLI客户端；或者请你的管理员允许该源（`mcp_allowed_origins`）。 |
| 带有`Mcp-Session-Id`的请求返回404 | 会话属于其他密钥或已过期 | 再次运行 `initialize`。 |
| 针对`GET /mcp`的405 | 预期情况：服务器没有事件流 | 仅使用POST（客户端会自动处理）。 |
| 工具列表很短 | 密钥作用域或模块 | 为密钥添加作用域；启用该模块。 |
| 工具提示需要`confirm: true` | 付费、删除或敏感工具 | 助手必须在你批准后设置`confirm`。 |
| 429 | MCP或密钥速率限制 | 等待`Retry-After`。 |
| 客户端无法通过请求头连接 | 客户端不支持自定义请求头 | 使用`mcp-remote`网桥。 |