---
title: 連接 AI 客戶端 (MCP)
description: 將 Claude Code、Codex CLI、Gemini CLI、Cursor、Claude Desktop、claude.ai、ChatGPT 或 OpenAI SDK 連線至面板的管理員 MCP 端點，並支援完整工具清單。
url: https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 連接 AI 客戶端 (MCP) {#connect-an-ai-client-mcp}

> **管理員位置：** System › Settings › API & AI agents (`/agent/keys`)，**Connect an AI** 分頁會顯示端點 URL 以及各客戶端的隨手複製程式碼片段，其中已填入您剛建立的金鑰。

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

**Model Context Protocol (MCP)** 允許 AI 客戶端呼叫工具。您的面板在 `https://cloud.example.com/mcp/admin` 提供管理員 MCP 伺服器。將您自己的 AI 工具連線至該伺服器，並用自然語言提問：「還有什麼需要設定？」、「加入我的 Proxmox 叢集」、「建立利潤率 40% 的方案」。客戶端會呼叫下方的管理員工具；面板會檢查範圍、在進行任何有風險的操作前詢問您，並記錄每一次呼叫。

::: info 兩個 MCP 端點
`/mcp` 是**客戶**端點（客戶 API 金鑰，`vk_`；請參閱 [MCP server](https://nexcmp.com/zh-tw/docs/developers/mcp/)）。`/mcp/admin` 是此處介紹的**管理員**端點（管理員金鑰 `ak_` 或 OAuth）。這兩者絕不混用：管理員工具在 `/mcp` 上不可見，且 `/mcp/admin` 僅接受管理員金鑰。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| Endpoint | 位於您面板自己的網域上的 `https://cloud.example.com/mcp/admin`。從 **Connect an AI** 分頁複製確切的 URL。同一個頁面也列出了用於伺服器本身執行之工具的本機 URL (`http://127.0.0.1:<port>/mcp/admin`)。 |
| 憑證 | 具有您所需範圍的 [admin API key](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/) (`ak_...`)，**或**用於網路連線器的 OAuth 登入 ([OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/))。 |
| 客戶端 | 任何支援 **Streamable HTTP** 傳輸與自訂 `Authorization` 標頭的 MCP 客戶端。支援協定版本 2025-11-25、2025-06-18 與 2025-03-26。 |
| 網路 | 如果您在面板前方放置了自己的反向代理伺服器，它必須轉發 `/mcp/admin`。網路連線器 (claude.ai、ChatGPT) 會從供應商的伺服器進行連線，因此該 URL 必須可從網際網路存取。 |

## 準備基礎設施 {#prepare-the-infrastructure}

伺服器上無需安裝任何東西。如果您透過 IP 限制金鑰，請確保客戶端連線的位址在該範圍內。請先測試連線能力：

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

回應 `401` 搭配 `WWW-Authenticate: Bearer ... resource_metadata=...` 標頭表示端點運作正常且需要認證資訊。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 建立金鑰：**System › Settings › API & AI agents › API keys › New key**。初次嘗試時請僅使用 `admin:read`；當您需要時再新增寫入範圍。請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/)。
2. 開啟 **Connect an AI** 分頁。當「金鑰已建立」對話方塊仍處於開啟狀態時，下方所有程式碼片段皆已包含您的真實金鑰。否則，它會顯示預留位置 `ak_YOUR_KEY`。
3. 複製適用於您客戶端的程式碼片段，並依照接下來的說明執行或貼上。

![Connect an AI 分頁，包含 MCP URL 以及每個客戶端一個帶有複製按鈕的卡片](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

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

然後啟動 `claude` 並詢問「列出 nexcmp 的工具」或「還有什麼需要設定？」。

於 2026/10/30 使用 Claude Code 2.1 檢查：`claude mcp add --transport http …` 會寫入伺服器（新增 `-s project` 以將其保留在專案的 `.mcp.json` 中——Claude Code 會在第一次使用時要求您核准專案伺服器）。對於指令碼，`claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` 執行時不會出現核准提示，並允許 Claude 僅使用面板的工具。

### Claude Desktop {#claude-desktop}

需要 Node.js 18 或更新版本。將此內容新增至 `claude_desktop_config.json`（它使用 `mcp-remote` 橋接器）並重新啟動 Claude Desktop：

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

如果您的系統在標頭引數中處理空格時發生錯誤，請改將整個值放入環境變數中，其方式與客戶端點完全相同：`"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` 搭配 `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`。

### claude.ai (自訂連線器) {#claude-ai-custom-connector}

無需金鑰：它使用 OAuth 登入。在 claude.ai 中開啟連線器設定、新增自訂連線器、貼上 `https://cloud.example.com/mcp/admin`，然後使用您的 NexCMP 管理員帳戶登入並在同意畫面上選擇權限。詳細資訊：[OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/)。

### ChatGPT (開發者模式) {#chatgpt-developer-mode}

無需金鑰。在 ChatGPT 中開啟開發者模式、新增一個網址為 `https://cloud.example.com/mcp/admin` 的 MCP 連線器、選擇 OAuth 並使用您的 NexCMP 管理員帳戶登入。詳細資訊：[OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/)。

### Codex CLI {#codex-cli}

新增至`~/.codex/config.toml`：

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

然後在啟動Codex的shell中匯出金鑰：

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip 非互動式`codex exec`
在`codex exec`（指令碼、CI）中，Codex在呼叫工具前不會詢問，且會跳過變更資料的工具。將`default_tools_approval_mode = "approve"`新增至`[mcp_servers.nexcmp]`下方以允許其呼叫；控制面板仍會回傳預覽，並針對資金、安全性與刪除動作要求確認。於30/10/2026以Codex CLI 0.166驗證。
:::

### Gemini CLI {#gemini-cli}

新增至`~/.gemini/settings.json`：

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI會在它不信任的資料夾中關閉MCP伺服器。請在您信任的資料夾中啟動它（或在詢問時信任該資料夾），然後以`gemini mcp list`檢查——它會顯示`nexcmp … Connected`。您可以透過`"Authorization": "Bearer $NEXCMP_KEY"`將金鑰保留在檔案之外。已於2026/10/30以Gemini CLI 0.66驗證。

### Cursor {#cursor}

新增至`~/.cursor/mcp.json`（或專案中的`.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip 將金鑰保留在設定檔外
在用戶端支援的情況下，從環境變數讀取金鑰，而不是將其寫入檔案：Codex預設會這樣做（`bearer_token_env_var`），而Cursor接受`"Bearer ${env:NEXCMP_KEY}"`。切勿將包含金鑰的檔案commit。
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

完整的執行（於2026/10/30以`openai-agents` 0.24驗證——一個讀取工具，接著是一個餘額變更，其傳回了確認預覽並在第二次呼叫時以`confirm_token`套用）：

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

將伺服器作為類型為`mcp`的工具傳入。將`require_approval`保持在`always`上，以便您的程式在每次呼叫前詢問您：

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### 其他所有項目（純HTTP） {#anything-else-plain-http}

沒有 MCP 的客戶端可以透過 HTTP 呼叫相同的工具。`GET /v1/admin/agent/tools`會列出這些工具，`POST /v1/admin/agent/tools/<name>`會執行帶有引數 JSON 內文的工具，而`GET /v1/admin/openapi.json`會傳回 OpenAPI 3.1 描述（每個工具為一個作業）。全部都需要`Authorization: Bearer ak_...`。

## 驗證 {#verify}

1. 在沒有用戶端的情況下，列出工具：

   ```bash
   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_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. 在您的用戶端中詢問「run system_health」。它會傳回警示、連線基礎設施的健康狀態、付款、電子郵件、AI與授權狀態。
3. 開啟**API & AI agents › Activity**: 呼叫記錄會連同用戶端名稱與`mcp`一併列出。
4. 在伺服器上，`sudo nexcmp status`會印出一行「MCP admin」，當端點回應時會顯示`ready`（沒有金鑰的HTTP 401是健康狀態）。

## 工具 {#tools}

伺服器提供58個工具。用戶端只能看到其金鑰範圍所允許的工具：讀取工具需要`admin:read`，寫入工具需要其自身的範圍。寫入工具也會取得選用的`confirm_token`引數（請參閱[Confirmation](#confirmation-confirm-token)）。引數會根據每個工具的Schema進行檢查：未知或拼寫錯誤的引數會被拒絕，並附帶指出它們的訊息。

價格以USD計：方案價格為每小時美元（`hourly_usd`），餘額以美分計。可以設定密碼，但絕不會傳回。

### 概覽與記錄 {#overview-and-logs}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `system_health` | 需要注意的警示、基礎設施健康狀態、付款、電子郵件、AI、授權與更新狀態。 | `admin:read` | 否 | 否 |
| `setup_checklist` | 已設定與剩餘的項目：授權、基礎設施、區域、OS範本、方案、付款、電子郵件、品牌、法律聲明、測試訂單。 | `admin:read` | 否 | 否 |
| `license_status` | 授權狀態以及是否存在較新的NexCMP版本。 | `admin:read` | 否 | 否 |
| `audit_search` | 搜尋管理員稽核記錄與API金鑰記錄。 | `admin:read` | 否 | 否 |

### 設定、品牌、法律聲明、模組 {#settings-branding-legal-modules}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `settings_get` | 讀取一般設定（`keys`篩選器；結尾的`*`符合前綴）。 | `admin:read` | 否 | 否 |
| `settings_update` | 從平坦的`values`物件變更一般設定。僅接受`settings_get`列出的金鑰。 | `settings:write` | 是 | 當金鑰觸及付款、登入安全性、全站開關或價格時 |
| `branding_get` | 品牌名稱、顏色、顯示貨幣、賣家名稱、標誌與favicon網址。 | `admin:read` | 否 | 否 |
| `branding_update` | 設定品牌名稱（最多60個字元）、顏色（`#rrggbb`）、顯示貨幣（`usd`或`vnd`）與賣家名稱。 | `settings:write` | 是 | 否 |
| `branding_logo_set` | 上傳明亮或暗色標誌或圖示（透過 https URL 或 base64，支援 PNG、JPEG、WEBP、ICO 或 SVG，最高 512 KB）。 | `settings:write` | 是 | 否 |
| `legal_get` | 服務條款與隱私權政策（英文與越南文）以及中立的預設值。 | `admin:read` | 否 | 否 |
| `legal_update` | 設定條款與隱私權文字（簡易 markdown，不支援 HTML，每項最高 50 KB）。空字串將恢復預設值。 | `settings:write` | 是 | 否 |
| `modules_get` | 哪些選用模組已啟用以及哪些可以切換。 | `admin:read` | 否 | 否 |
| `module_set` | 切換選用模組的開關（`key` 必須是 `settable` 之一）。 | `settings:write` | 是 | 否 |

### 電子郵件與警報 {#email-and-alerts}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `smtp_get` | 外寄郵件設定（密碼已遮蔽）與佇列狀態。 | `admin:read` | 否 | 否 |
| `smtp_configure` | 設定 SMTP 伺服器。變更主機、連接埠或安全性需要重新輸入密碼。 | `settings:write`（密碼另加 `secrets:write`） | 是 | 否 |
| `smtp_test` | 使用已儲存的設定發送真實的測試郵件。 | `settings:write` | 會發送郵件 | 否 |
| `telegram_get` | 管理員通知頻道（聊天室 ID；bot token 絕不會回傳）。 | `admin:read` | 否 | 否 |
| `telegram_configure` | 新增或更新 Telegram 警報頻道（bot token 與聊天室 ID）並切換管理員警報開關。 | `settings:write`（token 另加 `secrets:write`） | 是 | 否 |
| `telegram_test` | 傳送測試訊息至 Telegram 頻道。 | `settings:write` | 會傳送訊息 | 否 |

### 付款與貨幣 {#payments-and-currency}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `payments_get` | Stripe、PayPal、加密貨幣（USDT）與銀行轉帳的狀態，以及啟用的管道與手續費。 | `admin:read` | 否 | 否 |
| `payment_configure` | 設定一個金流閘道的憑證（`stripe`、`paypal`、`crypto` 或 `bank`）。 | `billing:write` (+ `secrets:write`) | 是 | 總是 |
| `payment_test` | 與提供者確認閘道已儲存的憑證。 | `billing:write` | 否 | 否 |
| `currency_get` | 顯示貨幣與 USD 兌 VND 匯率（自動或手動）。 | `admin:read` | 否 | 否 |
| `currency_set` | 設定顯示貨幣及/或手動匯率（0 表示自動，否則為 15000 至 50000）。 | `billing:write` | 是 | 當您變更手動匯率時 |

### 基礎設施與區域 {#infrastructure-and-zones}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `cloudstack_get` | 已儲存的 CloudStack 端點、區域與網路 ID（金鑰已遮蔽）。 | `admin:read` | 否 | 否 |
| `cloudstack_test` | 不儲存下使用 API 金鑰與密鑰測試端點；並列出區域。 | `infra:write`（因為您傳遞了金鑰，需加 `secrets:write`） | 否 | 否 |
| `cloudstack_connect` | 儲存 CloudStack 連線。 | `infra:write` (+ `secrets:write`) | 是 | 總是 |
| `proxmox_list` | 作為來源新增的 Proxmox VE 叢集及其健康狀態。 | `admin:read` | 否 | 否 |
| `proxmox_add` | 使用 API token（`user@realm!tokenid`）及其密鑰新增 Proxmox VE 叢集。 | `infra:write` (+ `secrets:write`) | 是 | 否 |
| `proxmox_test` | 透過 ID 連線至叢集；首次成功連線將會釘選其 TLS 憑證。 | `infra:write` | 是 | 否 |
| `proxmox_attach_zone` | 在現有區域中銷售 Proxmox 叢集，並可選擇以節點作為地區。 | `infra:write` | 是 | 否 |
| `zones_list` | 客戶可以選擇的區域（地點）。 | `admin:read` | 否 | 否 |
| `zone_create` | 建立區域。 | `infra:write` | 是 | 否 |

### 目錄與方案 {#catalog-and-plans}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `templates_list` | 客戶可以安裝的作業系統範本。 | `admin:read` | 否 | 否 |
| `templates_sync` | 從 CloudStack 匯入作業系統範本。 | `catalog:write` | 是 | 否 |
| `template_update` | 啟用或隱藏範本、重新命名、設定登入使用者或排序。 | `catalog:write` | 是 | 否 |
| `offerings_list` | 用於建立方案的 CloudStack 服務方案（CPU、記憶體、根磁碟）。 | `admin:read` | 否 | 否 |
| `plans_list` | 具有每小時與每月價格、大小、區域以及使用伺服器數量的方案。 | `admin:read` | 否 | 否 |
| `plan_create` | 建立方案。價格格式為 `hourly_usd`。CloudStack 方案需要 `cs_offering_id`；Proxmox 方案需要 `backend_id`。 | `catalog:write` | 是 | 否 |
| `plan_update` | 重新命名、顯示或隱藏、啟用或停用，或重新為方案定價。正在使用中的方案若要變更大小需要進行複製。 | `catalog:write` | 是 | 當價格變更時 |
| `plans_from_offerings` | 使用您的成本和利潤百分比，從產品（或 Proxmox 規格）建立入門方案表格。會傳回預覽；再次呼叫並帶有 `apply=true` 即可建立方案。 | `catalog:write` | 使用 `apply=true` | 套用時始終詢問 |
| `quota_defaults_get` | 預設客戶限制。 | `admin:read` | 否 | 否 |
| `quota_defaults_set` | 變更 `quota_*` 設定。 | `catalog:write` | 是 | 否 |
| `coupons_list` | 折扣與禮物代碼批次。 | `admin:read` | 否 | 否 |
| `coupon_create` | 建立一批代碼：輸入 `money`（以美分為單位的面額）或 `percent`（1 到 100，具有最高折扣）。 | `catalog:write` | 是 | 總是 |

### 客戶與經銷商 {#customers-and-resellers}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `customers_search` | 透過電子郵件、姓名或IP尋找客戶。 | `admin:read` | 否 | 否 |
| `customer_get` | 單一客戶的帳戶、餘額、伺服器與近期帳單。 | `admin:read` | 否 | 否 |
| `customer_adjust_balance` | 以美元美分新增（正數）或扣除（負數）信用額度。必須填寫原因。 | `billing:write` | 是 | 總是 |
| `customer_block` | 封鎖客戶，並可選擇同時停止其伺服器。必須填寫原因。 | `customers:write` | 是 | 總是 |
| `customer_unblock` | 解除封鎖客戶。 | `customers:write` | 是 | 否 |
| `resellers_list` | 具備錢包與狀態的經銷商。 | `admin:read` | 否 | 否 |
| `reseller_get` | 單一經銷商的網站、錢包、使用者與金流閘道。 | `admin:read` | 否 | 否 |

### AI 提供者 {#ai-provider}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `ai_provider_get` | 供客戶 AI Chat 與 AI Agent 使用的相容 OpenAI 提供者（金鑰已遮罩）。 | `admin:read` | 否 | 否 |
| `ai_provider_set` | 設定提供者：基礎URL、模型、API key、備用模型、推理強度、啟用狀態。 | `ai:write`（金鑰需 `secrets:write`） | 是 | 否 |
| `ai_provider_test` | 對已儲存的提供者提出一個問題以檢查其是否正常運作。 | `ai:write` | 否 | 否 |

### 設定檔 {#configuration-files}

| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
| `config_export` | 將設定匯出為 YAML（機密資訊會變成 `secret://` 參考）。 | `admin:read` | 否 | 否 |
| `config_plan` | 將 YAML 設定與線上面板進行比較並列出將變更的內容。 | `admin:read` | 否 | 否 |
| `config_apply` | 逐節套用 YAML 設定。每項變更皆遵循一般權限範圍與確認規則。 | `admin:read` + 各項變更的權限範圍 | 是 | 每次變更 |

檔案格式請參閱 [Configuration as code](https://nexcmp.com/zh-tw/docs/configure-with-ai/config-as-code/)。

## 提示詞 {#prompts}

伺服器亦提供三個現成提示詞供客戶作為捷徑顯示：

| 提示詞 | 參數 | 要求 AI 執行的工作 |
|---|---|---|
| `initial-setup` | 無 | 呼叫 `setup_checklist`，以一句話解釋每個未完成的步驟，向您詢問所需的資訊，透過相容工具執行該步驟，預覽金錢或安全性變更，並以 `system_health` 結束。 |
| `add-proxmox` | `endpoint`（選填，`https://host:8006`） | 詢問 API token，接著執行 `proxmox_add`、`proxmox_test`、區域工具與 `proxmox_attach_zone`；隨後使用 `plans_from_offerings` 提出方案並等待您的核准。 |
| `launch-pricing` | `margin_pct`（選填，預設為 40） | 詢問您每個 vCPU、每 GB RAM 及每 GB 磁碟的每月成本，顯示包含成本、每月價格與每小時價格的預覽表格，並在您核准後建立方案。 |

## 確認（`confirm_token`） {#confirmation-confirm-token}

涉及資金轉移、資料刪除、變更付款憑證或登入安全性的動作皆為兩步驟：

1. 第一次呼叫不會變更任何內容。工具結果以「CONFIRMATION REQUIRED」開頭，並包含**預覽**（將呼叫的內容、為何具敏感性、新值與目前值）以及 `confirm_token`。
2. 客戶必須向您展示預覽。唯有在您核准後，它才會使用相同的引數加上 `confirm_token` 再次呼叫相同的工具。
3. 該 token 只能使用一次、僅限該特定請求，並會在 5 分鐘後過期。

伺服器指令會告訴 AI 將工具執行結果視為資料而非指令，並且絕不重複使用您未核准的 Token。您是最後防線：請閱讀預覽。

::: warning 請勿自動核准
某些客戶端可以自動核准每一個工具呼叫。針對寫入型工具，請保持逐次呼叫核准開啟，或使用唯讀金鑰，以確保 AI 錯誤的計劃不會在您未察覺的情況下套用到您的面板上。
:::

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

| 項目 | Detail |
|---|---|
| 傳輸協定 | `POST /mcp/admin` 採用 JSON-RPC 2.0 訊息；回應為 `application/json`。批次中最多 20 個訊息。`GET /mcp/admin` 回應 405（無伺服器串流）；`DELETE /mcp/admin` 結束工作階段。 |
| 驗證 | `Authorization: Bearer ak_...`（手動金鑰或 OAuth 存取權杖）。缺少或錯誤的憑證會傳回帶有 `WWW-Authenticate: Bearer ... resource_metadata=...` 的 401，這可讓 OAuth 客戶端自行開始登入。 |
| 工作階段 | `Mcp-Session-Id` 由 `initialize` 發行，繫結至該金鑰且有效期限為 24 小時。 |
| 功能 | 工具與提示詞。無資源。 |
| 大小 | 請求主體最高 1 MB；工具執行結果在大約 100 KB 後會被截斷。 |
| 來源 | 帶有來自其他網站之 `Origin` 標頭的請求將被拒絕（`origin_not_allowed`）。命令列與桌面客戶端不會傳送任何標頭。 |
| 與 REST 相同的閘道 | 每個工具呼叫都會透過面板自身的請求管線與您的金鑰重新發送，因此範圍、IP 範圍、速率限制、確認與活動記錄的適用方式與直接 API 呼叫完全相同。 |

## 限制與注意事項 {#limits-notes}

- 您看不到的工具即是您未授予的範圍。請將該範圍新增至新金鑰。
- 透過 AI 客戶端設定密碼或 API 金鑰代表該機密會經過該 AI。如果您介意，請保持 `secrets:write` 關閉並在管理後台自行輸入機密，或是使用 AI Chat **Secret** 欄位（管理後台中的 [AI Chat in the admin](https://nexcmp.com/zh-tw/docs/configure-with-ai/ai-chat-in-admin/#secrets)）或 `secret://` 參考（[Configuration as code](https://nexcmp.com/zh-tw/docs/configure-with-ai/config-as-code/#secrets)）。
- 客戶端不共用工作階段：每個連線皆以 `initialize` 開始。
- 在 **API & AI agents** 中撤銷金鑰即可立即切斷 AI 客戶端。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 401 `invalid_key` | 錯誤、截斷或非管理員金鑰（例如 `vk_` 金鑰） | 請使用 `ak_` 金鑰。 |
| 401 `key_expired` 或 `key_revoked` | 金鑰已過期或已被撤銷 | 建立新金鑰。 |
| 403 `ip_not_allowed` | 您的 IP 不在金鑰的 IP 範圍內 | 請從允許的 IP 連線。 |
| 403 `origin_not_allowed` | 來自其他來源的瀏覽器頁面呼叫了此端點 | 請使用桌面或 CLI 客戶端。 |
| 帶有 `Mcp-Session-Id` 的請求回傳 404 | 工作階段屬於其他金鑰或已過期 | 請再次傳送 `initialize`。 |
| 400 unsupported `MCP-Protocol-Version` | 客戶端使用的版本伺服器無法識別 | 請更新客戶端；支援的版本：2025-11-25、2025-06-18、2025-03-26。 |
| 工具清單很短 | 金鑰範圍 | 請建立具有更多範圍的金鑰。 |
| 呼叫時發生 `insufficient_scope` | 工具需要第二個範圍，例如 `secrets:write` | 請將該範圍新增至新金鑰。 |
| 429 `rate_limited` | 每分鐘的呼叫次數超過金鑰允許的上限 | 請等待 `Retry-After` 或在新的金鑰上提高限制。 |
| claude.ai 或 ChatGPT 無法連線 | 無法從網際網路連線至該 URL，或是代理伺服器封鎖了 `/mcp/admin` 或 `/oauth-admin/` | 請檢查 DNS、TLS 與反向代理伺服器。 |

如需所有錯誤代碼，請參閱 [Admin API keys](https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/#errors)。