---
title: Kết nối client AI (MCP)
description: Kết nối Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT hay OpenAI SDK với admin MCP endpoint của panel, kèm đầy đủ công cụ.
url: https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Kết nối client AI (MCP) {#connect-an-ai-client-mcp}

> **Vị trí trong admin:** System › Settings › API & AI agents (`/agent/keys`), tab **Connect an AI** hiển thị URL endpoint và đoạn mã cấu hình có sẵn cho từng client, điền sẵn khóa bạn vừa tạo.

## Chức năng {#what-it-does}

**Model Context Protocol (MCP)** cho phép client AI gọi các công cụ. Panel của bạn cung cấp một admin MCP server tại `https://cloud.example.com/mcp/admin`. Hãy kết nối công cụ AI của bạn với server này và hỏi bằng ngôn ngữ tự nhiên: "what is left to set up?", "add my Proxmox cluster", "create plans with a 40% margin". Client sẽ gọi các công cụ quản trị bên dưới; panel sẽ kiểm tra scope, hỏi bạn trước mọi tác vụ có rủi ro và ghi log từng lệnh gọi.

::: info Hai MCP endpoint
`/mcp` là endpoint dành cho **khách hàng** (API key khách hàng, `vk_`; xem [MCP server](https://nexcmp.com/vi/docs/developers/mcp/)). `/mcp/admin` là endpoint dành cho **quản trị** được mô tả ở đây (khóa admin `ak_` hoặc OAuth). Hai endpoint này không bao giờ lẫn lộn: các công cụ admin không hiển thị trên `/mcp`, và `/mcp/admin` chỉ chấp nhận khóa admin.
:::

## Yêu cầu {#requirements}

| Hạng mục | Yêu cầu |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` trên chính domain panel của bạn. Hãy sao chép chính xác URL từ tab **Connect an AI**. Trang này cũng liệt kê một URL cục bộ (`http://127.0.0.1:<port>/mcp/admin`) dành cho các công cụ chạy trực tiếp trên chính server. |
| Thông tin xác thực | Một [admin API key](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/) (`ak_...`) với các scope bạn muốn, **hoặc** đăng nhập OAuth cho các connector nền web ([OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/)). |
| Client | Bất kỳ MCP client nào hỗ trợ transport **Streamable HTTP** và header `Authorization` tùy chỉnh. Các phiên bản giao thức 2025-11-25, 2025-06-18 và 2025-03-26. |
| Mạng | Nếu bạn đặt reverse proxy riêng phía trước panel, nó phải chuyển tiếp `/mcp/admin`. Các connector nền web (claude.ai, ChatGPT) kết nối từ server của nhà cung cấp, do đó URL phải truy cập được từ internet. |

## Chuẩn bị hạ tầng {#prepare-the-infrastructure}

Không cần cài đặt gì trên server. Nếu bạn giới hạn khóa theo IP, hãy đảm bảo địa chỉ client kết nối nằm trong dải cho phép. Kiểm tra khả năng kết nối trước:

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

Phản hồi `401` với header `WWW-Authenticate: Bearer ... resource_metadata=...` có nghĩa là endpoint đang hoạt động và yêu cầu thông tin xác thực.

## Kết nối trong NexCMP {#connect-in-nexcmp}

1. Tạo khóa: **System › Settings › API & AI agents › API keys › New key**. Với lần thử đầu tiên, chỉ nên dùng `admin:read`; thêm các write scope khi cần. Xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/).
2. Mở tab **Connect an AI**. Khi hộp thoại "key created" vừa mới hiển thị, mỗi đoạn mã bên dưới đã chứa sẵn khóa thực của bạn. Nếu không, nó sẽ hiển thị placeholder `ak_YOUR_KEY`.
3. Sao chép đoạn mã cho client của bạn rồi chạy hoặc dán như hướng dẫn tiếp theo.

![Tab Connect an AI với URL MCP và mỗi client một thẻ kèm nút sao chép](https://nexcmp.com/vi/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"
```

Sau đó khởi động `claude` và hỏi "list the tools from nexcmp" hoặc "what is left to set up?".

Đã kiểm tra vào ngày 30/10/2026 với Claude Code 2.1: `claude mcp add --transport http …` ghi server (thêm `-s project` để lưu trong `.mcp.json` của project — Claude Code sẽ yêu cầu bạn phê duyệt server project trong lần đầu). Đối với script, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` chạy mà không cần lời nhắc phê duyệt và chỉ cho phép Claude sử dụng các công cụ của panel.

### Claude Desktop {#claude-desktop}

Yêu cầu Node.js 18 trở lên. Thêm nội dung này vào `claude_desktop_config.json` (sử dụng bridge `mcp-remote`) và khởi động lại Claude Desktop:

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

Nếu hệ thống của bạn làm lỗi dấu cách trong đối số header, hãy đặt toàn bộ giá trị vào một biến môi trường, tương tự như với customer endpoint: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` với `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (custom connector) {#claude-ai-custom-connector}

Không cần khóa: đăng nhập bằng OAuth. Trong claude.ai, mở cài đặt connectors, thêm custom connector, dán `https://cloud.example.com/mcp/admin`, sau đó đăng nhập bằng tài khoản admin NexCMP của bạn và chọn quyền trên màn hình xác nhận. Chi tiết: [OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

Không cần khóa. Trong ChatGPT, bật developer mode, thêm một MCP connector với URL `https://cloud.example.com/mcp/admin`, chọn OAuth và đăng nhập bằng tài khoản admin NexCMP của bạn. Chi tiết: [OAuth connectors](https://nexcmp.com/vi/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Thêm vào `~/.codex/config.toml`:

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

Sau đó export khóa trong shell khởi chạy Codex:

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

::: tip `codex exec` không tương tác
Trong `codex exec` (script, CI), Codex không hỏi trước khi gọi tool và bỏ qua các tool làm thay đổi dữ liệu. Thêm `default_tools_approval_mode = "approve"` dưới `[mcp_servers.nexcmp]` để cho phép gọi chúng; bảng điều khiển vẫn trả về bản xem trước và yêu cầu xác nhận đối với các tác vụ liên quan đến tiền tệ, bảo mật và xóa. Đã kiểm tra với Codex CLI 0.166 vào 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Thêm vào `~/.gemini/settings.json`:

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

Gemini CLI tắt MCP server trong các thư mục mà nó không tin cậy. Hãy khởi chạy nó trong thư mục bạn tin cậy (hoặc chọn tin cậy thư mục khi được hỏi), sau đó kiểm tra bằng `gemini mcp list` — kết quả sẽ hiển thị `nexcmp … Connected`. Bạn có thể không lưu khóa trong file bằng cách dùng `"Authorization": "Bearer $NEXCMP_KEY"`. Đã kiểm tra với Gemini CLI 0.66 vào 30/10/2026.

### Cursor {#cursor}

Thêm vào `~/.cursor/mcp.json` (hoặc `.cursor/mcp.json` trong dự án):

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

::: tip Không lưu khóa trong file cấu hình
Nếu client hỗ trợ, hãy đọc khóa từ biến môi trường thay vì ghi trực tiếp vào file: Codex thực hiện việc này theo mặc định (`bearer_token_env_var`), và Cursor hỗ trợ `"Bearer ${env:NEXCMP_KEY}"`. Không bao giờ commit file có chứa khóa.
:::

### 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",
)
```

Một lượt chạy hoàn chỉnh (đã kiểm tra với `openai-agents` 0.24 vào 30/10/2026 — tool đọc dữ liệu, sau đó là thay đổi số dư trả về bản xem trước để xác nhận và được áp dụng ở lần gọi thứ hai với `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}

Truyền server dưới dạng một tool thuộc loại `mcp`. Giữ `require_approval` ở `always` để chương trình hỏi bạn trước mỗi lần gọi:

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

### Các trường hợp khác (plain HTTP) {#anything-else-plain-http}

Client không có MCP vẫn có thể gọi các tool này qua HTTP. `GET /v1/admin/agent/tools` liệt kê danh sách tool, `POST /v1/admin/agent/tools/<name>` chạy một tool với JSON body chứa các đối số, và `GET /v1/admin/openapi.json` trả về mô tả OpenAPI 3.1 (mỗi tool là một operation). Tất cả đều cần `Authorization: Bearer ak_...`.

## Kiểm tra {#verify}

1. Liệt kê các tool mà không cần client:

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

   Kết quả trả về là một JSON-RPC result chứa các tool mà scope của bạn cho phép.
2. Trong client của bạn, yêu cầu "run system_health". Lệnh này trả về các cảnh báo, tình trạng hạ tầng kết nối, thanh toán, email, AI và trạng thái giấy phép.
3. Mở **API & AI agents › Activity**: các lệnh gọi được liệt kê cùng tên client và `mcp`.
4. Trên server, `sudo nexcmp status` in ra dòng "MCP admin" thông báo `ready` khi endpoint phản hồi (HTTP 401 khi không có khóa là trạng thái bình thường).

## Công cụ {#tools}

Server cung cấp 58 tool. Client chỉ thấy các tool được scope của khóa cho phép: tool đọc cần `admin:read`, tool ghi cần scope tương ứng. Tool ghi cũng có thêm đối số tùy chọn `confirm_token` (xem [Confirmation](#confirmation-confirm-token)). Các đối số được xác thực theo schema của từng tool: đối số không xác định hoặc sai kiểu sẽ bị từ chối kèm thông báo chỉ rõ tên đối số đó.

Giá tính bằng USD: giá gói cước tính bằng USD mỗi giờ (`hourly_usd`), số dư tính bằng cent. Thông tin bảo mật có thể thiết lập nhưng không bao giờ được trả về.

### Tổng quan và nhật ký {#overview-and-logs}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `system_health` | Cảnh báo cần xử lý, tình trạng hạ tầng, thanh toán, email, AI, giấy phép và trạng thái cập nhật. | `admin:read` | Không | Không |
| `setup_checklist` | Những mục đã cấu hình và còn lại: giấy phép, hạ tầng, zone, OS template, gói cước, thanh toán, email, thương hiệu, pháp lý, đơn hàng thử nghiệm. | `admin:read` | Không | Không |
| `license_status` | Trạng thái giấy phép và liệu có phiên bản NexCMP mới hơn hay không. | `admin:read` | Không | Không |
| `audit_search` | Tìm kiếm audit log quản trị và log API key. | `admin:read` | Không | Không |

### Cài đặt, thương hiệu, pháp lý, module {#settings-branding-legal-modules}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `settings_get` | Đọc cài đặt chung (`keys` lọc; ký tự `*` ở cuối khớp với tiền tố). | `admin:read` | Không | Không |
| `settings_update` | Thay đổi cài đặt chung từ đối tượng `values` phẳng. Chỉ chấp nhận các key được liệt kê bởi `settings_get`. | `settings:write` | Có | Khi một key liên quan đến thanh toán, bảo mật đăng nhập, các nút bật tắt toàn trang hoặc giá bán |
| `branding_get` | Tên thương hiệu, màu sắc, đơn vị tiền tệ hiển thị, tên người bán, URL logo và favicon. | `admin:read` | Không | Không |
| `branding_update` | Đặt tên thương hiệu (tối đa 60 ký tự), màu sắc (`#rrggbb`), đơn vị tiền tệ hiển thị (`usd` hoặc `vnd`) và tên người bán. | `settings:write` | Có | Không |
| `branding_logo_set` | Tải lên logo sáng hoặc tối hoặc favicon từ URL https hoặc base64 (PNG, JPEG, WEBP, ICO hoặc SVG, tối đa 512 KB). | `settings:write` | Có | Không |
| `legal_get` | Điều khoản dịch vụ và chính sách quyền riêng tư (tiếng Anh và tiếng Việt) cùng các giá trị mặc định trung tính. | `admin:read` | Không | Không |
| `legal_update` | Thiết lập văn bản điều khoản và quyền riêng tư (markdown đơn giản, không chứa HTML, tối đa 50 KB mỗi mục). Chuỗi rỗng sẽ khôi phục mặc định. | `settings:write` | Có | Không |
| `modules_get` | Các module tùy chọn nào đang bật và module nào có thể bật tắt. | `admin:read` | Không | Không |
| `module_set` | Bật hoặc tắt module tùy chọn (`key` phải là một trong `settable`). | `settings:write` | Có | Không |

### Email và cảnh báo {#email-and-alerts}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `smtp_get` | Cài đặt email gửi đi (mật khẩu bị ẩn) và trạng thái hàng đợi. | `admin:read` | Không | Không |
| `smtp_configure` | Thiết lập máy chủ SMTP. Việc thay đổi host, port hoặc bảo mật sẽ yêu cầu nhập lại mật khẩu. | `settings:write` (+ `secrets:write` cho mật khẩu) | Có | Không |
| `smtp_test` | Gửi email thử nghiệm thực tế với các cài đặt đã lưu. | `settings:write` | Gửi một email | Không |
| `telegram_get` | Các kênh thông báo của quản trị viên (chat id; bot token không bao giờ được trả về). | `admin:read` | Không | Không |
| `telegram_configure` | Thêm hoặc cập nhật kênh cảnh báo Telegram (bot token và chat id) và bật hoặc tắt cảnh báo quản trị viên. | `settings:write` (+ `secrets:write` cho token) | Có | Không |
| `telegram_test` | Gửi tin nhắn thử nghiệm đến kênh Telegram. | `settings:write` | Gửi một tin nhắn | Không |

### Thanh toán và tiền tệ {#payments-and-currency}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `payments_get` | Trạng thái của Stripe, PayPal, crypto (USDT) và chuyển khoản ngân hàng, cùng các kênh được kích hoạt và phí. | `admin:read` | Không | Không |
| `payment_configure` | Thiết lập thông tin xác thực cho một cổng (`stripe`, `paypal`, `crypto` hoặc `bank`). | `billing:write` (+ `secrets:write`) | Có | Luôn luôn |
| `payment_test` | Kiểm tra thông tin xác thực đã lưu của cổng thanh toán với nhà cung cấp. | `billing:write` | Không | Không |
| `currency_get` | Đơn vị tiền tệ hiển thị và tỷ giá USD sang VND (tự động hoặc thủ công). | `admin:read` | Không | Không |
| `currency_set` | Đặt đơn vị tiền tệ hiển thị và/hoặc tỷ giá thủ công (0 nghĩa là tự động, nếu không sẽ từ 15000 đến 50000). | `billing:write` | Có | Khi bạn thay đổi tỷ giá thủ công |

### Hạ tầng và zone {#infrastructure-and-zones}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `cloudstack_get` | Endpoint CloudStack đã lưu cùng zone id và network id (các key bị ẩn). | `admin:read` | Không | Không |
| `cloudstack_test` | Kiểm tra endpoint với API key và secret mà không lưu; liệt kê các zone. | `infra:write` (+ `secrets:write`, vì bạn truyền các key) | Không | Không |
| `cloudstack_connect` | Lưu kết nối CloudStack. | `infra:write` (+ `secrets:write`) | Có | Luôn luôn |
| `proxmox_list` | Các cụm Proxmox VE được thêm làm nguồn, cùng tình trạng hoạt động. | `admin:read` | Không | Không |
| `proxmox_add` | Thêm cụm Proxmox VE bằng API token (`user@realm!tokenid`) và secret của nó. | `infra:write` (+ `secrets:write`) | Có | Không |
| `proxmox_test` | Kết nối tới cụm theo id; lần thành công đầu tiên sẽ ghim chứng chỉ TLS của cụm. | `infra:write` | Có | Không |
| `proxmox_attach_zone` | Bán cụm Proxmox trong một zone hiện có, tùy chọn với một node làm region. | `infra:write` | Có | Không |
| `zones_list` | Các zone (vị trí) mà khách hàng có thể chọn. | `admin:read` | Không | Không |
| `zone_create` | Tạo một zone. | `infra:write` | Có | Không |

### Danh mục và gói cước {#catalog-and-plans}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `templates_list` | Template OS khách hàng có thể cài đặt. | `admin:read` | Không | Không |
| `templates_sync` | Import OS template từ CloudStack. | `catalog:write` | Có | Không |
| `template_update` | Bật hoặc ẩn template, đổi tên, đặt user đăng nhập hoặc thứ tự sắp xếp. | `catalog:write` | Có | Không |
| `offerings_list` | Service offering của CloudStack (CPU, RAM, root disk) dùng để tạo gói dịch vụ. | `admin:read` | Không | Không |
| `plans_list` | Các gói dịch vụ với giá mỗi giờ và mỗi tháng, cấu hình, zone và số lượng server đang sử dụng. | `admin:read` | Không | Không |
| `plan_create` | Tạo gói dịch vụ. Giá theo `hourly_usd`. Gói CloudStack cần `cs_offering_id`; gói Proxmox cần `backend_id`. | `catalog:write` | Có | Không |
| `plan_update` | Đổi tên, hiện hoặc ẩn, bật hoặc tắt, hoặc định giá lại gói dịch vụ. Thay đổi cấu hình của gói đang được sử dụng sẽ cần tạo bản sao. | `catalog:write` | Có | Khi giá thay đổi |
| `plans_from_offerings` | Tạo bảng gói dịch vụ khởi đầu từ offering (hoặc cấu hình Proxmox) dựa trên chi phí và phần trăm biên lợi nhuận của bạn. Trả về bản xem trước; gọi lại với `apply=true` để tạo các gói dịch vụ. | `catalog:write` | Với `apply=true` | Luôn hỏi khi áp dụng |
| `quota_defaults_get` | Hạn mức khách hàng mặc định. | `admin:read` | Không | Không |
| `quota_defaults_set` | Thay đổi cài đặt `quota_*`. | `catalog:write` | Có | Không |
| `coupons_list` | Các đợt mã giảm giá và mã quà tặng. | `admin:read` | Không | Không |
| `coupon_create` | Tạo một đợt mã: loại `money` (mệnh giá tính bằng cent USD) hoặc `percent` (1 đến 100, kèm mức giảm tối đa). | `catalog:write` | Có | Luôn luôn |

### Khách hàng và đại lý {#customers-and-resellers}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `customers_search` | Tìm kiếm khách hàng theo email, tên hoặc IP. | `admin:read` | Không | Không |
| `customer_get` | Tài khoản, số dư, server và thanh toán gần đây của một khách hàng. | `admin:read` | Không | Không |
| `customer_adjust_balance` | Cộng (dương) hoặc trừ (âm) số dư bằng cent USD. Bắt buộc nhập lý do. | `billing:write` | Có | Luôn luôn |
| `customer_block` | Chặn khách hàng, tuỳ chọn dừng các server của họ. Bắt buộc nhập lý do. | `customers:write` | Có | Luôn luôn |
| `customer_unblock` | Bỏ chặn khách hàng. | `customers:write` | Có | Không |
| `resellers_list` | Các đại lý cùng ví tiền và trạng thái. | `admin:read` | Không | Không |
| `reseller_get` | Trang web, ví tiền, người dùng và cổng thanh toán của một đại lý. | `admin:read` | Không | Không |

### Nhà cung cấp AI {#ai-provider}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `ai_provider_get` | Nhà cung cấp tương thích OpenAI được AI Chat và AI Agent của khách hàng sử dụng (key đã được ẩn). | `admin:read` | Không | Không |
| `ai_provider_set` | Thiết lập nhà cung cấp: base URL, model, API key, fallback model, reasoning effort, enabled. | `ai:write` (+ `secrets:write` dành cho key) | Có | Không |
| `ai_provider_test` | Đặt một câu hỏi cho nhà cung cấp đã lưu để kiểm tra xem có hoạt động không. | `ai:write` | Không | Không |

### Tệp cấu hình {#configuration-files}

| Công cụ | Chức năng | Scope | Thay đổi dữ liệu | Yêu cầu xác nhận |
|---|---|---|---|---|
| `config_export` | Xuất cấu hình dưới dạng YAML (thông tin bảo mật trở thành tham chiếu `secret://`). | `admin:read` | Không | Không |
| `config_plan` | So sánh cấu hình YAML với trang quản trị đang chạy và liệt kê các thay đổi. | `admin:read` | Không | Không |
| `config_apply` | Áp dụng cấu hình YAML theo từng phần. Mỗi thay đổi đều tuân theo các quy tắc phạm vi và xác nhận thông thường. | `admin:read` + phạm vi của từng thay đổi | Có | Với mỗi thay đổi |

Xem [Cấu hình dưới dạng code](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/) để biết định dạng tệp.

## Prompt {#prompts}

Server cũng cung cấp ba prompt có sẵn để client có thể hiển thị dưới dạng phím tắt:

| Prompt | Đối số | Yêu cầu AI thực hiện |
|---|---|---|
| `initial-setup` | không có | Gọi `setup_checklist`, giải thích từng bước chưa hoàn tất trong một câu, hỏi bạn thông tin cần thiết, thực hiện bước đó bằng công cụ phù hợp, xem trước các thay đổi về chi phí hoặc bảo mật, và kết thúc bằng `system_health`. |
| `add-proxmox` | `endpoint` (tuỳ chọn, `https://host:8006`) | Yêu cầu cung cấp API token, sau đó là `proxmox_add`, `proxmox_test`, các công cụ zone và `proxmox_attach_zone`; tiếp theo đề xuất các gói dịch vụ bằng `plans_from_offerings` và chờ bạn phê duyệt. |
| `launch-pricing` | `margin_pct` (tuỳ chọn, mặc định 40) | Hỏi chi phí hàng tháng trên mỗi vCPU, mỗi GB RAM và mỗi GB ổ đĩa của bạn, hiển thị bảng xem trước gồm chi phí, giá mỗi tháng và giá mỗi giờ, sau đó tạo các gói sau khi bạn phê duyệt. |

## Xác nhận (`confirm_token`) {#confirmation-confirm-token}

Các thao tác luân chuyển tiền, xóa dữ liệu, thay đổi thông tin thanh toán hoặc bảo mật đăng nhập đều gồm hai bước:

1. Lần gọi đầu tiên không thay đổi điều gì. Kết quả của tool bắt đầu bằng "CONFIRMATION REQUIRED" và kèm theo một **bản xem trước** (thao tác nào sẽ được gọi, vì sao thao tác này nhạy cảm, các giá trị mới và giá trị hiện tại) cùng một `confirm_token`.
2. Client phải hiển thị bản xem trước cho bạn. Chỉ sau khi bạn phê duyệt, client mới gọi lại tool đó với cùng các đối số cộng thêm `confirm_token`.
3. Token chỉ dùng được một lần, riêng cho yêu cầu chính xác đó và hết hạn sau 5 phút.

Hướng dẫn của server chỉ định AI xem kết quả tool là dữ liệu chứ không phải chỉ thị, và không bao giờ được lặp lại lệnh gọi bằng token mà bạn chưa phê duyệt. Bạn chính là chốt chặn an toàn: hãy đọc kỹ bản xem trước.

::: warning Không tự động phê duyệt
Một số client có thể tự động phê duyệt mọi lệnh gọi tool. Đối với các write tool, hãy bật chế độ phê duyệt cho từng lệnh gọi hoặc dùng key chỉ đọc (read-only), để kế hoạch sai từ AI không thể tác động đến panel của bạn mà bạn không biết.
:::

## Cách thức hoạt động {#how-it-works}

| Hạng mục | Chi tiết |
|---|---|
| Giao thức truyền tải | `POST /mcp/admin` với thông điệp JSON-RPC 2.0; phản hồi là `application/json`. Tối đa 20 thông điệp trong một batch. `GET /mcp/admin` trả về 405 (không có server stream); `DELETE /mcp/admin` kết thúc một phiên. |
| Xác thực | `Authorization: Bearer ak_...` (key thủ công hoặc access token OAuth). Thiếu hoặc sai thông tin xác thực sẽ trả về 401 kèm `WWW-Authenticate: Bearer ... resource_metadata=...`, cho phép các OAuth client tự khởi tạo đăng nhập. |
| Phiên | `Mcp-Session-Id` được cấp bởi `initialize`, liên kết với key đó và có hiệu lực trong 24 giờ. |
| Capabilities | Tools và prompts. Không có resources. |
| Kích thước | Request body tối đa 1 MB; kết quả của tool bị cắt ngắn sau khoảng 100 KB. |
| Origin | Request mang header `Origin` từ trang khác sẽ bị từ chối (`origin_not_allowed`). Client dòng lệnh và desktop không gửi header này. |
| Cùng cơ chế kiểm soát như REST | Mỗi lệnh gọi tool được gửi lại qua pipeline xử lý request của chính panel bằng key của bạn, vì vậy các scope, dải IP, rate limit, xác nhận và nhật ký hoạt động đều áp dụng y hệt như các lệnh gọi API trực tiếp. |

## Hạn mức & lưu ý {#limits-notes}

- Nếu không thấy một tool nào đó, tức là bạn chưa cấp scope tương ứng. Hãy thêm scope vào một key mới.
- Thiết lập mật khẩu hoặc API key qua AI client đồng nghĩa với việc thông tin bí mật sẽ đi qua AI đó. Nếu muốn, bạn có thể tắt `secrets:write` và tự nhập các thông tin bí mật trong admin, hoặc dùng trường **Secret** của AI Chat ([AI Chat trong admin](https://nexcmp.com/vi/docs/configure-with-ai/ai-chat-in-admin/#secrets)) hay các tham chiếu `secret://` ([Cấu hình dưới dạng code](https://nexcmp.com/vi/docs/configure-with-ai/config-as-code/#secrets)).
- Các client không chia sẻ phiên với nhau: mỗi kết nối đều bắt đầu bằng `initialize`.
- Thu hồi key trong **API & AI agents** để ngắt kết nối của AI client ngay lập tức.

## Xử lý sự cố {#troubleshooting}

| Hiện tượng | Nguyên nhân | Cách khắc phục |
|---|---|---|
| 401 `invalid_key` | Key sai, bị cắt ngắn hoặc không có quyền admin (ví dụ key `vk_`) | Dùng key `ak_`. |
| 401 `key_expired` hoặc `key_revoked` | Key đã hết hạn hoặc bị thu hồi | Tạo một key mới. |
| 403 `ip_not_allowed` | IP của bạn nằm ngoài các dải IP của key | Kết nối từ một IP được cho phép. |
| 403 `origin_not_allowed` | Một trang trình duyệt từ origin khác đã gọi endpoint này | Dùng client desktop hoặc CLI. |
| 404 đối với request có `Mcp-Session-Id` | Phiên thuộc về một key khác hoặc đã hết hạn | Gửi lại `initialize`. |
| 400 unsupported `MCP-Protocol-Version` | Client sử dụng phiên bản mà server không nhận biết | Cập nhật client; hỗ trợ: 2025-11-25, 2025-06-18, 2025-03-26. |
| Danh sách tool bị ngắn | Scope của key | Tạo một key có nhiều scope hơn. |
| `insufficient_scope` trong một lệnh gọi | Công cụ cần thêm một scope thứ hai, ví dụ `secrets:write` | Thêm scope đó vào một key mới. |
| 429 `rate_limited` | Số lượt gọi mỗi phút vượt quá giới hạn của key | Chờ đến `Retry-After` hoặc tăng giới hạn trên một key mới. |
| claude.ai hoặc ChatGPT không thể kết nối | URL không truy cập được từ internet, hoặc proxy chặn `/mcp/admin` hoặc `/oauth-admin/` | Kiểm tra DNS, TLS và reverse proxy. |

Để xem tất cả mã lỗi, hãy xem [Admin API keys](https://nexcmp.com/vi/docs/configure-with-ai/admin-api-keys/#errors).