URnetwork

Добро пожаловать в 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, и клиент обнаружит сервер авторизации и проведет пользователя через процесс входа. Если вы реализуете этот процесс самостоятельно:

1. Вызовите MCP-сервер без токена. Он ответит 401 с заголовком WWW-Authenticate, указывающим на метаданные защищенного ресурса.
2. Получите эти метаданные по адресу https://mcp.bringyour.com/.well-known/oauth-protected-resource, чтобы найти сервер авторизации, https://auth.bringyour.com.
3. Получите https://auth.bringyour.com/.well-known/oauth-authorization-server (или /.well-known/openid-configuration) для его конечных точек.
4. Выполните поток кода авторизации с PKCE. Включите параметр resource, установленный в https://mcp.bringyour.com, который привязывает токен к этому серверу.
5. Отправляйте полученный токен доступа как Authorization: Bearer <ACCESS TOKEN> в каждом MCP-запросе.

Области (scopes):

Область	Предоставляет
mcp:read	providerLocations
mcp:fetch	fetch — открывает исходящий клиент, оплачиваемый сетью
openid	ID-токен, идентифицирующий пользователя
offline_access	токен обновления, чтобы соединение сохранялось без повторного запроса

Токены доступа действуют один час. Запросите offline_access и используйте токен обновления, а не отправляйте пользователя обратно через браузер. Если инструмент сообщает, что ему нужна область, которой у вас нет, повторно авторизуйтесь, запрашивая эту область в дополнение к тем, что у вас уже есть, иначе вы потеряете остальные.

API: JWT

При использовании API (https://api.bringyour.com) JWT пользователя передается в заголовке Authorization: Bearer <JWT>.

Чтобы получить JWT, попросите человека предоставить код авторизации, а затем преобразуйте этот код в JWT с помощью маршрута API /auth/code-login. Пример 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. Всегда используйте HTTPS-прокси, если нет особой необходимости использовать HTTP. HTTP обычно нужен только для конкретных тестовых сред, не поддерживающих HTTPS. Из ответа /network/auth-client, внутри объекта proxy_config_result, используйте https_proxy_url. Дополнительные имя пользователя или пароль не требуются.
Низкоуровневые сокеты / UDP	SOCKS	Поддерживает TCP+UDP сокеты с SOCKS5. Из ответа /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 для запроса местоположений всегда фильтруйте возвращаемый массив locations по желаемому location_type (city, region или country), чтобы 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) в этом местоположении и создания HTTPS/SOCKS/WireGuard прокси для каждого исходящего IP. Придется принять решение о выборе наиболее желаемого результата местоположения. Каждое местоположение имеет фиксированный 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, получите ранжированный список провайдеров (исходящих IP) для location_id с помощью маршрута /network/find-providers2. Размер выборки можно установить на любое необходимое количество уникальных провайдеров. Пример 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>"}}}}}'