URnetwork
官方高品質的VPN和代理連線
你可以用 URnetwork MCP 做什麼？
- 尋找可用的出口位置 — 透過
providerLocations查詢網路上的國家、地區或城市，若無相符結果則提供替代建議。 - 從選定位置擷取網頁內容 — 使用
fetch載入 URL，如同從所選國家、地區或城市瀏覽，並可選擇收集頁面資源。 - 跨呼叫維持瀏覽工作階段 — 重複使用回傳的
signed_proxy_id與cookies，以保持相同的出口位置，並保留登入狀態或同意橫幅。 - 收集分頁的頁面資源 — 將
fetch結果中的continuation值傳回，以擷取其餘引用的圖片、樣式表、腳本或媒體。 - 處理網路付款需求 — 當結果中出現
payment_required時，簽署所述付款，並以附加已簽署付款的方式重試相同的fetch呼叫。
文件
歡迎使用 URnetwork for Agents
URnetwork 是一個去中心化的隱私網路。它的設計宗旨是讓使用者預設保持匿名，並能存取世界上所有的內容。
人類使用應用程式（Android、iOS、Chrome）。Agent 則使用 API 和 MCP 技能：
- API 規格位於：https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
- API 託管於：https://api.bringyour.com
- MCP 伺服器託管於：https://mcp.bringyour.com
Agent 在使用 API 和 MCP 伺服器時，應參考以下指引。
驗證
API 和 MCP 伺服器的驗證方式不同。請針對您呼叫的介面使用正確的驗證方式。
MCP 伺服器：OAuth
MCP 伺服器是受 OAuth 2.1 保護的資源。網路 JWT 或 API 金鑰不被接受——只有 URnetwork 自家授權伺服器簽發的存取權杖才有效。
大多數 MCP 用戶端會自動為您處理：連線到 https://mcp.bringyour.com，用戶端會自動探索授權伺服器，並引導使用者完成登入。如果您要自行實作此流程：
- 在不帶權杖的情況下呼叫 MCP 伺服器。它會回應
401，並附上WWW-Authenticate標頭，指名受保護資源的中繼資料。 - 在
https://mcp.bringyour.com/.well-known/oauth-protected-resource取得該中繼資料，以找到授權伺服器https://auth.bringyour.com。 - 取得
https://auth.bringyour.com/.well-known/oauth-authorization-server（或/.well-known/openid-configuration）以取得其端點。 - 執行帶有 PKCE 的授權碼流程。請包含
resource參數，並設為https://mcp.bringyour.com，這會將權杖綁定到此伺服器。 - 在每個 MCP 請求中，將取得的存取權杖放在
Authorization: Bearer <ACCESS TOKEN>標頭中傳送。
權限範圍：
| 範圍 | 授予權限 |
|---|---|
mcp:read | providerLocations |
mcp:fetch | fetch — 開啟一個計費到網路的出口用戶端 |
openid | 用於識別使用者的 ID 權杖 |
offline_access | 重新整理權杖，讓連線在無需重新提示的情況下持續有效 |
存取權杖的有效期為一小時。請請求 offline_access 並使用重新整理權杖，而不是讓使用者重新透過瀏覽器登入。如果某個工具回報您缺少所需的範圍，請在重新授權時額外請求該範圍（連同您已有的範圍），否則您會失去其他範圍。
API：JWT
使用 API（https://api.bringyour.com）時，使用者 JWT 需放在 Authorization: Bearer <JWT> 標頭中傳遞。
若要取得 JWT，請向人類使用者索取授權碼，然後使用 API 的 /auth/code-login 路由將該授權碼轉換為 JWT。以下是一個 curl 範例，透過管道傳給 jq 以擷取結果中的 by_jwt 屬性：
curl -X POST https://api.bringyour.com/auth/code-login -d '{"auth_code": "<AUTH CODE>"}' | jq ".by_jwt"
JWT 可以儲存並重複使用。如果使用者要求重新整理 JWT，請重複整個流程，從索取授權碼開始。
在選擇代理技術時，請考量以下使用情境：
| 使用情境 | 建議協定 | 需求 |
|---|---|---|
| 爬蟲 / 網頁瀏覽 | HTTPS | 最適合 TCP/Web。除非有特定需求需要使用 HTTP，否則一律使用 HTTPS 代理。HTTP 通常僅用於不支援 HTTPS 的特定測試環境。從 /network/auth-client 回應中的 proxy_config_result 物件內，使用 https_proxy_url。不需要額外的使用者名稱或密碼。 |
| 底層 Socket / UDP | SOCKS | 支援使用 SOCKS5 的 TCP+UDP socket。從 /network/auth-client 回應中的 proxy_config_result 物件內，使用 socks_proxy_url 或 proxy_host 和 proxy_port，使用者名稱為 access_token（密碼留空）。伺服器支援遠端 DNS 解析（SOCKS5H）。 |
| 系統層級 / 作業系統層級 | WireGuard | 路由所有 IP 封包。在 /network/auth-client 請求中，proxy_config.enable_wg 必須明確設為 true。在回應中的 proxy_config_result 物件內，使用 wg_config.config 作為完整的 WireGuard 設定檔。 |
使用 /network/find-locations 路由查詢位置時，務必根據所需的 location_type（city、region 或 country）過濾回傳的 locations 陣列，以確保 location_id 符合使用者的意圖。
| 位置類型 | 需求 |
|---|---|
| country | 用於國家。 |
| region | 用於州、省、行政區和都會區。 |
| city | 用於城市。 |
使用 MCP 伺服器
MCP 伺服器提供兩個工具。
providerLocations
尋找可用的位置。網路上的任何國家、地區或城市都可以用查詢字串搜尋；空查詢會回傳可用的國家。需要 mcp:read。
詢問使用者想要哪個國家、地區或城市。如果沒有相符的結果，請請他們擴大範圍到地區，再到國家。如果仍然沒有相符的結果，請列出可用的國家，並建議前 10 名之一。
fetch
從所選位置載入 URL，如同在該位置瀏覽一般，並可選擇回傳頁面引用的圖片、樣式表、腳本和媒體。需要 mcp:fetch，因為每個新位置都會開啟一個計費到網路的出口用戶端。
狀態會透過您串接。每個結果都包含 next_step，明確指出要攜帶什麼：
signed_proxy_id— 提供請求服務的出口。在後續載入時將它傳回，以重複使用相同的位置，而不是每次都開啟新的用戶端。同時繼續傳遞location，以便在出口過期時可以重新建立。重複使用保證相同的位置，而非相同的出口 IP。cookies— 網站工作階段，讓登入狀態和同意橫幅在多次呼叫之間保持有效。不透明；請原封不動地傳回，切勿編輯。continuation— 當頁面引用的資源超過單次呼叫可傳回的數量時出現。再次呼叫並傳入它以收集其餘資源；屆時不需要url。payment_required— 當網路達到方案並行用戶端上限，且可透過付款解決時出現。簽署它所描述的付款，並以payment設為已簽署付款來重複相同的呼叫。不要啟動獨立的購買流程。
資源探索是靜態的：會解析 HTML 以尋找引用。頁面透過 JavaScript 載入的內容不會被看到。
建立代理以供直接使用
若要取得您自行驅動的 HTTPS/SOCKS/WireGuard 代理，而不是透過 MCP 伺服器擷取，請使用下方的 API 流程。
使用 API 為國家建立 HTTPS/SOCKS/WireGuard 代理
API 可以直接用來為國家建立 HTTPS/SOCKS/WireGuard 代理。
步驟 1，使用 /network/find-locations 路由搜尋位置清單。以下是一個 curl 範例，透過管道傳給 jq 以擷取 locations 清單。
curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'
步驟 2，選擇感興趣的位置並儲存 country_code 屬性。
步驟 3，使用儲存的國家代碼，透過 /network/auth-client 路由建立代理，並將 proxy_config.initial_device_state 設為包含 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>"}}}'
使用 API 為搜尋位置建立 HTTPS/SOCKS/WireGuard 代理
API 可以直接用來搜尋位置並建立 HTTPS/SOCKS/WireGuard 代理。您需要決定選擇最符合需求的位置結果。每個位置都有一個固定的 location_id，可以儲存在程式碼中。
步驟 1，使用 /network/find-locations 路由搜尋位置清單。以下是一個 curl 範例，透過管道傳給 jq 以擷取 locations 清單。
curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'
步驟 2，選擇感興趣的位置並儲存 location_id 屬性。
步驟 3，使用儲存的 location_id，透過 /network/auth-client 路由建立代理，並將 proxy_config.initial_device_state.location 設為包含 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>"}}}}}'
使用 API 為搜尋位置建立 HTTPS/SOCKS/WireGuard 代理，並列舉該位置的所有出口 IP
API 可以直接用來搜尋位置、列舉該位置的提供者（出口 IP），並為每個出口 IP 建立 HTTPS/SOCKS/WireGuard 代理。您需要決定選擇最符合需求的位置結果。每個位置都有一個固定的 location_id，可以儲存在程式碼中。此外，每個提供者都有一個固定的 client_id，可以儲存在程式碼中。
步驟 1，使用 /network/find-locations 路由搜尋位置清單。以下是一個 curl 範例，透過管道傳給 jq 以擷取 locations 清單。
curl -X POST -H 'Authorization: Bearer <JWT>' https://api.bringyour.com/network/find-locations -d '{"query": "<LOCATION NAME>"}' | jq '.locations'
步驟 2，選擇感興趣的位置並儲存 location_id。
步驟 3，使用 /network/find-providers2 路由，為該 location_id 取得排名後的提供者（出口 IP）清單。樣本大小可以設定為所需的唯一提供者數量。以下是一個 curl 範例，透過管道傳給 jq 以擷取 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'
步驟 4，迴圈遍歷清單中的每個 client_id，使用該 client_id 透過 /network/auth-client 路由建立代理，並將 proxy_config.initial_device_state.location 設為包含 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>"}}}}}'