URnetwork
공식고품질 VPN 및 프록시 연결
URnetwork MCP(으)로 무엇을 할 수 있나요?
- 사용 가능한 이그레스 위치 찾기 —
providerLocations를 통해 네트워크상의 국가, 지역, 도시를 요청하고, 일치하는 항목이 없을 때 대체 제안을 제공합니다. - 선택한 위치에서 웹 콘텐츠 가져오기 —
fetch를 사용하여 선택한 국가, 지역, 도시에서 브라우징하는 것처럼 URL을 로드하며, 선택적으로 페이지 리소스 수집이 가능합니다. - 호출 간 브라우징 세션 유지 — 반환된
signed_proxy_id와cookies를 재사용하여 동일한 이그레스 위치를 유지하고 로그인 또는 동의 배너를 보존합니다. - 페이지네이션된 페이지 리소스 수집 —
fetch결과의continuation값을 다시 전달하여 나머지 참조된 이미지, 스타일시트, 스크립트 또는 미디어를 검색합니다. - 네트워크 결제 요구사항 처리 — 결과에
payment_required가 나타나면 설명된 결제에 서명하고, 서명된 결제를 첨부하여 동일한fetch호출을 다시 시도합니다.
문서
URnetwork 에이전트 시작하기
URnetwork는 분산형 프라이버시 네트워크입니다. 사용자를 기본적으로 익명으로 유지하고 전 세계의 모든 콘텐츠에 접근할 수 있도록 설계되었습니다.
사람들은 앱(Android, iOS, Chrome)을 사용합니다. 에이전트는 API와 MCP 스킬을 사용합니다:
- API 사양: https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
- API 호스팅 주소: https://api.bringyour.com
- MCP 서버 호스팅 주소: https://mcp.bringyour.com
에이전트는 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>로 전송합니다.
범위(Scopes):
| 범위 | 부여 권한 |
|---|---|
mcp:read | providerLocations |
mcp:fetch | fetch — 네트워크에 청구되는 이그레스 클라이언트를 엽니다 |
openid | 사용자를 식별하는 ID 토큰 |
offline_access | 리프레시 토큰 — 재프롬프트 없이 연결 유지 |
액세스 토큰은 1시간 동안 유효합니다. offline_access를 요청하고 리프레시 토큰을 사용하여 사용자를 브라우저로 다시 보내지 마세요. 도구가 보유하지 않은 범위가 필요하다고 보고하면, 기존 범위 에 추가로 해당 범위를 요청하여 재인증하세요. 그렇지 않으면 기존 범위를 잃게 됩니다.
API: JWT
API(https://api.bringyour.com)를 사용할 때 사용자 JWT는 Authorization: Bearer <JWT> 헤더로 전달됩니다.
JWT를 얻으려면 사용자에게 인증 코드를 요청한 다음, API /auth/code-login 경로를 사용하여 해당 인증 코드를 JWT로 변환하세요. 아래에 curl 예시가 있으며, 결과에서 by_jwt 속성을 추출하기 위해 jq로 파이프합니다:
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을 사용하세요. 추가 사용자 이름이나 비밀번호는 필요 없습니다. |
| 저수준 소켓 / UDP | SOCKS | SOCKS5로 TCP+UDP 소켓을 지원합니다. /network/auth-client 응답의 proxy_config_result 객체 내부에서 socks_proxy_url 또는 proxy_host와 proxy_port를 사용하고, 사용자 이름은 access_token(비밀번호는 비어 있음)으로 설정하세요. 서버는 원격 DNS 확인(SOCKS5H)을 지원합니다. |
| 시스템 전체 / OS 수준 | WireGuard | 모든 IP 패킷을 라우팅합니다. /network/auth-client 요청에서 proxy_config.enable_wg를 명시적으로 true로 설정해야 합니다. 응답의 proxy_config_result 객체 내부에서 wg_config.config를 완전한 WireGuard 구성 파일로 사용하세요. |
/network/find-locations 경로를 사용하여 위치를 쿼리할 때는 항상 반환된 locations 배열을 원하는 location_type(도시, 지역 또는 국가)으로 필터링하여 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로 로드되는 콘텐츠는 표시되지 않습니다.
직접 사용을 위한 프록시 생성
MCP 서버를 통해 가져오는 대신 직접 구동하는 HTTPS/SOCKS/WireGuard 프록시를 얻으려면 아래 API 흐름을 사용하세요.
API를 사용하여 국가용 HTTPS/SOCKS/WireGuard 프록시 생성
API를 직접 사용하여 국가용 HTTPS/SOCKS/WireGuard 프록시를 생성할 수 있습니다.
1단계, /network/find-locations 경로를 사용하여 위치 목록을 검색합니다. 아래에 curl 예시가 있으며, locations 목록을 추출하기 위해 jq로 파이프합니다.
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 예시가 있으며, locations 목록을 추출하기 위해 jq로 파이프합니다.
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 예시가 있으며, locations 목록을 추출하기 위해 jq로 파이프합니다.
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 예시가 있으며, providers 목록을 추출하기 위해 jq로 파이프합니다.
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를 반복하면서 /network/auth-client 경로를 사용하여 client_id로 프록시를 생성하고 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>"}}}}}'