---
title: MCP server
description: Kết nối trợ lý AI (Claude, Cursor, VS Code...) với API hệ thống qua endpoint MCP tại /mcp — xác thực, cấu hình client, tools và quy tắc an toàn.
url: https://nexcmp.com/vi/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# MCP server {#mcp-server}

> **Vị trí trong portal:** API reference › Tools (`https://<your-domain>/apidoc`) hiển thị endpoint và các đoạn code client; khóa được tạo tại API keys (`/api-keys`). Không có cài đặt nào trong admin: endpoint là một phần của panel.

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

**Model Context Protocol (MCP)** cho phép trợ lý AI gọi các tool. NexCMP cung cấp một endpoint MCP tại `https://<your-domain>/mcp`. Mỗi thao tác API công khai trở thành một **tool** (`vm_list`, `vm_start`, `billing_wallet`,...), do đó khách hàng có thể hỏi trợ lý của họ "những VM nào của tôi đang chạy?" hoặc "dừng VM staging". Trợ lý chỉ hoạt động với API key và quyền hạn của chính khách hàng.

::: tip Cấu hình NexCMP bằng AI?
Trang này nói về endpoint MCP cho **khách hàng** (`/mcp`). Để cho phép trợ lý AI cấu hình panel của bạn với tư cách quản trị viên, hãy xem [Configure with AI](https://nexcmp.com/vi/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, admin keys `ak_`).
:::

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

| Hạng mục | Yêu cầu |
|---|---|
| Máy chủ | Không cần cài đặt gì: endpoint được phân phối bởi panel và có thể truy cập ở bất kỳ đâu panel hoạt động. Reverse proxy của bạn phải chuyển tiếp `/mcp` đến panel. |
| Khách hàng | Một [API key](https://nexcmp.com/vi/docs/developers/api-keys/) (`vk_...`) với các scope mà trợ lý cần. |
| Client | Một MCP client hỗ trợ transport **Streamable HTTP** và header `Authorization` tùy chỉnh: Claude Code, Claude Desktop (thông qua bridge `mcp-remote`), Cursor, VS Code với Copilot agent mode và các công cụ tương tự. |
| Phiên bản giao thức | 2025-11-25, 2025-06-18 và 2025-03-26. |

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

Không có gì, ngoại trừ việc đảm bảo `https://<your-domain>/mcp` không bị chặn bởi tường lửa hoặc quy tắc proxy. MCP client dựa trên trình duyệt từ một origin khác sẽ bị từ chối trừ khi origin đó được cho phép; các client dòng lệnh và desktop không gửi header `Origin` và hoạt động bình thường.

## Kết nối (phía khách hàng) {#connect-customer-side}

1. Tạo một API key trong portal (**API keys › Create key**) chỉ với các scope bạn muốn trợ lý sử dụng, thời hạn ngắn và nếu có thể, giới hạn theo IP.
2. Thêm server vào client của bạn. Thay thế `cloud.example.com` và key.

   **Claude Code**

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

   **Cursor** (`~/.cursor/mcp.json` hoặc `.cursor/mcp.json`; thiết lập `CLOUD_API_KEY` trong môi trường mà Cursor khởi chạy):

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop** (cần Node.js 18+; `claude_desktop_config.json`), thông qua bridge `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" }
       }
     }
   }
   ```

   Viết header không có khoảng trắng sau dấu hai chấm và đặt toàn bộ giá trị vào biến môi trường, như trên.

3. Khởi động lại client và yêu cầu liệt kê các tool của bạn.


Kiểm tra kết nối mà không cần client:

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

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

| Hạng mục | Chi tiết |
|---|---|
| Endpoint | `POST /mcp` với thông điệp JSON-RPC 2.0; phản hồi là `application/json`. `GET /mcp` trả về 405 (không có stream từ server đến client); `DELETE /mcp` kết thúc phiên làm việc. |
| Xác thực | Chỉ `Authorization: Bearer vk_...` (session token, cookie và admin key sẽ bị từ chối với mã 401 cùng header `WWW-Authenticate: Bearer`). |
| Session | `Mcp-Session-Id` được cấp bởi `initialize`, gắn với key đó, có hiệu lực trong 24 giờ; tối đa 16 session cho mỗi key. |
| Công cụ | Một tool cho mỗi thao tác API công khai hiển thị với key. Tên tool là lệnh CLI với `_` thay cho khoảng trắng và dấu gạch ngang (`vm firewall add` trở thành `vm_firewall_add`) và tương đương với OpenAPI `operationId`. Tool chỉ được liệt kê khi key có scope tương ứng và module đã được bật. |
| Capabilities | Chỉ tools (không có resources hoặc prompts). |
| Kích thước | Request body tối đa 1 MB; văn bản kết quả tool tối đa khoảng 100 KB (phần còn lại sẽ bị cắt kèm ghi chú); mỗi lệnh gọi mất tối đa 55 giây. |

### Quy tắc an toàn {#safety-rules}

- **Cùng cơ chế kiểm soát như REST.** Mỗi `tools/call` đều đi qua pipeline xử lý request của chính panel: scope, site, giới hạn IP, rate limit, tính lũy thừa (idempotency), kiểm tra quyền sở hữu (404 đối với tài nguyên của người khác) và quota đều được áp dụng. MCP không thể cấp bất kỳ quyền nào mà key không có.
- **Xác nhận.** Các tool phát sinh chi phí, xóa dữ liệu hoặc trả về thông tin xác thực (ticket console, kubeconfig, secret S3 hoặc SSH, đặt lại mật khẩu, key mới) đều yêu cầu đối số `confirm: true`. Phần mô tả của tool sẽ chỉ dẫn trợ lý chỉ truyền đối số này sau khi người dùng đã phê duyệt, vì vậy chỉ thị ẩn trong trang web hoặc log không thể tự ý kích hoạt.
- **Tính lũy thừa.** Các tool trả phí chấp nhận `idempotency_key`; nếu bỏ trống, một key ổn định sẽ được tạo từ tên tool và các đối số, nhờ đó việc thử lại giống hệt nhau sẽ không bị tính phí hai lần.
- **Không hiển thị dưới dạng tool:** các endpoint streaming (chat AI Agent), ticket WebSocket dùng một lần cho SSH hoặc console, tải xuống file nhị phân và các endpoint của ứng dụng VPN (`/v1/ext/*`).
- **Không bao giờ khả thi:** API không bao giờ cho phép nạp tiền, đổi mật khẩu, xóa tài khoản hoặc tạo key, do đó không trợ lý nào có thể thực hiện các thao tác này.

### Giới hạn {#limits}

| Hạn mức | Mặc định |
|---|---|
| Lượt gọi tool trên mỗi key | 60 mỗi phút |
| Lượt request MCP trên mỗi key | 240 mỗi phút |
| Cộng với các giới hạn thông thường của key và tài khoản | Xem [REST API](https://nexcmp.com/vi/docs/developers/api/#rate-limits) |

Khi vượt quá giới hạn, endpoint sẽ trả về HTTP 429 kèm lỗi JSON-RPC và `Retry-After`.

## Kiểm tra {#verify}

1. Lệnh `curl` ở trên trả về kết quả JSON-RPC với danh sách `tools`. Chỉ các tool phù hợp với scope của key mới xuất hiện.
2. Trong client của bạn, hãy hỏi "list my VMs": trợ lý sẽ gọi `vm_list` và hiển thị kết quả.
3. Trong portal, thời gian **Last used** của key sẽ được cập nhật, và các lệnh gọi ghi sẽ xuất hiện trong **Key usage log**.

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

- **Đăng nhập qua trình duyệt (OAuth).** Trang tài liệu tham khảo cũng mô tả việc đăng nhập qua trình duyệt đối với các client hỗ trợ MCP OAuth. Trong bản cài đặt NexCMP, phương thức được hỗ trợ và đã kiểm thử là API key (hoặc `cmp login` cho CLI).
- **Trang reseller** không hiển thị phần MCP; khách hàng của họ sử dụng domain của reseller cho API.
- **Đặc quyền tối thiểu.** Tạo một key riêng cho từng trợ lý với các scope chỉ đọc trước; chỉ thêm các scope ghi khi cần thiết.
- Thu hồi key trong **API keys** để ngắt quyền truy cập của trợ lý 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 kèm `WWW-Authenticate: Bearer` | Không có key, sai key hoặc là session token | Gửi `Authorization: Bearer vk_...`. |
| 403 về `Origin` | Trang trình duyệt trên một origin khác | Sử dụng desktop client hoặc CLI client; hoặc yêu cầu quản trị viên của bạn cho phép origin (`mcp_allowed_origins`). |
| 404 đối với request có `Mcp-Session-Id` | Session thuộc về key khác hoặc đã hết hạn | Chạy lại `initialize`. |
| 405 đối với `GET /mcp` | Dự kiến: máy chủ không có event stream | Chỉ sử dụng POST (các client tự động thực hiện việc này). |
| Danh sách tool bị ngắn | Scope của key hoặc module | Thêm scope cho key; bật module tương ứng. |
| Tool phản hồi rằng nó cần `confirm: true` | Tool tính phí, xóa hoặc nhạy cảm | Trợ lý phải đặt `confirm` sau khi bạn phê duyệt. |
| 429 | Rate limit của MCP hoặc key | Chờ `Retry-After`. |
| Client không thể kết nối bằng header | Client không hỗ trợ custom-header | Sử dụng bridge `mcp-remote`. |