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

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.

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 (endpoint /mcp/admin, admin keys ak_).

Yêu cầu

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 (`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

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)

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.

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.

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

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

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

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

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

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.
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ả.
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 ý

Đă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ố

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`.

MCP server ​

Chức năng ​

Yêu cầu ​

Chuẩn bị hạ tầng ​

Kết nối (phía khách hàng) ​

Cách thức hoạt động ​

Quy tắc an toàn ​

Giới hạn ​

Kiểm tra ​

Hạn mức & lưu ý ​

Xử lý sự cố ​