# URnetwork for agents

Give your agent residential network egress in 90+ countries, with the same
identity and privacy guarantees as human users. The happy path is the MCP
server; everything else on this page is fallback or detail.

## MCP server (preferred)

```
https://mcp.bringyour.com
```

- Protocol: MCPv2 — the stateless 2026-07-28 revision of the Model Context
  Protocol (streamable HTTP, JSON responses). Older protocol revisions are
  negotiated down automatically.
- Auth: OAuth. The first connect opens a browser sign-in to your account on
  https://ur.io and issues your agent a scoped token. No keys to paste.
  Discovery metadata: https://mcp.bringyour.com/.well-known/oauth-protected-resource
- A network account is required; a person creates it at https://ur.io.
  Start with a free account — x402 (below) tells your agent when an upgrade
  is actually needed.

### Tools

- `providerLocations` — find available provider locations (countries,
  regions, cities), with provider counts, stability, and strong-privacy flags.
- `fetch` — load a URL from a chosen country, region, or city, as if
  browsing from there, optionally returning referenced resources. State is
  threaded through the caller: pass back `signed_proxy_id` (reuse the same
  egress), `cookies` (opaque site session), `continuation` (collect
  remaining resources). Requires the `mcp:fetch` scope. When the network is
  at a plan limit the result carries `payment_required` — see x402 below.

## Add the server to your harness

### Claude Code

```
claude mcp add --transport http urnetwork https://mcp.bringyour.com
```

OAuth: run /mcp in a session, pick urnetwork, and finish the browser sign-in.

### Cursor

```
{
  "mcpServers": {
    "urnetwork": { "url": "https://mcp.bringyour.com" }
  }
}
```

.cursor/mcp.json (or ~/.cursor/mcp.json). Authenticate under Settings → MCP; the browser consent opens on connect.

### VS Code

```
code --add-mcp '{"name":"urnetwork","type":"http","url":"https://mcp.bringyour.com"}'
```

OAuth: on first start VS Code shows a trust prompt, then opens the browser sign-in (Copilot agent mode).

### Codex

```
codex mcp add urnetwork --url https://mcp.bringyour.com
```

OAuth: codex mcp login urnetwork opens the browser sign-in.

### Cline

```
{
  "mcpServers": {
    "urnetwork": { "type": "streamableHttp", "url": "https://mcp.bringyour.com" }
  }
}
```

MCP Servers → Remote Servers → Add (or cline_mcp_settings.json); recent builds run the browser sign-in when the server asks.

### Claude.ai

```
Settings → Connectors → Add custom connector → https://mcp.bringyour.com
```

Every plan, web and desktop. Connect runs the browser sign-in.

### ChatGPT

```
Settings → Developer mode → + → MCP server URL: https://mcp.bringyour.com
```

Plus/Pro/Business: pick OAuth as the connector auth; sign-in runs on connect.

### OpenClaw

```
openclaw mcp add urnetwork --url https://mcp.bringyour.com --transport streamable-http --auth oauth
```

OAuth: openclaw mcp login urnetwork prints the authorization link.

### Hermes

```
hermes mcp add urnetwork --url https://mcp.bringyour.com --auth oauth
```

OAuth: first connect prints an authorize URL and opens your browser, waiting on a loopback port; hermes mcp login urnetwork re-authenticates.

### OpenCode

```
{
  "mcp": {
    "urnetwork": { "type": "remote", "url": "https://mcp.bringyour.com", "enabled": true }
  }
}
```

opencode.json. OAuth is automatic on first use; opencode mcp auth urnetwork re-authenticates.

### Antigravity

```
{
  "mcpServers": {
    "urnetwork": { "serverUrl": "https://mcp.bringyour.com" }
  }
}
```

Agent panel → MCP Servers → Manage → edit the raw config (note serverUrl), then tap Authenticate.

### Devin

```
Settings → Connections → MCP servers → Add a custom MCP → Streamable HTTP → https://mcp.bringyour.com
```

Full OAuth flow, per person or per org. (Windsurf is now Devin Desktop; same place there.)

### Perplexity

```
Settings → Connectors → Add connector → https://mcp.bringyour.com
```

Pro/Max/Enterprise: choose OAuth at setup; works on web, Comet, and the Mac app.

### Zed

```
{
  "context_servers": {
    "urnetwork": { "url": "https://mcp.bringyour.com" }
  }
}
```

settings.json (note the context_servers key), or Settings → AI → MCP Servers → Add Remote Server; Zed prompts the standard MCP OAuth flow when no header is set.

### Factory Droid

```
droid mcp add urnetwork https://mcp.bringyour.com --type http
```

OAuth is the default for remote servers. Run /mcp inside droid to complete the sign-in.

### JetBrains

```
{
  "mcpServers": {
    "urnetwork": { "url": "https://mcp.bringyour.com" }
  }
}
```

Settings | Tools | AI Assistant | MCP → paste As JSON. No OAuth flow yet; use a static Authorization header or the mcp-remote bridge.

### Trae

```
{
  "mcpServers": {
    "urnetwork": { "url": "https://mcp.bringyour.com" }
  }
}
```

Settings → MCP → Add → Add Manually. Header auth only today; no OAuth in Trae yet.

### Qwen Code

```
qwen mcp add --transport http urnetwork https://mcp.bringyour.com
```

OAuth: runs automatically on connect (httpUrl + oauth.enabled in ~/.qwen/settings.json); manage via /mcp.

### Gemini CLI

```
gemini mcp add --transport http urnetwork https://mcp.bringyour.com
```

OAuth: automatic on first use; /mcp auth urnetwork re-authenticates. (Enterprise Gemini Code Assist; individual access moved to Antigravity.)

### Grok

```
grok.com → Connectors → New Connector → Custom → https://mcp.bringyour.com
```

OAuth runs during connector setup. Grok Build CLI: grok mcp add --transport http urnetwork https://mcp.bringyour.com.

### Kimi Code

```
kimi  →  /mcp-config  →  "add urnetwork https://mcp.bringyour.com"
```

AI-native MCP config: describe the server in /mcp-config and Kimi Code adds and authenticates it, with no JSON to hand-edit. (Successor to kimi-cli.)

## Live network data

- `GET https://api.bringyour.com/stats/last-90` — the network's public
  stats feed (providers, countries, cities, daily series for the last 90
  days). Unauthenticated JSON; the source behind the coverage figures the
  docs cite. Use it to verify claims instead of quoting them.
- `curl -H 'Accept: application/json' https://ur.io/ip` — the public IP
  address the request came from, as `{"ip": "<address>"}`. Send it through a
  proxy to see the egress address a site sees.

## The API

- OpenAPI 3.1 spec: https://ur.io/openapi.yml (rendered at
  https://ur.io/docs/api, summarized at https://ur.io/docs-md/api.md)
- Authentication: `Authorization: Bearer <token>`, where the token is a
  network JWT from an auth code or a long-lived `urn_` API key (both in the
  fallback below)

## x402 — pay as you go

The MCP server and the HTTP API both support x402: when a job hits a plan
limit, the server quotes machine-readable terms (`x402Version`,
`accepts[]` — USDC, one accept per settlement chain). The MCP server's
result carries them as `payment_required`. The HTTP API answers
`402 Payment Required` with them only to a request that asks with
`X-UR-X402: 1`, since x402 has no header a client sends before it is
quoted; without it a plan limit is the HTTP 200 refusal with
`error.upgrade_required`. Payment settles on-chain through an x402
facilitator, so an agent pays on whichever quoted chain it holds funds on.
Sign a payment for exactly the quoted amount and retry the same request with
the `X-PAYMENT` header; the response carries an `X-PAYMENT-RESPONSE`
settlement receipt.

Availability: x402 is not switched on for this deployment yet. Until it is, `GET /x402/skus` answers an error instead of a sku list (today an HTTP 500; the intended not-enabled answer is 404 "x402 is not enabled."). Treat any answer other than a 200 with a JSON sku list as "not available": ask the human on the account to upgrade, and do not retry the purchase flow.

- Public sku list (prices): `GET https://api.bringyour.com/x402/skus`
- Quote terms without paying (requires an account JWT; nothing is charged
  without a signed X-PAYMENT):

```
curl -i -X POST https://api.bringyour.com/x402/purchase \
  -H "Authorization: Bearer $URNETWORK_JWT" \
  -d '{"sku_id": "pro_1month"}'
```

- Spend cap honored by the default skill:

```
URNETWORK_X402_MAX=25.00
```

## Fallback: auth code + proxies

If OAuth is not an option in your runtime, sign in with an auth code instead:

1. A person signed in to the network creates an auth code at
   https://ur.io/app/account/settings and gives it to your agent, for example
   as `URNETWORK_AUTH_CODE=<auth code>`.
   A code works once and expires after 5 minutes.
2. Exchange the code for a network JWT. This call takes no authentication:

   ```
   curl -s -X POST https://api.bringyour.com/auth/code-login \
     -H 'Content-Type: application/json' \
     -d '{"auth_code": "<AUTH CODE>"}'
   ```

   The answer is `{"by_jwt": "<JWT>"}`, the token the next calls send (as
   `$URNETWORK_JWT` below). An unknown, used or expired code answers
   `{"error": {"message": "Invalid auth code."}}`.
3. Send the JWT as `Authorization: Bearer <JWT>`. For example,
   `POST /network/auth-client` with a `proxy_config` creates a client and
   returns its ready-to-use proxy endpoints in `proxy_config_result`:

   ```
   curl -s -X POST https://api.bringyour.com/network/auth-client \
     -H "Authorization: Bearer $URNETWORK_JWT" \
     -H 'Content-Type: application/json' \
     -d '{"proxy_config": {}}'
   ```

Pick the endpoint for the job:

| Use case | Protocol | Where |
| --- | --- | --- |
| Scraping / web browsing | HTTPS proxy | `proxy_config_result.https_proxy_url` |
| Low-level sockets / UDP | SOCKS5 (UR Pro) | `proxy_config_result.socks_proxy_url` (SOCKS5H supported) |
| System-wide / OS level | WireGuard (UR Pro) | `proxy_config_result.wg_config.config` (set `proxy_config.enable_wg: true` in the request) |

### Long-lived API keys

The JWT is tied to the session that created the auth code and ends with
it. For access that outlives that session, create an API key with the JWT:

```
curl -s -X POST https://api.bringyour.com/account/api-key \
  -H "Authorization: Bearer $URNETWORK_JWT" \
  -H 'Content-Type: application/json' \
  -d '{"name": "my agent"}'
```

The answer's `api_key` is a `urn_…` key, shown only in this answer. Send it
wherever a JWT goes: `Authorization: Bearer urn_…`. `GET /account/api-keys`
lists your keys and `POST /account/api-key/remove` with `{"id": "<key id>"}`
revokes one.

## Skill

The default skill wires the auth-code + proxy fallback path — including
reading a 402, paying, and retrying — into your runtime: https://github.com/urnetwork/skill/blob/main/SKILL.md
(For MCP-capable harnesses, the add-server recipes above are the whole
setup; the skill is the path for runtimes without MCP.)
