URnetwork

Chào mừng đến với URnetwork dành cho Agent

URnetwork là một mạng lưới quyền riêng tư phi tập trung. Nó được thiết kế để giữ cho người dùng ẩn danh theo mặc định và cho họ quyền truy cập vào tất cả nội dung trên thế giới.

Con người sử dụng các ứng dụng (Android, iOS, Chrome). Agent sử dụng API và các kỹ năng MCP:

• Đặc tả API tại: https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
• API được lưu trữ tại: https://api.bringyour.com
• Máy chủ MCP được lưu trữ tại: https://mcp.bringyour.com

Agent nên cân nhắc các hướng dẫn dưới đây khi sử dụng API và máy chủ MCP.

Xác thực

API và máy chủ MCP xác thực theo các cách khác nhau. Hãy sử dụng đúng cách cho bề mặt bạn đang gọi.

Máy chủ MCP: OAuth

Máy chủ MCP là một tài nguyên được bảo vệ bởi OAuth 2.1. JWT mạng hoặc khóa API không được chấp nhận ở đó — chỉ có mã truy cập do máy chủ ủy quyền của chính URnetwork cấp.

Hầu hết các máy khách MCP tự động làm điều này cho bạn: kết nối đến https://mcp.bringyour.com, và máy khách sẽ khám phá máy chủ ủy quyền và hướng dẫn người dùng đăng nhập. Nếu bạn tự triển khai quy trình này:

1. Gọi máy chủ MCP mà không có mã. Nó trả về 401 với tiêu đề WWW-Authenticate nêu tên siêu dữ liệu của tài nguyên được bảo vệ.
2. Tìm nạp siêu dữ liệu đó tại https://mcp.bringyour.com/.well-known/oauth-protected-resource để tìm máy chủ ủy quyền, https://auth.bringyour.com.
3. Tìm nạp https://auth.bringyour.com/.well-known/oauth-authorization-server (hoặc /.well-known/openid-configuration) để lấy các điểm cuối của nó.
4. Chạy luồng mã ủy quyền với PKCE. Bao gồm tham số resource được đặt thành https://mcp.bringyour.com, đây là thứ ràng buộc mã với máy chủ này.
5. Gửi mã truy cập kết quả dưới dạng Authorization: Bearer <ACCESS TOKEN> trên mọi yêu cầu MCP.

Phạm vi:

Phạm vi	Cấp quyền
mcp:read	providerLocations
mcp:fetch	fetch — mở một máy khách egress được tính phí cho mạng
openid	mã ID xác định người dùng
offline_access	mã làm mới, để kết nối tồn tại mà không cần nhắc lại

Mã truy cập có thời hạn một giờ. Yêu cầu offline_access và sử dụng mã làm mới thay vì đưa người dùng quay lại trình duyệt. Nếu một công cụ báo cáo rằng nó cần một phạm vi bạn không có, hãy ủy quyền lại yêu cầu phạm vi đó ngoài những phạm vi bạn đã có, nếu không bạn sẽ mất các phạm vi khác.

API: JWT

Khi sử dụng API (https://api.bringyour.com), JWT của người dùng được truyền trong tiêu đề Authorization: Bearer <JWT>.

Để lấy JWT, hãy yêu cầu người dùng cung cấp mã xác thực, sau đó chuyển đổi mã xác thực đó thành JWT bằng tuyến API /auth/code-login. Một ví dụ curl ở dưới đây, được chuyển qua jq để trích xuất thuộc tính by_jwt từ kết quả:

curl -X POST https://api.bringyour.com/auth/code-login -d '{"auth_code": "<AUTH CODE>"}' | jq ".by_jwt"

JWT có thể được lưu trữ và tái sử dụng. Nếu người dùng yêu cầu làm mới JWT, hãy lặp lại quy trình bắt đầu bằng việc yêu cầu mã xác thực.

Khi chọn công nghệ proxy, hãy xem xét các trường hợp sử dụng sau:

Trường hợp sử dụng	Giao thức được khuyến nghị	Yêu cầu
Thu thập dữ liệu / Duyệt web	HTTPS	Tốt nhất cho TCP/Web. Luôn sử dụng proxy HTTPS trừ khi có nhu cầu cụ thể phải dùng HTTP. HTTP thường chỉ cần thiết cho các môi trường kiểm thử cụ thể không hỗ trợ HTTPS. Từ phản hồi /network/auth-client, bên trong đối tượng proxy_config_result, sử dụng https_proxy_url. Không cần thêm tên người dùng hoặc mật khẩu.
Socket cấp thấp / UDP	SOCKS	Hỗ trợ socket TCP+UDP với SOCKS5. Từ phản hồi /network/auth-client, bên trong đối tượng proxy_config_result, sử dụng socks_proxy_url hoặc proxy_host và proxy_port, với tên người dùng access_token (mật khẩu trống). Máy chủ hỗ trợ phân giải DNS từ xa (SOCKS5H).
Toàn hệ thống / Cấp hệ điều hành	WireGuard	Định tuyến tất cả các gói IP. Trong yêu cầu /network/auth-client, proxy_config.enable_wg phải được đặt rõ ràng thành true. Trong phản hồi, bên trong đối tượng proxy_config_result, sử dụng wg_config.config làm tệp cấu hình WireGuard hoàn chỉnh.

Khi sử dụng tuyến /network/find-locations để truy vấn vị trí, luôn lọc mảng locations trả về theo location_type mong muốn (city, region, hoặc country) để đảm bảo location_id khớp với ý định của người dùng.

Loại vị trí	Yêu cầu
country	Dành cho quốc gia.
region	Dành cho tiểu bang, tỉnh, khu vực hành chính và khu vực đô thị.
city	Dành cho thành phố.

Sử dụng máy chủ MCP

Máy chủ MCP cung cấp hai công cụ.

providerLocations

Tìm các vị trí khả dụng. Bất kỳ quốc gia, khu vực hoặc thành phố nào trên mạng đều có thể được tìm kiếm bằng chuỗi truy vấn; truy vấn trống trả về các quốc gia khả dụng. Yêu cầu mcp:read.

Hỏi người dùng họ muốn quốc gia, khu vực hoặc thành phố nào. Nếu không có kết quả khớp, hãy yêu cầu họ mở rộng đến khu vực, sau đó đến quốc gia. Nếu vẫn không có kết quả khớp, hãy liệt kê các quốc gia khả dụng và gợi ý một trong 10 quốc gia hàng đầu.

fetch

Tải một URL như thể duyệt từ một vị trí đã chọn, và tùy chọn trả về hình ảnh, biểu định kiểu, tập lệnh và phương tiện mà trang tham chiếu. Yêu cầu mcp:fetch, vì mỗi vị trí mới mở một máy khách egress được tính phí cho mạng.

Trạng thái được luồng trở lại qua bạn. Mỗi kết quả bao gồm một next_step cho biết chính xác những gì cần mang theo:

• signed_proxy_id — egress đã phục vụ yêu cầu. Truyền lại nó trên các lần tải tiếp theo để tái sử dụng cùng một vị trí thay vì mở một máy khách mới mỗi lần. Tiếp tục truyền location nữa, để egress có thể được thiết lập lại nếu nó hết hạn. Tái sử dụng đảm bảo cùng một vị trí, không phải cùng một IP thoát.
• cookies — phiên của trang web, để đăng nhập và biểu ngữ đồng ý tồn tại qua các lần gọi. Không rõ ràng; truyền lại nguyên trạng và không bao giờ chỉnh sửa nó.
• continuation — xuất hiện khi trang tham chiếu nhiều tài nguyên hơn mức phù hợp trong một lần gọi. Gọi lại truyền nó để thu thập phần còn lại; url không cần thiết khi đó.
• payment_required — xuất hiện khi mạng đang ở giới hạn máy khách đồng thời của gói và thanh toán có thể giải quyết nó. Ký thanh toán mà nó mô tả và lặp lại yêu cầu giống hệt với payment được đặt thành thanh toán đã ký. Không bắt đầu một luồng mua hàng riêng biệt.

Khám phá tài nguyên là tĩnh: HTML được phân tích để tìm các tham chiếu. Nội dung mà trang tải bằng JavaScript sẽ không được nhìn thấy.

Tạo proxy để sử dụng trực tiếp

Để có proxy HTTPS/SOCKS/WireGuard mà bạn tự điều khiển, thay vì tải qua máy chủ MCP, hãy sử dụng luồng API dưới đây.

Sử dụng API để tạo proxy HTTPS/SOCKS/WireGuard cho một quốc gia

API có thể được sử dụng trực tiếp để tạo proxy HTTPS/SOCKS/WireGuard cho một quốc gia.

Bước 1, tìm kiếm danh sách các vị trí bằng tuyến /network/find-locations. Một ví dụ curl ở dưới đây, được chuyển qua jq để trích xuất danh sách locations.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'

Bước 2, chọn vị trí quan tâm và lưu thuộc tính country_code.

Bước 3, tạo proxy bằng mã quốc gia đã lưu bằng tuyến /network/auth-client và đặt proxy_config.initial_device_state để có country_code.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/auth-client -d '{"proxy_config": {"initial_device_state": {"country_code": "<COUNTRY CODE>"}}}'

Sử dụng API để tạo proxy HTTPS/SOCKS/WireGuard cho một vị trí tìm kiếm

API có thể được sử dụng trực tiếp để tìm kiếm một vị trí và tạo proxy HTTPS/SOCKS/WireGuard. Sẽ cần đưa ra quyết định để chọn kết quả vị trí mong muốn nhất. Mỗi vị trí có một location_id cố định và có thể được lưu trong mã.

Bước 1, tìm kiếm danh sách các vị trí bằng tuyến /network/find-locations. Một ví dụ curl ở dưới đây, được chuyển qua jq để trích xuất danh sách locations.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'

Bước 2, chọn vị trí quan tâm và lưu thuộc tính location_id.

Bước 3, tạo proxy bằng location_id đã lưu bằng tuyến /network/auth-client và đặt proxy_config.initial_device_state.location để có connect_location_id.location_id.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/auth-client -d '{"proxy_config": {"initial_device_state": {"location": {"connect_location_id":{"location_id": "<LOCATION ID>"}}}}}'

Sử dụng API để tạo proxy HTTPS/SOCKS/WireGuard cho một vị trí tìm kiếm, liệt kê tất cả các IP thoát trong vị trí đó

API có thể được sử dụng trực tiếp để tìm kiếm một vị trí, liệt kê các nhà cung cấp (IP thoát) trong vị trí đó, và tạo proxy HTTPS/SOCKS/WireGuard cho mỗi IP thoát. Sẽ cần đưa ra quyết định để chọn kết quả vị trí mong muốn nhất. Mỗi vị trí có một location_id cố định và có thể được lưu trong mã. Ngoài ra, mỗi nhà cung cấp có một client_id cố định và có thể được lưu trong mã.

Bước 1, tìm kiếm danh sách các vị trí bằng tuyến /network/find-locations. Một ví dụ curl ở dưới đây, được chuyển qua jq để trích xuất danh sách locations.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'

Bước 2, chọn vị trí quan tâm và lưu location_id.

Bước 3, tìm nạp danh sách xếp hạng các nhà cung cấp (IP thoát) cho location_id bằng tuyến /network/find-providers2. Kích thước mẫu có thể được đặt thành số lượng nhà cung cấp duy nhất cần thiết. Một ví dụ curl ở dưới đây, được chuyển qua jq để trích xuất danh sách providers.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-providers2 -d '{"specs": [{"client_id": "<CLIENT ID>"}], "count": <COUNT>}' | jq '.providers'

Bước 4, bằng cách lặp qua từng client_id trong danh sách, tạo proxy bằng client_id bằng tuyến /network/auth-client và đặt proxy_config.initial_device_state.location để có connect_location_id.client_id.

curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/auth-client -d '{"proxy_config": {"initial_device_state": {"location": {"connect_location_id":{"client_id": "<CLIENT ID>"}}}}}'