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金鑰（`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 keys › Create key）中建立一個API金鑰，僅包含您希望助理使用的範圍、較短的有效期限，以及可能的話，限制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"}'

運作原理

項目	Detail
Endpoint	帶有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

超過限制時，端點會回應 HTTP 429 以及 JSON-RPC 錯誤與 Retry-After。

驗證

上述 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伺服器 ​

功能 ​

需求 ​

準備基礎設施 ​

連線（客戶端） ​

運作原理 ​

安全規則 ​

限制 ​

驗證 ​

限制與注意事項 ​

故障排除 ​