Bắt đầu nhanh: kết nối AI agent qua MCP

1. Tạo token

1. Đăng nhập bằng tài khoản quản trị workspace và mở Nhà phát triển ở thanh bên.
2. Đặt tên token và chọn chế độ: plan_only để xem thử, interactive để dựng dự án, execute khi agent được phép bắt đầu việc tính phí sau khi người dùng duyệt giá.
3. Chọn thời hạn 1, 7 hoặc 30 ngày. Token phủ cả workspace và mọi tool của chế độ, nên tự có cả các tool thêm sau này. Với một dự án hoặc từng tool riêng, dùng Cài đặt, mục API & MCP.
4. Sao chép token: token chỉ hiện một lần. Lưu nó trong biến môi trường, ví dụ MCP_API_TOKEN; không dán vào prompt, khung chat hay file trong repository.
5. Với token execute, chọn Sửa giới hạn trong danh sách token và đặt hạn mức chi trước khi agent bắt đầu việc tính phí.

2. Thêm MCP server vào client

Địa chỉ là studio bạn đăng nhập, nối thêm đường dẫn endpoint /api/v1/agent/mcp. Trong các ví dụ, STUDIO_URL chứa địa chỉ đó, ví dụ https://<your-studio-host>, và MCP_API_TOKEN chứa token.

claude mcp add --transport http rpt-video "$STUDIO_URL/api/v1/agent/mcp" \
  --header "Authorization: Bearer $MCP_API_TOKEN"

[mcp_servers.rpt-video]
url = "https://<your-studio-host>/api/v1/agent/mcp"
bearer_token_env_var = "MCP_API_TOKEN"

{
  "mcpServers": {
    "rpt-video": {
      "url": "https://<your-studio-host>/api/v1/agent/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Các MCP client khác, như custom connector của ChatGPT ở chế độ nhà phát triển, dùng cùng địa chỉ với header Authorization: Bearer. Hãy bắt đầu với token plan_only hoặc interactive cho tới khi bạn tin quy trình.

3. Kiểm tra kết nối

1. Liệt kê tool (tools/list). Bạn chỉ thấy các tool mà chế độ của token cho phép.
2. Gọi get_workspace không kèm tham số. Kết quả gồm id workspace, tên và vai trò của bạn.
3. Gọi list_video_models với workspace_id đó. Chỉ dùng ref có selectable là true; không bao giờ tự đoán.
4. Khi đã có dự án, gọi agent_preflight với project_id của nó. Kết quả gồm các điểm chặn, cảnh báo và chính xác next_calls cho token của bạn.

get_workspace {}
list_video_models {"workspace_id": "<id from get_workspace>"}
agent_preflight {"project_id": "<project id>"}

4. Làm video đầu tiên

Làm theo Clip sản phẩm từ một tấm ảnh: tạo dự án, gắn ảnh, gửi storyboard, báo giá, chờ người dùng đồng ý, sản xuất và bàn giao.

Khi không chắc bước tiếp theo, gọi agent_continue với project_id. Tool này không tiêu tiền và không thay đổi gì; nó trả về một biên nhận kèm lời gọi kế tiếp.

5. Khi một lời gọi thất bại

• Đọc structuredContent.error và làm theo next_action. Danh mục mã lỗi giải thích các mã.
• MODE_FORBIDS_TOOL: chế độ của token không có tool đó. Quản trị viên workspace tạo token với chế độ phù hợp.
• TOKEN_RATE_LIMITED và TOKEN_CONCURRENCY_LIMIT: chờ rồi thử lại. TOKEN_SPEND_CAP_REACHED: báo người dùng; quản trị viên có thể nâng hạn mức ở trang Nhà phát triển.
• Sau khi hết thời gian chờ hoặc gặp WRITE_OUTCOME_UNKNOWN, đọc trạng thái trước (ví dụ bằng get_run_progress).
• Token hết hạn: quản trị viên tạo token mới ở trang Nhà phát triển; cập nhật biến môi trường.