Hướng dẫn MONA Cloud cho AI agent

Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol (MCP). Mục tiêu là thử toàn bộ luồng bằng sandbox miễn phí trước khi tạo hạ tầng tính phí.

Cài MONA Cloud MCP cho agent thế nào?

claude mcp add monacloud -- npx -y monacloud-mcp

{
  "mcpServers": {
    "monacloud": {
      "command": "npx",
      "args": ["-y", "monacloud-mcp"]
    }
  }
}

codex mcp add monacloud -- npx -y monacloud-mcp

https://mcp.monacloud.vn/mcp

Settings → Connectors → Add custom connector, dán URL rồi đăng nhập MONA Pass. Cursor dùng "url": "https://mcp.monacloud.vn/mcp" trong mcp.json; Codex dùng [mcp_servers.monacloud] url = "https://mcp.monacloud.vn/mcp".

MCP monacloud-mcp 0.5.0 và CLI monacloud 0.4.1 đã LIVE. Các tool compute dùng namespace cloud_*:

Các alias cũ vibecloud_* vẫn chạy để giữ tương thích, nhưng tích hợp mới phải dùng tên cloud_* ở trên.

Token nào dùng ở đâu?

Con agent hay kẹt ở chỗ này nên ghi thành bảng, đọc một lần là đủ.

Khách đã đăng ký và đưa sẵn token thì agent không cần đăng nhập gì thêm: đặt MONACLOUD_TOKEN, gọi GET /api/me để xác nhận, rồi làm việc bằng REST hoặc MCP. Không in token ra log, không ghi vào mã nguồn.

Bắt đầu bằng các lệnh nào?

export MONACLOUD_TOKEN=vc_live_...        # khách đưa, hoặc lấy từ console → API keys
curl -s https://api.monacloud.vn/api/me -H "Authorization: Bearer $MONACLOUD_TOKEN"
curl -s https://api.monacloud.vn/openapi.json | head -c 400   # đọc hợp đồng thật trước khi gọi

Có Node thì chạy npx -y monacloud deploy để đưa thư mục hiện tại lên web, không cần GitHub. CLI monacloud 0.4.1 tự tải MCP qua npx; đặt MONACLOUD_TOKEN là chạy. Thêm --git để dùng remote hiện tại, --repo <url> để chỉ định repo public hoặc --sandbox để thử miễn phí. Không có Node, dùng hai request upload REST ở mục deploy local bên dưới.

Đăng nhập MONA Pass thế nào?

npx -y monacloud-mcp login

Đăng nhập một lần bằng MONA Pass. MCP lưu token cục bộ và dùng cùng phiên đăng nhập cho nhóm sản phẩm MONA Cloud; không yêu cầu người dùng gửi username, password hoặc token vào chat. MONA Cloud nhận trực tiếp JWT có audience vibecloud.

Với curl, đặt access token MONA Pass vào biến môi trường của phiên shell, không ghi vào source hoặc log:

export MONACLOUD_API="https://api.monacloud.vn"
export MONA_PASS_TOKEN="<access-token>"

https://api.vibecloud.vn là alias tương thích của API và được giữ trong 12 tháng, đến hết ngày 04/09/2027. Tích hợp mới phải dùng https://api.monacloud.vn.

Chuỗi thử từng bước trong sandbox

Các lệnh tạo tài nguyên dưới đây dùng prefix /api/sandbox. Có thể gọi route /api/... tương ứng với header X-Vibecloud-Sandbox: 1 để nhận cùng hành vi.

1. Đọc bảng giá

Với MCP, gọi cloud_prices hoặc cloud_packages.

curl -sS "$MONACLOUD_API/api/prices"

2. Tạo VPS sandbox

Với MCP, gọi cloud_vps_create sau khi đã xác nhận cấu hình và chi phí.

curl -sS -X POST "$MONACLOUD_API/api/sandbox/lxc" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"agent-demo","cpu":1,"ram_gb":1,"disk_gb":10}'

Lưu trường id thành VPS_JOB_ID. Response luôn có sandbox: true và IP giả thuộc dải 10.99.x.x.

3. Poll job tới done

Với MCP, gọi cloud_job_status với job_id vừa nhận.

export VPS_JOB_ID="<id-tu-buoc-2>"
curl -sS "$MONACLOUD_API/api/jobs/$VPS_JOB_ID" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

Lookup theo ID tự tìm trong kho sandbox nếu không có bản ghi thật, nên poll GET /api/jobs/{id} không cần gửi lại header sandbox. Job sandbox chuyển queued → running → done sau vài giây. Chỉ đọc result khi trạng thái là done; job thật dùng trạng thái hoàn tất succeeded.

4. Tạo database sandbox

Với MCP, gọi cloud_db_create, sau đó theo dõi bằng cloud_job_status.

curl -sS -X POST "$MONACLOUD_API/api/sandbox/databases" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"agent-demo-db","engine":"postgresql","cpu":1,"ram_gb":1,"disk_gb":10}'

Poll id của response qua /api/jobs/{id} như bước 3. Credential, connection string và IP trong sandbox chỉ là dữ liệu giả để kiểm tra tích hợp.

engine nhận mongodb, postgresql, mysql; alias cũ mongo được chuẩn hoá thành mongodb. Với route thật, backend kiểm tra template đã resolve trên Proxmox trước khi nhận job (inventory cache 10 phút). PostgreSQL/MySQL mặc định dùng template Ubuntu từ PROXMOX_LXC_TEMPLATE rồi cài engine lúc provision; nếu operator cấu hình template riêng thì backend dùng đường nhanh đó.

Khi template chưa có, API trả thẳng HTTP 409 (không tạo job):

{
  "code": "engine_not_available",
  "message": "Engine được yêu cầu tạm không khả dụng; chọn engine trong phản hồi API",
  "next_step": "Chọn engine đang khả dụng hoặc thử lại sau khi template đã được cài trên node Proxmox."
}

Route sandbox không kiểm tra inventory Proxmox. Job thật công bố stages[]; mỗi stage có status là running, succeeded hoặc failed, cùng started_at, completed_at và duration_seconds để agent theo dõi thời gian provision.

Connection string khi thành công:

• PostgreSQL: postgresql://user:password@host:5432/database?sslmode=require
• MySQL: mysql://user:password@host:3306/database (server bắt buộc TLS)
• MongoDB: mongodb://user:password@host:27017/database?authSource=database&tls=true

5. Lấy credential rồi deploy

Backend MONA Cloud provision hạ tầng; agent deploy source qua SSH sau khi job hoàn tất. Lấy service_id trong result, đọc service trước, rồi gọi endpoint reveal riêng khi thực sự cần SSH. Service detail và job result không trả private key hay root password.

Với MCP, dùng cloud_services_list để lấy danh sách tài nguyên hiện tại.

export VPS_SERVICE_ID="<service_id-trong-result>"
curl -sS "$MONACLOUD_API/api/services/$VPS_SERVICE_ID" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

curl -sS "$MONACLOUD_API/api/services/$VPS_SERVICE_ID/credentials" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN" \
  -H "X-Confirm: reveal"

Endpoint reveal được audit và giới hạn 5 lần/giờ/token. Với service thật, dùng credential vừa reveal để rsync source, cài dependency, đưa secret database vào biến môi trường, chạy migration và kiểm tra health URL. Không thử SSH vào IP 10.99.x.x; đó là IP giả của sandbox.

6. Dừng service

Với MCP, gọi cloud_service_stop.

curl -sS -X POST "$MONACLOUD_API/api/services/$VPS_SERVICE_ID/stop" \
  -H "Authorization: Bearer $MONA_PASS_TOKEN"

Thử miễn phí bằng sandbox hoạt động thế nào?

Sandbox không gọi Proxmox, không cấp IP thật và không trừ tiền. Service và job được lưu tách bằng sandbox: true; dashboard trả chúng trong nhóm sandbox, không trộn với service thật. MongoDB tự dọn dữ liệu khi hết TTL, mặc định 24 giờ.

Sau khi tạo sandbox, các endpoint theo ID GET /api/jobs/{id}, GET /api/services/{id}, POST /api/services/{id}/start|stop|rebuild và DELETE /api/services/{id} tự fallback sang kho sandbox, không cần header. Response sandbox vẫn luôn có sandbox: true.

Endpoint danh sách vẫn tách biệt: không header chỉ trả tài nguyên thật, có header chỉ trả sandbox. Thêm ?include_sandbox=1 vào GET /api/jobs hoặc GET /api/services để gộp cả hai.

Dùng một trong hai cách:

• Prefix: /api/sandbox/lxc, /api/sandbox/databases, /api/sandbox/jobs/{id}, /api/sandbox/services*.
• Header: thêm X-Vibecloud-Sandbox: 1 khi tạo qua /api/lxc, /api/databases, hoặc khi muốn list riêng sandbox qua /api/jobs, /api/services.

Bảng endpoint cho agent

Mã lỗi và cách xử lý

Điều agent hay hiểu sai

• stop chỉ dừng compute. Disk và IP của service thật vẫn được giữ và tiếp tục tính phí; phải DELETE /api/services/{id} mới ngừng toàn bộ phí.
• Provision và rebuild là job bất đồng bộ. Nhận job_id chưa có nghĩa là xong; phải poll tới succeeded với job thật hoặc done với sandbox.
• IP, credential và connection string sandbox đều là giả. Không báo với người dùng rằng ứng dụng đã online sau một job sandbox.
• Custom domain dạng subdomain nên dùng CNAME trỏ vào hostname được cấp. Không đặt CNAME trực tiếp vào địa chỉ IP; apex domain cần A/ALIAS phù hợp nhà cung cấp DNS.
• Không gửi đồng thời package_slug và bộ cpu/ram_gb/disk_gb.
• Không đưa token, private key hoặc password database vào commit, issue hay output công khai.

Bản đồ tài liệu cho agent

• OpenAPI máy đọc: https://api.monacloud.vn/openapi.json
• Swagger: https://api.monacloud.vn/docs
• Tài liệu agent raw: https://monacloud.vn/ai-agent
• Hướng dẫn API đầy đủ: https://api.monacloud.vn/api/guide
• Mục lục cho LLM: https://monacloud.vn/llms.txt
• Ngữ cảnh đầy đủ cho LLM: https://monacloud.vn/llms-full.txt

Trước khi tạo tài nguyên thật, agent phải đọc giá, xác nhận cấu hình, chạy luồng sandbox và chỉ chuyển sang route thật khi người dùng yêu cầu rõ ràng.

Prompt mẫu cho AI

Đọc hướng dẫn này, kiểm tra giá và ví trước khi thao tác. Thử sandbox, xác minh sandbox: true và poll tới done. Báo cấu hình cùng chi phí VND, chỉ tạo tài nguyên tính phí sau khi tôi đồng ý. Không đưa token hoặc credential vào chat.

Deploy app từ git đã LIVE

Luồng deploy cho repo public

1. Đăng nhập, đọc dự án và thử bằng MCP

Đăng nhập MONA Pass bằng npx -y monacloud-mcp login. Dùng MCP monacloud-mcp 0.5.0 và CLI monacloud 0.4.1. Giao prompt sau cho AI:

Đọc repo của tôi. Gọi cloud_app_list và cloud_app_host_list để tránh tạo trùng, cloud_prices, cloud_plan_list và cloud_balance để tính phí. Nếu chưa có host, gọi cloud_app_create với repo_url, branch, build_type, port đúng dự án và sandbox=true. Báo ước tính để tôi duyệt. Sau khi được duyệt, gọi cloud_app_create với sandbox=false, poll bằng cloud_job_status, kiểm cloud_app_get/cloud_app_logs và HTTPS rồi trả URL.

2. Deploy bằng CLI thế nào?

CLI dùng npx -y monacloud deploy --repo <url>. Ví dụ dưới đây dùng repo Node.js mẫu có Dockerfile; thay URL, nhánh, kiểu build và cổng theo dự án của bạn:

npx -y monacloud deploy --repo https://github.com/themonagroup/monacloud-example-node --branch main --build dockerfile --sandbox
npx -y monacloud deploy --repo https://github.com/themonagroup/monacloud-example-node --branch main --build dockerfile

Lần đầu chạy thử miễn phí; lệnh thứ hai hiển thị ước tính và hỏi duyệt trước khi tạo thật. --build nhận dockerfile, nixpacks hoặc static. Với repo hiện tại có remote và nhánh, chạy npx -y monacloud deploy --git. Không có cờ nguồn, CLI deploy thư mục hiện tại. Chọn một công cụ tạo app: nếu AI đã deploy ở bước 1 thì dùng ID đó để kiểm tra, không tạo lại bằng CLI.

3. Gọi API và đọc kết quả thế nào?

Nếu dùng curl thay cho MCP/CLI, đặt token theo bắt đầu nhanh và thử POST /api/apps:

curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "X-Vibecloud-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/themonagroup/monacloud-example-node","branch":"main","build_type":"dockerfile","dockerfile":"Dockerfile","port":3000}'

Sau khi duyệt phí, bỏ header X-Vibecloud-Sandbox: 1 để tạo thật. API trả job có id; thay JOB_ID bằng ID nhận được và đọc tới trạng thái cuối:

export JOB_ID="<job-id-tra-ve>"
curl -sS "$MONACLOUD_API/api/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN"

Lấy result.app_id, đọc GET /api/apps/{app_id} để kiểm tra status, url, last_deploy và errorMessage. Khi timeout, đọc lại job cũ trước; không gửi create lặp. Quản lý app tại console /apps.

Kết quả mong đợi khi deploy git là gì?

App từ git đã LIVE, đo ngày 05/09/2026: repo git public → app host riêng của user (LXC + Dokploy, tạo lần đầu ~150 giây) → deploy 10–20 giây → URL https://<repo>-<mã>.app.monacloud.vn có cert Let's Encrypt.

Ví dụ thật: https://monacloud-example-node-3fb5b2.app.monacloud.vn, từ repo mẫu Node.js. Xoá app → tạo lại: 31 giây khi đã có app host. Đây là số đo của repo mẫu; thời gian build dự án của bạn phụ thuộc source, dependency và tài nguyên.

Job thật kết thúc ở succeeded; trạng thái app là done. Sandbox kết thúc ở done, có sandbox: true và URL giả; không có website thật. Kiểm tra HTTPS và chức năng app trước khi chuyển traffic.

Gói tháng 399.000đ, 999.000đ, 1.990.000đ, 3.990.000đ mỗi tháng, trả năm bằng giá 10 tháng; khách MONA gói miễn phí, credit đăng ký 100.000đ. App host tính như VPS, app không tính thêm. Repo private đang mở qua GitHub App.

POST /api/app-hosts với {} tạo host mặc định 2 CPU/2 GB RAM/30 GB disk; route này không nhận sandbox. Dùng POST /api/apps với X-Vibecloud-Sandbox: 1 để mô phỏng host và xem ước tính, không tính phí. Khi dùng gói tháng, tạo host với billing_mode, plan_code, period, rồi truyền app_host_id vào app create.

Xem triển khai repo mẫu cho số đo ~150 giây / 10–20 giây / 31 giây, URL HTTPS thật và cách poll job. OpenAPI giữ nguyên schema nguồn; route tải .pdf trả file theo summary, dù schema nguồn vẫn khai báo response JSON tổng quát. CLI/MCP có lệnh tải file riêng.

Deploy từ thư mục local, không cần GitHub

MCP monacloud-mcp 0.5.0 và CLI monacloud 0.4.1 đã hỗ trợ source local. Đặt MONACLOUD_TOKEN là chạy; CLI tự tải MCP qua npx. Ví local đọc số dư qua GET /api/me. Chọn một trong ba cách dưới đây; app host tính phí như VPS, app không tính thêm.

1. MCP tool: detect rồi create

cloud_app_detect(local_dir) đoán stack/port/Dockerfile, offline. Sau đó cloud_app_create({local_dir}) tự đóng zip và upload; thao tác tạo app cần kết nối MONA Cloud. local_dir là đường dẫn tuyệt đối trên máy đang chạy MCP.

{"local_dir":"/duong-dan-tuyet-doi/du-an"}

Dùng đối số này cho cloud_app_detect, đọc kết quả, rồi gọi cloud_app_create với cùng local_dir và cấu hình build/cổng phù hợp. Đọc giá và ví, thử sandbox: true để mô phỏng, không tính phí và duyệt phí trước khi tạo thật; poll bằng cloud_job_status, kiểm tra cloud_app_get và cloud_app_logs.

Prompt mẫu cho Claude Code/Codex:

Đưa dự án trong thư mục này lên web bằng MONA Cloud. Token ở biến MONACLOUD_TOKEN. Dùng cloud_app_detect rồi cloud_app_create với local_dir, xong đưa tôi link https.

2. CLI: chạy ngay trong thư mục dự án

Có Dockerfile/package.json trong thư mục hiện tại và MONACLOUD_TOKEN trong môi trường:

npx -y monacloud deploy --sandbox
npx -y monacloud deploy

Lệnh có --sandbox thử miễn phí và trả URL giả; sau khi duyệt phí, chạy lệnh thứ hai để deploy thật. CLI mặc định deploy thư mục hiện tại, kể cả khi thư mục có git remote. Dùng --git để lấy remote hiện tại hoặc --repo <url> nếu có URL GitHub public. --build nixpacks dùng khi không có Dockerfile và stack hỗ trợ Nixpacks.

3. Curl: tạo app upload rồi gửi archive

Hai request dưới đây tạo app thật sau khi đã duyệt phí host. Để thử miễn phí, dùng CLI --sandbox hoặc MCP sandbox: true ở trên.

POST /api/apps thêm source: "git" | "upload". Với source=upload, không cần repo_url. Ví dụ dưới đây dùng app có Dockerfile, cổng 3000; chỉnh theo dự án. Đặt MONACLOUD_TOKEN trong phiên shell và MONACLOUD_API=https://api.monacloud.vn.

Tạo app chờ upload:

curl -sS -X POST "$MONACLOUD_API/api/apps" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"upload","build_type":"dockerfile","port":3000}'

Phản hồi có dạng:

{
  "id": "<app-id>",
  "upload_url": "/api/apps/<app-id>/upload",
  "max_bytes": 83886080,
  "job_id": "<job-id>",
  "status": "awaiting_upload",
  "url": "<url-https-cua-app>"
}

id là ID app, job_id là ID job. awaiting_upload chưa phải deploy xong. Gán APP_ID bằng id vừa nhận. Chuẩn bị app.zip sao cho Dockerfile hoặc các file ứng dụng nằm ngay gốc archive, rồi gửi lệnh thứ hai:

APP_ID="<app-id-tra-ve>"
curl -sS -X POST "$MONACLOUD_API/api/apps/$APP_ID/upload" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -F [email protected] \
  -F build_path=/

POST /api/apps/{id}/upload nhận multipart archive (zip hoặc tar.gz ≤ 80 MB) + build_path (mặc định /). Có thể đổi sang -F [email protected]. Không đặt Content-Type: application/json cho upload; curl tự tạo multipart boundary.

Server tự loại node_modules/, .git/, .env*, *.pem; chặn zip-slip; file phải nằm ở gốc archive, không bọc thêm một thư mục.

Upload trả job id, sau đó poll GET /api/jobs/{id} như git, dùng ID job trong phản hồi upload. Đợi job trả succeeded, đọc GET /api/apps/{app_id} rồi kiểm tra URL HTTPS. Nếu job lỗi, đọc lỗi và log trước khi thử lại; không tạo app mới liên tục. Đọc API reference cho schema.

Kết quả mong đợi khi deploy từ thư mục local là gì?

Đây là số đo thực tế, không phải cam kết thời gian build cho mọi dự án.

Lỗi thường gặp khi upload

Gói tháng và hoá đơn đã LIVE

Gói tháng đang bán có những mức nào?

Khách MONA có gói miễn phí theo quyền tài khoản; credit tặng 100.000đ khi đăng ký. Đọc GET /api/plans hoặc cloud_plan_list để lấy code, CPU/RAM/disk và giá tháng/năm hiện hành. Backup PBS đang mở; không coi dòng cấu hình gói là bằng chứng đã có restore.

Mua và quản lý gói qua CLI hoặc API thế nào?

npx monacloud plans
npx monacloud vps create --plan kinh-doanh --monthly
npx monacloud invoices

Chọn mã gói từ danh sách trả về. API tạo VPS dùng POST /api/lxc với app_name, billing_mode: "monthly", plan_code và period: "month" hoặc "year"; không trộn package hoặc custom sizing. App host dùng POST /api/app-hosts với cùng các trường tính phí, rồi truyền app_host_id cho POST /api/apps.

Đọc GET /api/subscriptions để kiểm tra kỳ và gia hạn. POST /api/services/{service_id}/subscription nhận plan_code, period, auto_renew, cancel_action. Nâng gói tính phần thời gian còn lại; hạ gói từ kỳ sau. Tắt gia hạn bằng auto_renew: false; chọn cancel_action: "hourly" hoặc "stop" và kiểm tra kỳ hiệu lực trả về.

MCP có cloud_subscription_list và cloud_subscription_update. CLI/MCP thử cấu hình gói qua hourly sandbox miễn phí, không tạo subscription sandbox; vẫn báo giá kỳ thật trước khi bạn duyệt.

Xem hoá đơn VAT mỗi tháng ở đâu?

Hoá đơn VAT 10% mỗi tháng đã LIVE. Mở console /invoices, dùng GET /api/invoices hoặc cloud_invoice_list. Tải file bằng GET /api/invoices/{invoice_id}.pdf, cloud_invoice_pdf hoặc npx monacloud invoices --pdf <id>.

Đọc số tiền và thuế trên hoá đơn của tài khoản. Danh sách nạp ví GET /api/payments là dữ liệu thanh toán riêng. Quản lý gói tại console /subscriptions; đăng nhập MONA Pass đã bật.

Dùng mã credit như thế nào?

Console đã có redeem mã credit. MCP dùng cloud_credit_redeem với mã bạn nhận được; API dùng:

curl -sS -X POST "$MONACLOUD_API/api/credit-codes/redeem" \
  -H "Authorization: Bearer $MONACLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"<ma-credit-cua-ban>"}'

Đặt token theo bắt đầu nhanh; kiểm tra kết quả và số dư sau khi đổi mã. Xem API reference cho schema đầy đủ.