連接 AI 客戶端 (MCP)
管理員位置: System › Settings › API & AI agents (
/agent/keys),Connect an AI 分頁會顯示端點 URL 以及各客戶端的隨手複製程式碼片段,其中已填入您剛建立的金鑰。
功能
Model Context Protocol (MCP) 允許 AI 客戶端呼叫工具。您的面板在 https://cloud.example.com/mcp/admin 提供管理員 MCP 伺服器。將您自己的 AI 工具連線至該伺服器,並用自然語言提問:「還有什麼需要設定?」、「加入我的 Proxmox 叢集」、「建立利潤率 40% 的方案」。客戶端會呼叫下方的管理員工具;面板會檢查範圍、在進行任何有風險的操作前詢問您,並記錄每一次呼叫。
兩個 MCP 端點
/mcp 是客戶端點(客戶 API 金鑰,vk_;請參閱 MCP server)。/mcp/admin 是此處介紹的管理員端點(管理員金鑰 ak_ 或 OAuth)。這兩者絕不混用:管理員工具在 /mcp 上不可見,且 /mcp/admin 僅接受管理員金鑰。
需求
| 項目 | 需求 |
|---|---|
| Endpoint | 位於您面板自己的網域上的 https://cloud.example.com/mcp/admin。從 Connect an AI 分頁複製確切的 URL。同一個頁面也列出了用於伺服器本身執行之工具的本機 URL (http://127.0.0.1:<port>/mcp/admin)。 |
| 憑證 | 具有您所需範圍的 admin API key (ak_...),或用於網路連線器的 OAuth 登入 (OAuth connectors)。 |
| 客戶端 | 任何支援 Streamable HTTP 傳輸與自訂 Authorization 標頭的 MCP 客戶端。支援協定版本 2025-11-25、2025-06-18 與 2025-03-26。 |
| 網路 | 如果您在面板前方放置了自己的反向代理伺服器,它必須轉發 /mcp/admin。網路連線器 (claude.ai、ChatGPT) 會從供應商的伺服器進行連線,因此該 URL 必須可從網際網路存取。 |
準備基礎設施
伺服器上無需安裝任何東西。如果您透過 IP 限制金鑰,請確保客戶端連線的位址在該範圍內。請先測試連線能力:
bash
curl -i -X POST https://cloud.example.com/mcp/admin回應 401 搭配 WWW-Authenticate: Bearer ... resource_metadata=... 標頭表示端點運作正常且需要認證資訊。
在 NexCMP 中連線
- 建立金鑰:System › Settings › API & AI agents › API keys › New key。初次嘗試時請僅使用
admin:read;當您需要時再新增寫入範圍。請參閱 Admin API keys。 - 開啟 Connect an AI 分頁。當「金鑰已建立」對話方塊仍處於開啟狀態時,下方所有程式碼片段皆已包含您的真實金鑰。否則,它會顯示預留位置
ak_YOUR_KEY。 - 複製適用於您客戶端的程式碼片段,並依照接下來的說明執行或貼上。

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
需要 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 (自訂連線器)
無需金鑰:它使用 OAuth 登入。在 claude.ai 中開啟連線器設定、新增自訂連線器、貼上 https://cloud.example.com/mcp/admin,然後使用您的 NexCMP 管理員帳戶登入並在同意畫面上選擇權限。詳細資訊:OAuth connectors。
ChatGPT (開發者模式)
無需金鑰。在 ChatGPT 中開啟開發者模式、新增一個網址為 https://cloud.example.com/mcp/admin 的 MCP 連線器、選擇 OAuth 並使用您的 NexCMP 管理員帳戶登入。詳細資訊:OAuth connectors。
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非互動式codex exec
在codex exec(指令碼、CI)中,Codex在呼叫工具前不會詢問,且會跳過變更資料的工具。將default_tools_approval_mode = "approve"新增至[mcp_servers.nexcmp]下方以允許其呼叫;控制面板仍會回傳預覽,並針對資金、安全性與刪除動作要求確認。於30/10/2026以Codex CLI 0.166驗證。
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/mcp.json(或專案中的.cursor/mcp.json):
json
{
"mcpServers": {
"nexcmp": {
"url": "https://cloud.example.com/mcp/admin",
"headers": { "Authorization": "Bearer ak_XXXX" }
}
}
}將金鑰保留在設定檔外
在用戶端支援的情況下,從環境變數讀取金鑰,而不是將其寫入檔案:Codex預設會這樣做(bearer_token_env_var),而Cursor接受"Bearer ${env:NEXCMP_KEY}"。切勿將包含金鑰的檔案commit。
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
將伺服器作為類型為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)
沒有 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_...。
驗證
在沒有用戶端的情況下,列出工具:
bashcurl -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結果。
在您的用戶端中詢問「run system_health」。它會傳回警示、連線基礎設施的健康狀態、付款、電子郵件、AI與授權狀態。
開啟API & AI agents › Activity: 呼叫記錄會連同用戶端名稱與
mcp一併列出。在伺服器上,
sudo nexcmp status會印出一行「MCP admin」,當端點回應時會顯示ready(沒有金鑰的HTTP 401是健康狀態)。
工具
伺服器提供58個工具。用戶端只能看到其金鑰範圍所允許的工具:讀取工具需要admin:read,寫入工具需要其自身的範圍。寫入工具也會取得選用的confirm_token引數(請參閱Confirmation)。引數會根據每個工具的Schema進行檢查:未知或拼寫錯誤的引數會被拒絕,並附帶指出它們的訊息。
價格以USD計:方案價格為每小時美元(hourly_usd),餘額以美分計。可以設定密碼,但絕不會傳回。
概覽與記錄
| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
system_health | 需要注意的警示、基礎設施健康狀態、付款、電子郵件、AI、授權與更新狀態。 | admin:read | 否 | 否 |
setup_checklist | 已設定與剩餘的項目:授權、基礎設施、區域、OS範本、方案、付款、電子郵件、品牌、法律聲明、測試訂單。 | admin:read | 否 | 否 |
license_status | 授權狀態以及是否存在較新的NexCMP版本。 | admin:read | 否 | 否 |
audit_search | 搜尋管理員稽核記錄與API金鑰記錄。 | admin:read | 否 | 否 |
設定、品牌、法律聲明、模組
| 工具 | 功能 | 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 | 是 | 否 |
電子郵件與警報
| 工具 | 功能 | 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 | 會傳送訊息 | 否 |
付款與貨幣
| 工具 | 功能 | 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 | 是 | 當您變更手動匯率時 |
基礎設施與區域
| 工具 | 功能 | 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 | 是 | 否 |
目錄與方案
| 工具 | 功能 | 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 | 是 | 總是 |
客戶與經銷商
| 工具 | 功能 | 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 提供者
| 工具 | 功能 | 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 | 否 | 否 |
設定檔
| 工具 | 功能 | Scope | 變更資料 | 詢問您 |
|---|---|---|---|---|
config_export | 將設定匯出為 YAML(機密資訊會變成 secret:// 參考)。 | admin:read | 否 | 否 |
config_plan | 將 YAML 設定與線上面板進行比較並列出將變更的內容。 | admin:read | 否 | 否 |
config_apply | 逐節套用 YAML 設定。每項變更皆遵循一般權限範圍與確認規則。 | admin:read + 各項變更的權限範圍 | 是 | 每次變更 |
檔案格式請參閱 Configuration as code。
提示詞
伺服器亦提供三個現成提示詞供客戶作為捷徑顯示:
| 提示詞 | 參數 | 要求 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 REQUIRED」開頭,並包含預覽(將呼叫的內容、為何具敏感性、新值與目前值)以及
confirm_token。 - 客戶必須向您展示預覽。唯有在您核准後,它才會使用相同的引數加上
confirm_token再次呼叫相同的工具。 - 該 token 只能使用一次、僅限該特定請求,並會在 5 分鐘後過期。
伺服器指令會告訴 AI 將工具執行結果視為資料而非指令,並且絕不重複使用您未核准的 Token。您是最後防線:請閱讀預覽。
請勿自動核准
某些客戶端可以自動核准每一個工具呼叫。針對寫入型工具,請保持逐次呼叫核准開啟,或使用唯讀金鑰,以確保 AI 錯誤的計劃不會在您未察覺的情況下套用到您的面板上。
運作原理
| 項目 | 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 呼叫完全相同。 |
限制與注意事項
- 您看不到的工具即是您未授予的範圍。請將該範圍新增至新金鑰。
- 透過 AI 客戶端設定密碼或 API 金鑰代表該機密會經過該 AI。如果您介意,請保持
secrets:write關閉並在管理後台自行輸入機密,或是使用 AI Chat Secret 欄位(管理後台中的 AI Chat in the admin)或secret://參考(Configuration as code)。 - 客戶端不共用工作階段:每個連線皆以
initialize開始。 - 在 API & AI agents 中撤銷金鑰即可立即切斷 AI 客戶端。
故障排除
| 症狀 | 原因 | 修正方式 |
|---|---|---|
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。