---
title: MCP伺服器
description: 透過內建的 /mcp MCP端點，將AI助理（Claude、Cursor、VS Code等）連接至安裝的API，包含驗證、客戶端設定、工具與安全規則。
url: https://nexcmp.com/zh-tw/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-tw/docs/configure-with-ai/mcp-admin/)（端點`/mcp/admin`，管理員金鑰`ak_`）。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 伺服器 | 無需安裝：此端點由面板提供，只要面板可連線之處即可存取。您的反向代理伺服器必須將`/mcp`轉發至面板。 |
| 客戶 | 具備助理所需範圍的[API金鑰](https://nexcmp.com/zh-tw/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 keys › Create key**）中建立一個API金鑰，僅包含您希望助理使用的範圍、較短的有效期限，以及可能的話，限制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}

| 項目 | 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秒。 |

### 安全規則 {#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-tw/docs/developers/api/#rate-limits) |

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

## 驗證 {#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` 橋接器。 |