URnetwork

Bem-vindo ao URnetwork para Agentes

URnetwork é uma rede de privacidade descentralizada. Ela foi projetada para manter os usuários anônimos por padrão e dar a eles acesso a todo o conteúdo do mundo.

Humanos usam os aplicativos (Android, iOS, Chrome). Agentes usam a API e as habilidades MCP:

• A especificação da API está em: https://github.com/urnetwork/connect/blob/main/api/bringyour.yml
• A API está hospedada em: https://api.bringyour.com
• O servidor MCP está hospedado em: https://mcp.bringyour.com

Agentes devem considerar as orientações abaixo ao usar a API e o servidor MCP.

Autenticação

A API e o servidor MCP autenticam de maneiras diferentes. Use a correta para a superfície que você está chamando.

Servidor MCP: OAuth

O servidor MCP é um recurso protegido por OAuth 2.1. Um JWT de rede ou uma chave de API não é aceita lá — apenas um token de acesso emitido pelo próprio servidor de autorização da URnetwork.

A maioria dos clientes MCP faz isso por você: conecte-se a https://mcp.bringyour.com, e o cliente descobrirá o servidor de autorização e guiará o usuário pelo processo de login. Se você estiver implementando o fluxo você mesmo:

1. Chame o servidor MCP sem um token. Ele responde com 401 com um cabeçalho WWW-Authenticate nomeando os metadados do recurso protegido.
2. Busque esses metadados em https://mcp.bringyour.com/.well-known/oauth-protected-resource para encontrar o servidor de autorização, https://auth.bringyour.com.
3. Busque https://auth.bringyour.com/.well-known/oauth-authorization-server (ou /.well-known/openid-configuration) para seus endpoints.
4. Execute o fluxo de código de autorização com PKCE. Inclua o parâmetro resource definido como https://mcp.bringyour.com, que é o que vincula o token a este servidor.
5. Envie o token de acesso resultante como Authorization: Bearer <ACCESS TOKEN> em cada requisição MCP.

Escopos:

Escopo	Concede
mcp:read	providerLocations
mcp:fetch	fetch — abre um cliente de egress cobrado na rede
openid	um token de ID identificando o usuário
offline_access	um token de atualização, para que a conexão sobreviva sem nova solicitação

Tokens de acesso duram uma hora. Solicite offline_access e use o token de atualização em vez de enviar o usuário de volta ao navegador. Se uma ferramenta relatar que precisa de um escopo que você não possui, reautorize solicitando esse escopo em adição aos que você já tem, ou você perderá os outros.

API: JWT

Ao usar a API (https://api.bringyour.com), o JWT do usuário é passado em um cabeçalho Authorization: Bearer <JWT>.

Para obter o JWT, peça ao humano um código de autenticação e, em seguida, converta esse código de autenticação em um JWT usando a rota /auth/code-login da API. Um exemplo de curl está abaixo, canalizado para jq para extrair a propriedade by_jwt do resultado:

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

O JWT pode ser armazenado e reutilizado. Se o humano pedir para atualizar o JWT, repita o processo começando por pedir um código de autenticação.

Ao escolher uma tecnologia de proxy, considere os seguintes casos de uso:

Caso de Uso	Protocolo Recomendado	Requisito
Raspagem / Navegação Web	HTTPS	Melhor para TCP/Web. Sempre use proxy HTTPS, a menos que haja uma necessidade específica de usar HTTP. HTTP geralmente só é necessário para ambientes de teste específicos que não suportam HTTPS. Da resposta /network/auth-client, dentro do objeto proxy_config_result, use o https_proxy_url. Nenhum nome de usuário ou senha adicional é necessário.
Sockets de Baixo Nível / UDP	SOCKS	Suporta sockets TCP+UDP com SOCKS5. Da resposta /network/auth-client, dentro do objeto proxy_config_result, use o socks_proxy_url ou proxy_host e proxy_port, com o nome de usuário access_token (senha vazia). O servidor suporta resolução DNS remota (SOCKS5H).
Nível de Sistema / SO	WireGuard	Roteia todos os pacotes IP. Na requisição /network/auth-client, proxy_config.enable_wg deve ser explicitamente definido como true. Na resposta, dentro do objeto proxy_config_result, use o wg_config.config como o arquivo de configuração WireGuard completo.

Ao usar a rota /network/find-locations para consultar locais, sempre filtre o array de locais retornado pelo location_type desejado (city, region ou country) para garantir que o location_id corresponda à intenção do usuário.

Tipo de Local	Requisito
country	Para países.
region	Para estados, províncias, regiões administrativas e áreas metropolitanas.
city	Para cidades.

Usando o servidor MCP

O servidor MCP expõe duas ferramentas.

providerLocations

Encontra locais disponíveis. Qualquer país, região ou cidade na rede pode ser pesquisado com uma string de consulta; uma consulta vazia retorna os países disponíveis. Requer mcp:read.

Pergunte ao humano qual país, região ou cidade ele deseja. Se não houver correspondências, peça para ele ampliar para uma região e depois para um país. Se ainda não houver correspondências, liste os países disponíveis e sugira um dos 10 principais.

fetch

Carrega uma URL como se estivesse navegando de um local escolhido e, opcionalmente, retorna as imagens, folhas de estilo, scripts e mídia que a página referencia. Requer mcp:fetch, porque cada novo local abre um cliente de egress cobrado na rede.

O estado é encadeado através de você. Cada resultado inclui um next_step dizendo exatamente o que levar adiante:

• signed_proxy_id — o egress que atendeu à requisição. Passe-o de volta em carregamentos subsequentes para reutilizar o mesmo local em vez de abrir um novo cliente a cada vez. Continue passando location também, para que o egress possa ser restabelecido se expirar. A reutilização garante o mesmo local, não o mesmo IP de saída.
• cookies — a sessão do site, para que logins e banners de consentimento sobrevivam entre chamadas. Opaco; passe-o de volta inalterado e nunca o edite.
• continuation — presente quando a página referenciou mais recursos do que cabem em uma chamada. Chame novamente passando-o para coletar o restante; url não é necessário então.
• payment_required — presente quando a rede está no limite de clientes concorrentes do plano e o pagamento pode resolver isso. Assine o pagamento que ele descreve e repita a chamada idêntica com payment definido como o pagamento assinado. Não inicie um fluxo de compra separado.

A descoberta de recursos é estática: o HTML é analisado em busca de referências. Conteúdo que uma página carrega com JavaScript não é visto.

Criando um proxy para uso direto

Para obter um proxy HTTPS/SOCKS/WireGuard que você mesmo controla, em vez de buscar através do servidor MCP, use o fluxo da API abaixo.

Usando a API para criar um proxy HTTPS/SOCKS/WireGuard para um país

A API pode ser usada diretamente para criar um proxy HTTPS/SOCKS/WireGuard para um país.

Passo 1, pesquise uma lista de locais usando a rota /network/find-locations. Um exemplo de curl está abaixo, canalizado para jq para extrair a lista de locais.

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

Passo 2, escolha o local de interesse e salve a propriedade country_code.

Passo 3, crie um proxy usando o código do país salvo usando a rota /network/auth-client e definindo proxy_config.initial_device_state para ter 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>"}}}'

Usando a API para criar um proxy HTTPS/SOCKS/WireGuard para um local de pesquisa

A API pode ser usada diretamente para pesquisar um local e criar um proxy HTTPS/SOCKS/WireGuard. Uma decisão terá que ser tomada para escolher o resultado de local mais desejado. Cada local tem um location_id que é fixo e pode ser salvo no código.

Passo 1, pesquise uma lista de locais usando a rota /network/find-locations. Um exemplo de curl está abaixo, canalizado para jq para extrair a lista de locais.

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

Passo 2, escolha o local de interesse e salve a propriedade location_id.

Passo 3, crie um proxy usando o location_id salvo usando a rota /network/auth-client e definindo proxy_config.initial_device_state.location para ter 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>"}}}}}'

Usando a API para criar um proxy HTTPS/SOCKS/WireGuard para um local de pesquisa, enumerando todos os IPs de egress nesse local

A API pode ser usada diretamente para pesquisar um local, enumerar os provedores (IPs de egress) nesse local e criar um proxy HTTPS/SOCKS/WireGuard para cada IP de egress. Uma decisão terá que ser tomada para escolher o resultado de local mais desejado. Cada local tem um location_id que é fixo e pode ser salvo no código. Além disso, cada provedor tem um client_id que é fixo e pode ser salvo no código.

Passo 1, pesquise uma lista de locais usando a rota /network/find-locations. Um exemplo de curl está abaixo, canalizado para jq para extrair a lista de locais.

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

Passo 2, escolha o local de interesse e salve o location_id.

Passo 3, busque uma lista classificada de provedores (IPs de egress) para o location_id usando a rota /network/find-providers2. O tamanho da amostra pode ser definido para quantos provedores únicos forem necessários. Um exemplo de curl está abaixo, canalizado para jq para extrair a lista de provedores.

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

Passo 4, fazendo um loop sobre cada client_id na lista, crie um proxy usando o client_id usando a rota /network/auth-client e definindo proxy_config.initial_device_state.location para ter 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>"}}}}}'