MCP 服务器

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

功能说明

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

使用 AI 配置 NexCMP 本身？

此页面是客户端 MCP 端点 (/mcp)。若要让 AI 助手作为管理员配置您自己的面板，请参阅 Configure with AI（端点 /mcp/admin，管理员密钥 ak_）。

前提条件

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

准备基础设施

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

连接（客户侧）

在门户中创建一个 API 密钥（API keys › Create key），只赋予您希望助手使用的作用域、较短的过期时间，并且可能的话设置 IP 限制。

将服务器添加到您的客户端。替换 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" }
    }
  }
}

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

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

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

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"}'

工作原理

项目	详情
端点	带有 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 秒。

安全规则

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

限制

限制	默认值
每个密钥的工具调用数	每分钟60次
每个密钥的MCP请求数	每分钟240次
外加正常的密钥和账号限制	参见REST API

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

验证

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

限制与注意事项

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

故障排查

症状	原因	解决办法
带有`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`网桥。

MCP 服务器 ​

功能说明 ​

前提条件 ​

准备基础设施 ​

连接（客户侧） ​

工作原理 ​

安全规则 ​

限制 ​

验证 ​

限制与注意事项 ​

故障排查 ​