URnetwork

Willkommen bei URnetwork für Agents

URnetwork ist ein dezentrales Privatsphäre-Netzwerk. Es ist darauf ausgelegt, Nutzer standardmäßig anonym zu halten und ihnen Zugang zu allen Inhalten der Welt zu verschaffen.

Menschen nutzen die Apps (Android, iOS, Chrome). Agents nutzen die API und die MCP-Fähigkeiten:

• Die API-Spezifikation finden Sie unter: https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
• Die API ist gehostet unter: https://api.bringyour.com
• Der MCP-Server ist gehostet unter: https://mcp.bringyour.com

Agents sollten die folgenden Hinweise beachten, wenn sie die API und den MCP-Server verwenden.

Authentifizierung

Die API und der MCP-Server authentifizieren sich unterschiedlich. Verwenden Sie die richtige Methode für die Oberfläche, die Sie aufrufen.

MCP-Server: OAuth

Der MCP-Server ist eine durch OAuth 2.1 geschützte Ressource. Ein Netzwerk-JWT oder ein API-Schlüssel wird dort nicht akzeptiert — nur ein Zugriffstoken, das vom eigenen Autorisierungsserver von URnetwork ausgestellt wurde.

Die meisten MCP-Clients erledigen dies für Sie: Verbinden Sie sich mit https://mcp.bringyour.com, und der Client erkennt den Autorisierungsserver und führt den Benutzer durch die Anmeldung. Wenn Sie den Ablauf selbst implementieren:

1. Rufen Sie den MCP-Server ohne Token auf. Er antwortet mit 401 und einem WWW-Authenticate-Header, der die Metadaten der geschützten Ressource benennt.
2. Rufen Sie diese Metadaten unter https://mcp.bringyour.com/.well-known/oauth-protected-resource ab, um den Autorisierungsserver https://auth.bringyour.com zu finden.
3. Rufen Sie https://auth.bringyour.com/.well-known/oauth-authorization-server (oder /.well-known/openid-configuration) für dessen Endpunkte ab.
4. Führen Sie den Autorisierungscode-Ablauf mit PKCE durch. Fügen Sie den Parameter resource mit dem Wert https://mcp.bringyour.com hinzu, der das Token an diesen Server bindet.
5. Senden Sie das resultierende Zugriffstoken als Authorization: Bearer <ACCESS TOKEN> bei jeder MCP-Anfrage.

Bereiche (Scopes):

Bereich	Gewährt
mcp:read	providerLocations
mcp:fetch	fetch — öffnet einen Egress-Client, der dem Netzwerk in Rechnung gestellt wird
openid	ein ID-Token, das den Benutzer identifiziert
offline_access	ein Aktualisierungstoken, sodass die Verbindung ohne erneute Aufforderung bestehen bleibt

Zugriffstokens gelten eine Stunde. Fordern Sie offline_access an und verwenden Sie das Aktualisierungstoken, anstatt den Benutzer erneut durch den Browser zu schicken. Wenn ein Tool meldet, dass es einen Bereich benötigt, den Sie nicht besitzen, autorisieren Sie erneut und fordern Sie diesen Bereich zusätzlich zu den bereits vorhandenen an, sonst verlieren Sie die anderen.

API: JWT

Bei Verwendung der API (https://api.bringyour.com) wird das Benutzer-JWT in einem Authorization: Bearer <JWT>-Header übergeben.

Um das JWT zu erhalten, bitten Sie den Menschen um einen Autorisierungscode und wandeln Sie diesen Code dann über die API-Route /auth/code-login in ein JWT um. Ein curl-Beispiel finden Sie unten, das an jq weitergeleitet wird, um die by_jwt-Eigenschaft aus dem Ergebnis zu extrahieren:

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

Das JWT kann gespeichert und wiederverwendet werden. Wenn der Mensch eine Aktualisierung des JWT wünscht, wiederholen Sie den Vorgang, beginnend mit der Anforderung eines Autorisierungscodes.

Bei der Wahl einer Proxy-Technologie sollten Sie die folgenden Anwendungsfälle berücksichtigen:

Anwendungsfall	Empfohlenes Protokoll	Anforderung
Scraping / Web-Browsing	HTTPS	Am besten für TCP/Web. Verwenden Sie immer den HTTPS-Proxy, es sei denn, es gibt einen spezifischen Grund, HTTP zu verwenden. HTTP wird normalerweise nur für bestimmte Testumgebungen benötigt, die HTTPS nicht unterstützen. Verwenden Sie aus der /network/auth-client-Antwort im Objekt proxy_config_result die https_proxy_url. Es sind keine zusätzlichen Benutzernamen oder Passwörter erforderlich.
Low-Level-Sockets / UDP	SOCKS	Unterstützt TCP+UDP-Sockets mit SOCKS5. Verwenden Sie aus der /network/auth-client-Antwort im Objekt proxy_config_result die socks_proxy_url oder proxy_host und proxy_port, mit dem Benutzernamen access_token (leeres Passwort). Der Server unterstützt die Remote-DNS-Auflösung (SOCKS5H).
Systemweit / Betriebssystemebene	WireGuard	Leitet alle IP-Pakete. In der /network/auth-client-Anfrage muss proxy_config.enable_wg explizit auf true gesetzt werden. Verwenden Sie in der Antwort im Objekt proxy_config_result die wg_config.config als vollständige WireGuard-Konfigurationsdatei.

Wenn Sie die Route /network/find-locations zum Abfragen von Standorten verwenden, filtern Sie das zurückgegebene locations-Array immer nach dem gewünschten location_type (city, region oder country), um sicherzustellen, dass die location_id der Absicht des Benutzers entspricht.

Standorttyp	Anforderung
country	Für Länder.
region	Für Bundesstaaten, Provinzen, Verwaltungsregionen und Metropolregionen.
city	Für Städte.

Verwenden des MCP-Servers

Der MCP-Server stellt zwei Tools bereit.

providerLocations

Findet verfügbare Standorte. Jedes Land, jede Region oder jede Stadt im Netzwerk kann mit einer Abfragezeichenfolge durchsucht werden; eine leere Abfrage gibt die verfügbaren Länder zurück. Erfordert mcp:read.

Fragen Sie den Menschen, welches Land, welche Region oder welche Stadt er möchte. Wenn es keine Übereinstimmungen gibt, bitten Sie ihn, auf eine Region und dann auf ein Land zu erweitern. Wenn es immer noch keine Übereinstimmungen gibt, listen Sie die verfügbaren Länder auf und schlagen Sie eines der Top 10 vor.

fetch

Lädt eine URL, als ob Sie von einem gewählten Standort aus browsen würden, und gibt optional die Bilder, Stylesheets, Skripte und Medien zurück, auf die die Seite verweist. Erfordert mcp:fetch, da jeder neue Standort einen Egress-Client öffnet, der dem Netzwerk in Rechnung gestellt wird.

Der Zustand wird über Sie zurückgeführt. Jedes Ergebnis enthält eine next_step-Angabe, die genau sagt, was Sie weitergeben sollen:

• signed_proxy_id — der Egress, der die Anfrage bedient hat. Geben Sie ihn bei Folgeaufrufen zurück, um denselben Standort wiederzuverwenden, anstatt jedes Mal einen neuen Client zu öffnen. Geben Sie auch weiterhin location zurück, damit der Egress bei Ablauf wiederhergestellt werden kann. Die Wiederverwendung garantiert denselben Standort, nicht dieselbe Ausgangs-IP.
• cookies — die Site-Sitzung, sodass Anmeldungen und Zustimmungsbanner über Aufrufe hinweg erhalten bleiben. Undurchsichtig; geben Sie sie unverändert zurück und bearbeiten Sie sie niemals.
• continuation — vorhanden, wenn die Seite auf mehr Ressourcen verwiesen hat, als in einen Aufruf passen. Rufen Sie erneut auf und übergeben Sie es, um den Rest abzurufen; url wird dann nicht benötigt.
• payment_required — vorhanden, wenn das Netzwerk das gleichzeitige Client-Limit seines Plans erreicht hat und eine Zahlung dies beheben kann. Unterschreiben Sie die beschriebene Zahlung und wiederholen Sie den identischen Aufruf mit payment, das auf die unterschriebene Zahlung gesetzt ist. Starten Sie keinen separaten Kaufvorgang.

Die Ressourcenerkennung ist statisch: Das HTML wird auf Verweise geparst. Inhalte, die eine Seite mit JavaScript lädt, werden nicht erkannt.

Erstellen eines Proxys zur direkten Verwendung

Um einen HTTPS/SOCKS/WireGuard-Proxy zu erhalten, den Sie selbst steuern, anstatt über den MCP-Server abzurufen, verwenden Sie den folgenden API-Ablauf.

Verwenden der API zum Erstellen eines HTTPS/SOCKS/WireGuard-Proxys für ein Land

Die API kann direkt verwendet werden, um einen HTTPS/SOCKS/WireGuard-Proxy für ein Land zu erstellen.

Schritt 1: Suchen Sie mit der Route /network/find-locations nach einer Liste von Standorten. Ein curl-Beispiel finden Sie unten, das an jq weitergeleitet wird, um die Standortliste zu extrahieren.

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

Schritt 2: Wählen Sie den gewünschten Standort aus und speichern Sie die Eigenschaft country_code.

Schritt 3: Erstellen Sie mit dem gespeicherten Ländercode über die Route /network/auth-client einen Proxy und setzen Sie proxy_config.initial_device_state so, dass es country_code enthält.

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

Verwenden der API zum Erstellen eines HTTPS/SOCKS/WireGuard-Proxys für einen Suchstandort

Die API kann direkt verwendet werden, um nach einem Standort zu suchen und einen HTTPS/SOCKS/WireGuard-Proxy zu erstellen. Es muss eine Entscheidung getroffen werden, welches Standortergebnis am besten geeignet ist. Jeder Standort hat eine location_id, die fest ist und im Code gespeichert werden kann.

Schritt 1: Suchen Sie mit der Route /network/find-locations nach einer Liste von Standorten. Ein curl-Beispiel finden Sie unten, das an jq weitergeleitet wird, um die Standortliste zu extrahieren.

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

Schritt 2: Wählen Sie den gewünschten Standort aus und speichern Sie die Eigenschaft location_id.

Schritt 3: Erstellen Sie mit der gespeicherten location_id über die Route /network/auth-client einen Proxy und setzen Sie proxy_config.initial_device_state.location so, dass es connect_location_id.location_id enthält.

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>"}}}}}'

Verwenden der API zum Erstellen eines HTTPS/SOCKS/WireGuard-Proxys für einen Suchstandort, wobei alle Egress-IPs an diesem Standort aufgelistet werden

Die API kann direkt verwendet werden, um nach einem Standort zu suchen, die Anbieter (Egress-IPs) an diesem Standort aufzulisten und für jede Egress-IP einen HTTPS/SOCKS/WireGuard-Proxy zu erstellen. Es muss eine Entscheidung getroffen werden, welches Standortergebnis am besten geeignet ist. Jeder Standort hat eine location_id, die fest ist und im Code gespeichert werden kann. Zusätzlich hat jeder Anbieter eine client_id, die fest ist und im Code gespeichert werden kann.

Schritt 1: Suchen Sie mit der Route /network/find-locations nach einer Liste von Standorten. Ein curl-Beispiel finden Sie unten, das an jq weitergeleitet wird, um die Standortliste zu extrahieren.

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

Schritt 2: Wählen Sie den gewünschten Standort aus und speichern Sie die location_id.

Schritt 3: Rufen Sie mit der Route /network/find-providers2 eine nach Rangfolge sortierte Liste der Anbieter (Egress-IPs) für die location_id ab. Die Stichprobengröße kann auf die Anzahl der benötigten eindeutigen Anbieter eingestellt werden. Ein curl-Beispiel finden Sie unten, das an jq weitergeleitet wird, um die Anbieterliste zu extrahieren.

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

Schritt 4: Erstellen Sie, indem Sie über jede client_id in der Liste iterieren, mit der client_id über die Route /network/auth-client einen Proxy und setzen Sie proxy_config.initial_device_state.location so, dass es connect_location_id.client_id enthält.

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>"}}}}}'