Kết nối tác tử AI (MCP)

Tác tử AI của riêng một công ty di trú có thể làm việc trong không gian làm việc DS160.io của công ty qua MCP (Model Context Protocol). Từ giấy tờ hoặc email của khách hàng, tác tử có thể tạo biểu mẫu, điền các câu trả lời nó tìm thấy, kiểm tra những gì còn thiếu và gửi cho khách hàng một liên kết để điền phần còn lại. Sau đó nhân viên của bạn tự kiểm tra đơn và ký trên CEAC.

Tác tử kết nối với một không gian làm việc doanh nghiệp và chỉ có thể làm những gì bạn cho phép. Mỗi việc nó làm được cũng là một endpoint của API của DS160.io.

Trước khi bắt đầu

Một không gian làm việc doanh nghiệp. MCP có trên các không gian làm việc doanh nghiệp.
Quyền Chủ sở hữu hoặc Quản trị viên. Chỉ Chủ sở hữu và Quản trị viên của không gian làm việc mới có thể tạo khóa API hoặc cho phép một kết nối.
Một ứng dụng MCP. Claude Code, Cursor, VS Code, Codex và Windsurf kết nối bằng khóa API. claude.ai và ChatGPT kết nối bằng cách đăng nhập vào DS160.io.

Địa chỉ của máy chủ là:

https://www.ds160.io/api/mcp

Hãy dùng địa chỉ này ngay cả khi không gian làm việc của bạn có tên miền riêng.

Kết nối bằng khóa API

Mở Cài đặt không gian làm việc → Nhóm & quyền truy cập → Khóa API và nhấn Tạo khóa API.
Đặt tên khóa theo tác tử (ví dụ Claude Code, nhóm tiếp nhận), chọn mẫu thiết lập sẵn MCP và tạo khóa. Mẫu này chọn mọi scope trừ runs:write; bỏ chọn scope nào tác tử không cần.
Sao chép bí mật. Bí mật bắt đầu bằng ds160_sk_ và chỉ hiển thị một lần.
Thêm máy chủ vào ứng dụng của bạn với bí mật trong header Authorization. Trong Claude Code:

claude mcp add --transport http ds160 https://www.ds160.io/api/mcp --header "Authorization: Bearer ds160_sk_…"

Các ứng dụng khác nhận cùng địa chỉ và header trong phần cài đặt. Trong Cursor (.cursor/mcp.json):

{
    "mcpServers": {
        "ds160": {
            "url": "https://www.ds160.io/api/mcp",
            "headers": { "Authorization": "Bearer ds160_sk_…" }
        }
    }
}

Trong VS Code (.vscode/mcp.json), thêm cùng url và headers dưới "servers" với "type": "http". Đừng để bí mật trong các tệp bạn commit: hãy dùng biến môi trường hoặc ô nhập bí mật nếu ứng dụng của bạn hỗ trợ.

Kết nối claude.ai hoặc ChatGPT

claude.ai và ChatGPT không gửi khóa. Thay vào đó, chúng kết nối bằng cách đăng nhập vào DS160.io:

Trong claude.ai hoặc ChatGPT, thêm https://www.ds160.io/api/mcp làm trình kết nối tùy chỉnh.
Khi được hỏi, đăng nhập vào DS160.io bằng tài khoản của chính bạn.
Chọn không gian làm việc doanh nghiệp mà tác tử sẽ làm việc.
Xem lại các quyền mà nó yêu cầu, rồi nhấn để cho phép.

Sau đó tác tử hành động với tư cách của bạn, trong không gian làm việc đó. Bạn phải là Chủ sở hữu hoặc Quản trị viên của không gian làm việc mới có thể cho phép một kết nối.

Scope: mỗi scope cho phép gì

Scope	Tác tử có thể làm gì
`forms:read`	Liệt kê biểu mẫu, đọc tên và trạng thái của biểu mẫu, kiểm tra những gì còn thiếu, theo dõi một lần nộp
`forms:write`	Tạo biểu mẫu (và đọc chúng)
`forms:clone`	Sao chép một biểu mẫu hiện có thành biểu mẫu mới
`client-links:write`	Tạo liên kết khách hàng để gửi cho người nộp đơn
`answers:read`	Đọc câu trả lời của biểu mẫu
`answers:write`	Ghi và xóa câu trả lời của biểu mẫu
`runs:write`	Bắt đầu một lần nộp trên CEAC và theo dõi nó

answers:read đưa dữ liệu cá nhân của người nộp đơn ra khỏi DS160.io. Tên, ngày sinh, số hộ chiếu, lịch sử đi lại và mọi câu trả lời DS-160 khác mà tác tử đọc được đều được chuyển cho tác tử và cho bên vận hành nó, chẳng hạn một nhà cung cấp AI. Không gian làm việc của bạn, với tư cách là bên kiểm soát dữ liệu của khách hàng mình, quyết định việc đó có được phép hay không, và chịu trách nhiệm về dữ liệu đó khi nó đã rời khỏi DS160.io (xem chính sách quyền riêng tư và Thỏa thuận xử lý dữ liệu). Nếu tác tử chỉ cần điền biểu mẫu, hãy bỏ answers:read: chỉ với answers:write, nó có thể ghi câu trả lời mà không đọc lại.

Tác tử làm được gì và không làm được gì

Nó có thể chuẩn bị một biểu mẫu: tạo biểu mẫu, điền câu trả lời từ những gì khách hàng gửi, xem câu hỏi nào còn thiếu hoặc sẽ bị từ chối, và gửi cho khách hàng một liên kết để điền phần còn lại.
Mọi câu trả lời nó ghi đều được kiểm tra như trình chỉnh sửa biểu mẫu kiểm tra. Văn bản được lưu bằng chữ in hoa trừ khi câu hỏi cho phép chữ cái ngoài tiếng Anh. Một câu trả lời không phù hợp bị từ chối kèm lý do, và các câu trả lời khác trong cùng lô không bị ảnh hưởng.
Mọi thay đổi đều được ghi lại. Lịch sử trường của biểu mẫu hiển thị mỗi thay đổi là “API key tên” với một khóa, hoặc “thành viên via tác tử” với một kết nối.
Nó không thể ký hay nộp. Một lần nộp do tác tử bắt đầu luôn dừng trước khi ký, bất kể cài đặt của không gian làm việc: một người kiểm tra đơn và ký trên CEAC (xem Kiểm tra DS-160 trên CEAC trước khi ký).
Nó không thể nhập mã captcha của CEAC. Một người nhập mã trong DS160.io trong khi lần nộp chờ; lần nộp cho tác tử biết khi nào cần một người và ở đâu.
Việc tạo biểu mẫu được tính phí như khi tạo trong ứng dụng: mỗi biểu mẫu được tạo, hoặc được nhân bản, được tính là một biểu mẫu đã tạo.
Nó chỉ làm việc trong không gian làm việc của chính nó. Nó không thấy các không gian làm việc khác, và một biểu mẫu từ không gian làm việc khác được báo là không tìm thấy.

Công cụ

Công cụ	Việc nó làm	Scope
`list_forms`	Liệt kê các biểu mẫu của không gian làm việc, mới nhất trước	`forms:read`
`get_form`	Đọc tên, trạng thái và sự đồng ý của một biểu mẫu	`forms:read`
`create_form`	Tạo một biểu mẫu (tính phí theo mỗi biểu mẫu được tạo)	`forms:write`
`clone_form`	Sao chép một biểu mẫu thành biểu mẫu mới, có thể bỏ bớt các phần	`forms:clone`
`create_client_link`	Tạo liên kết khách hàng cho một biểu mẫu	`client-links:write`
`search_docs`	Tìm trong tài liệu này, 200 lượt mỗi ngày cho mỗi khóa hoặc kết nối	bất kỳ
`describe_form_pages`	Liệt kê các trang của biểu mẫu và từng câu hỏi: đường dẫn câu trả lời, loại, có bắt buộc không, giá trị của danh sách thả xuống và các câu hỏi mà mỗi câu trả lời mở ra, kèm JSON cho từng loại câu trả lời	bất kỳ
`get_answers`	Đọc câu trả lời của biểu mẫu, cho cả biểu mẫu hoặc một trang	`answers:read`
`set_answers`	Ghi tối đa 200 câu trả lời mỗi lần gọi, theo thứ tự: mỗi câu được ghi, được xóa (giá trị `null`) hoặc bị từ chối kèm mã và lý do	`answers:write`
`get_form_progress`	Cho mỗi phần: trạng thái, các câu hỏi bắt buộc chưa có câu trả lời và các vấn đề theo đường dẫn; và biểu mẫu đã hoàn tất hay chưa	`forms:read`, `answers:read` hoặc `answers:write`
`start_run`	Bắt đầu một lần nộp trên CEAC cho lãnh sự quán đã chọn; dừng trước khi ký	`runs:write`
`get_run`	Trạng thái của một lần nộp, tóm tắt nó đang ở đâu, có cần một người không, và liên kết tới nó	`runs:write` hoặc `forms:read`

Thu hồi quyền truy cập

Một khóa: thu hồi trong Cài đặt không gian làm việc → Nhóm & quyền truy cập → Khóa API. Lần gọi tiếp theo của tác tử sẽ bị từ chối.
Một kết nối (claude.ai, ChatGPT): thu hồi trong Tài khoản & Bảo mật, hoặc cho cả không gian làm việc trong Cài đặt không gian làm việc. Cả hai nơi đều liệt kê các kết nối hiện có.

Hãy thu hồi ngay nếu một khóa có thể đã bị lộ hoặc một tác tử không còn được dùng.

Giữ tác tử trong phạm vi những gì người nộp đơn cung cấp

DS-160 do người nộp đơn ký, và họ cam đoan rằng mọi câu trả lời đều đúng sự thật. Hãy dặn tác tử của bạn chỉ trả lời từ những gì người nộp đơn đã cung cấp cho bạn (giấy tờ, email và câu trả lời của họ) và không bao giờ đoán hay bịa ra câu trả lời. Khi không chắc chắn, nó nên để trống câu hỏi, để get_form_progress hiển thị câu hỏi đó là còn thiếu và khách hàng hoặc nhân viên của bạn trả lời. Hãy kiểm tra biểu mẫu trước khi bất kỳ ai ký.

Khắc phục sự cố

Vấn đề	Cách xử lý
Ứng dụng báo không kết nối được, hoặc nhận `401`	Kiểm tra địa chỉ là `https://www.ds160.io/api/mcp` và header là `Authorization: Bearer <secret>`, với toàn bộ bí mật. Một khóa đã thu hồi không thể dùng lại: hãy tạo khóa mới.
Một công cụ báo thiếu scope	Khóa hoặc kết nối thiếu scope đó. Tạo một khóa có scope đó (hoặc kết nối lại và cho phép nó), rồi thu hồi khóa cũ.
Một câu trả lời bị từ chối	Đọc lý do. Dùng `describe_form_pages` để biết đường dẫn đúng và các giá trị mà danh sách thả xuống chấp nhận.
`start_run` bị từ chối	`get_form_progress` liệt kê những gì còn thiếu hoặc sai trong mỗi phần. Điền vào, rồi bắt đầu lại lần nộp. Nếu một lần nộp của biểu mẫu đang diễn ra, hãy theo dõi nó bằng `get_run`.
Lần nộp đang chờ với `needsPerson`	Một người mở liên kết của lần nộp trong DS160.io và nhập mã captcha. Khi lần nộp đã sẵn sàng để ký, một người kiểm tra đơn và ký trên CEAC.