> For the complete documentation index, see [llms.txt](https://docs.ur.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ur.io/mcp/skill2.md).

# Optimized Skill Document: URnetwork for AI Agents

## Overview

URnetwork is a decentralized privacy network. AI Agents use this skill to provision anonymous network egress via SOCKS, HTTPS, or WireGuard proxies.

* **API Base:** `https://api.bringyour.com`
* **MCP Server:** `https://mcp.bringyour.com`
* **Spec:** `https://github.com/urnetwork/connect/blob/main/api/bringyour.yml`

## 1. Authentication Protocol

Agents must maintain a valid User JWT.

1. **Trigger:** If no JWT exists or 401 Unauthorized occurs.
2. **Action:** Prompt human: *"Please provide a URnetwork auth code to initialize the proxy connection."*
3. **Exchange:** Call `POST /auth/code-login` with `{"auth_code": "<CODE>"}`.
4. **Storage:** Extract `by_jwt`. Use in all headers as `Authorization: Bearer <JWT>`.

## 2. Proxy Technology Selection Logic

Before calling `/network/auth-client`, the Agent **must** determine the protocol based on the environment:

| Use Case                    | Recommended Protocol | Requirement                                                                                          |
| --------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| **Scraping / Web Browsing** | **HTTPS**            | Best for TCP/Web. Use `https_proxy_url`.                                                             |
| **Low-level Sockets / UDP** | **SOCKS**            | Supports TCP+UDP. Use `socks_proxy_url`. User: `access_token`, Pass: (empty).                        |
| **System-wide / OS Level**  | **WireGuard**        | Routes all IP packets. Set `proxy_config.enable_wg: true`. Use `wg_config.config` as a `.conf` file. |

## 3. Location Discovery & Selection Workflow

When a user requests a location (e.g., "Give me a London IP"), follow this recursive logic:

### Step 1: Search

Call `POST /network/find-locations` with `{"query": "<USER_QUERY>"}`.

### Step 2: Validation & Fallback

* **If 1+ results:** Present top matches to the human to confirm `location_type` (City vs. Country).
* **If 0 results:** 1. Broaden search (e.g., if "London City" fails, search "United Kingdom").

2. If broadening fails, fetch all available countries and suggest the top 10.

* **Conflict Resolution:** If the user is vague, ask: *"Would you like to connect to the City, Region, or Country level?"*

## 4. Implementation Patterns (API)

### Pattern A: Connecting by Country Code (Simplest)

Use this when only the country is specified.

* **Route:** `/network/auth-client`
* **Payload Fragment:**

```json
{
  "proxy_config": {
    "initial_device_state": {
      "country_code": "US"
    }
  }
}

```

### Pattern B: Connecting by Specific Location ID

Use this for specific cities or regions discovered in Step 3.

* **Path:** `proxy_config.initial_device_state.location.connect_location_id.location_id`
* **Payload Fragment:**

```json
{
  "proxy_config": {
    "initial_device_state": {
      "location": {
        "connect_location_id": { "location_id": "12345" }
      }
    }
  }
}

```

### Pattern C: Egress IP Rotation (Provider Level)

Use this if the user requires multiple unique IPs in the same location.

1. Call `POST /network/find-providers2` using the `location_id`.
2. Loop through the `providers` list.
3. For each `client_id`, call `/network/auth-client` using: `proxy_config.initial_device_state.location.connect_location_id.client_id`

## 5. Agent Constraints

* **Persistence:** Do not request a new Auth Code unless the JWT expires or the user explicitly asks to "re-login."
* **Security:** Never expose the JWT in logs or chat output.
* **Protocol:** Always prefer HTTPS over HTTP unless testing is specified.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ur.io/mcp/skill2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.