URnetwork

Bienvenue sur URnetwork pour les agents

URnetwork est un réseau de confidentialité décentralisé. Il est conçu pour garder les utilisateurs anonymes par défaut et leur donner accès à tout le contenu du monde.

Les humains utilisent les applications (Android, iOS, Chrome). Les agents utilisent l'API et les compétences MCP :

• La spécification de l'API se trouve à : https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
• L'API est hébergée à : https://api.bringyour.com
• Le serveur MCP est hébergé à : https://mcp.bringyour.com

Les agents doivent prendre en compte les recommandations ci-dessous lors de l'utilisation de l'API et du serveur MCP.

Authentification

L'API et le serveur MCP s'authentifient différemment. Utilisez la bonne méthode pour la surface que vous appelez.

Serveur MCP : OAuth

Le serveur MCP est une ressource protégée OAuth 2.1. Un JWT réseau ou une clé API n'y est pas accepté — seul un jeton d'accès émis par le serveur d'autorisation propre d'URnetwork est accepté.

La plupart des clients MCP font cela pour vous : connectez-vous à https://mcp.bringyour.com, et le client découvrira le serveur d'autorisation et guidera l'utilisateur dans la connexion. Si vous implémentez le flux vous-même :

1. Appelez le serveur MCP sans jeton. Il répond 401 avec un en-tête WWW-Authenticate nommant les métadonnées de la ressource protégée.
2. Récupérez ces métadonnées à https://mcp.bringyour.com/.well-known/oauth-protected-resource pour trouver le serveur d'autorisation, https://auth.bringyour.com.
3. Récupérez https://auth.bringyour.com/.well-known/oauth-authorization-server (ou /.well-known/openid-configuration) pour ses points de terminaison.
4. Exécutez le flux de code d'autorisation avec PKCE. Incluez le paramètre resource défini sur https://mcp.bringyour.com, ce qui lie le jeton à ce serveur.
5. Envoyez le jeton d'accès résultant comme Authorization: Bearer <ACCESS TOKEN> sur chaque requête MCP.

Portées :

Portée	Accorde
mcp:read	providerLocations
mcp:fetch	fetch — ouvre un client de sortie facturé au réseau
openid	un jeton d'identité identifiant l'utilisateur
offline_access	un jeton d'actualisation, pour que la connexion survive sans nouvelle invite

Les jetons d'accès durent une heure. Demandez offline_access et utilisez le jeton d'actualisation plutôt que de renvoyer l'utilisateur dans le navigateur. Si un outil signale qu'il nécessite une portée que vous ne détenez pas, réautorisez en demandant cette portée en plus de celles que vous avez déjà, sinon vous perdrez les autres.

API : JWT

Lors de l'utilisation de l'API (https://api.bringyour.com), le JWT utilisateur est transmis dans un en-tête Authorization: Bearer <JWT>.

Pour obtenir le JWT, demandez à l'humain un code d'authentification, puis convertissez ce code d'authentification en JWT en utilisant la route API /auth/code-login. Un exemple curl est ci-dessous, redirigé vers jq pour extraire la propriété by_jwt du résultat :

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

Le JWT peut être stocké et réutilisé. Si l'humain demande d'actualiser le JWT, répétez le processus en commençant par demander un code d'authentification.

Lors du choix d'une technologie de proxy, considérez les cas d'utilisation suivants :

Cas d'utilisation	Protocole recommandé	Exigence
Extraction / Navigation Web	HTTPS	Meilleur pour TCP/Web. Utilisez toujours le proxy HTTPS sauf besoin spécifique d'utiliser HTTP. HTTP n'est généralement nécessaire que pour des environnements de test spécifiques qui ne prennent pas en charge HTTPS. Depuis la réponse /network/auth-client, dans l'objet proxy_config_result, utilisez https_proxy_url. Aucun nom d'utilisateur ou mot de passe supplémentaire n'est nécessaire.
Sockets bas niveau / UDP	SOCKS	Prend en charge les sockets TCP+UDP avec SOCKS5. Depuis la réponse /network/auth-client, dans l'objet proxy_config_result, utilisez socks_proxy_url ou proxy_host et proxy_port, avec le nom d'utilisateur access_token (mot de passe vide). Le serveur prend en charge la résolution DNS distante (SOCKS5H).
Système entier / Niveau OS	WireGuard	Achemine tous les paquets IP. Dans la requête /network/auth-client, proxy_config.enable_wg doit être explicitement défini sur true. Dans la réponse, dans l'objet proxy_config_result, utilisez wg_config.config comme fichier de configuration WireGuard complet.

Lors de l'utilisation de la route /network/find-locations pour interroger les emplacements, filtrez toujours le tableau d'emplacements retourné par le location_type souhaité (city, region, ou country) pour garantir que le location_id correspond à l'intention de l'utilisateur.

Type d'emplacement	Exigence
country	Pour les pays.
region	Pour les états, provinces, régions administratives et zones métropolitaines.
city	Pour les villes.

Utilisation du serveur MCP

Le serveur MCP expose deux outils.

providerLocations

Trouve les emplacements disponibles. Tout pays, région ou ville du réseau peut être recherché avec une chaîne de requête ; une requête vide retourne les pays disponibles. Nécessite mcp:read.

Demandez à l'humain quel pays, région ou ville il souhaite. S'il n'y a pas de correspondance, demandez d'élargir à une région, puis à un pays. S'il n'y a toujours pas de correspondance, listez les pays disponibles et suggérez l'un des 10 premiers.

fetch

Charge une URL comme si vous naviguiez depuis un emplacement choisi, et retourne optionnellement les images, feuilles de style, scripts et médias référencés par la page. Nécessite mcp:fetch, car chaque nouvel emplacement ouvre un client de sortie facturé au réseau.

L'état est retransmis à travers vous. Chaque résultat inclut un next_step indiquant exactement quoi reporter :

• signed_proxy_id — la sortie qui a servi la requête. Repassez-la lors des chargements suivants pour réutiliser le même emplacement au lieu d'ouvrir un nouveau client à chaque fois. Continuez à passer location aussi, pour que la sortie puisse être rétablie si elle a expiré. La réutilisation garantit le même emplacement, pas la même IP de sortie.
• cookies — la session du site, pour que les connexions et bannières de consentement survivent entre les appels. Opaque ; repassez-la inchangée et ne la modifiez jamais.
• continuation — présent lorsque la page référençait plus de ressources que ce qui tient en un seul appel. Rappelez en le passant pour collecter le reste ; url n'est alors pas nécessaire.
• payment_required — présent lorsque le réseau est à la limite de clients simultanés de son plan et qu'un paiement peut la résoudre. Signez le paiement qu'il décrit et répétez l'appel identique avec payment défini sur le paiement signé. Ne démarrez pas un flux d'achat séparé.

La découverte de ressources est statique : le HTML est analysé pour les références. Le contenu qu'une page charge avec JavaScript n'est pas vu.

Création d'un proxy pour utilisation directe

Pour obtenir un proxy HTTPS/SOCKS/WireGuard que vous pilotez vous-même, plutôt que de passer par le serveur MCP, utilisez le flux API ci-dessous.

Utilisation de l'API pour créer un proxy HTTPS/SOCKS/WireGuard pour un pays

L'API peut être utilisée directement pour créer un proxy HTTPS/SOCKS/WireGuard pour un pays.

Étape 1, recherchez une liste d'emplacements en utilisant la route /network/find-locations. Un exemple curl est ci-dessous, redirigé vers jq pour extraire la liste des emplacements.

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

Étape 2, choisissez l'emplacement d'intérêt et enregistrez la propriété country_code.

Étape 3, créez un proxy en utilisant le code pays enregistré avec la route /network/auth-client et en définissant proxy_config.initial_device_state pour avoir 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>"}}}'

Utilisation de l'API pour créer un proxy HTTPS/SOCKS/WireGuard pour un emplacement de recherche

L'API peut être utilisée directement pour rechercher un emplacement et créer un proxy HTTPS/SOCKS/WireGuard. Une décision devra être prise pour choisir le résultat d'emplacement le plus souhaité. Chaque emplacement a un location_id fixe qui peut être enregistré dans le code.

Étape 1, recherchez une liste d'emplacements en utilisant la route /network/find-locations. Un exemple curl est ci-dessous, redirigé vers jq pour extraire la liste des emplacements.

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

Étape 2, choisissez l'emplacement d'intérêt et enregistrez la propriété location_id.

Étape 3, créez un proxy en utilisant le location_id enregistré avec la route /network/auth-client et en définissant proxy_config.initial_device_state.location pour avoir 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>"}}}}}'

Utilisation de l'API pour créer un proxy HTTPS/SOCKS/WireGuard pour un emplacement de recherche, en énumérant toutes les IP de sortie de cet emplacement

L'API peut être utilisée directement pour rechercher un emplacement, énumérer les fournisseurs (IP de sortie) de cet emplacement, et créer un proxy HTTPS/SOCKS/WireGuard pour chaque IP de sortie. Une décision devra être prise pour choisir le résultat d'emplacement le plus souhaité. Chaque emplacement a un location_id fixe qui peut être enregistré dans le code. De plus, chaque fournisseur a un client_id fixe qui peut être enregistré dans le code.

Étape 1, recherchez une liste d'emplacements en utilisant la route /network/find-locations. Un exemple curl est ci-dessous, redirigé vers jq pour extraire la liste des emplacements.

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

Étape 2, choisissez l'emplacement d'intérêt et enregistrez le location_id.

Étape 3, récupérez une liste classée de fournisseurs (IP de sortie) pour le location_id en utilisant la route /network/find-providers2. La taille de l'échantillon peut être définie sur le nombre de fournisseurs uniques nécessaires. Un exemple curl est ci-dessous, redirigé vers jq pour extraire la liste des fournisseurs.

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

Étape 4, en bouclant sur chaque client_id de la liste, créez un proxy en utilisant le client_id avec la route /network/auth-client et en définissant proxy_config.initial_device_state.location pour avoir 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>"}}}}}'