Proxy4agent

Novada Proxy

The agent-first residential proxy MCP — works with any provider.

Route any HTTP request through 2M+ real home devices — Android phones, Windows PCs, Macs — to bypass anti-bot systems, geo-target by country or city, and maintain sticky sessions across multi-step workflows. Powered by Novada.

Why · Install · Tools · Prompts · Resources · Providers · Agent-First

---

Works with Claude Code, Cursor, Windsurf, Cline, Continue, and any MCP-compatible AI agent.

> [!TIP] > Free tier available — sign up at novada.com, no credit card required. Get free access to Scraper API, Web Unblocker, and residential proxies to start building immediately.

---

Getting Started

For Humans

1. Create a free account at novada.com — no credit card required
2. Get your credentials at Dashboard → Residential Proxies → Endpoint Generator — copy your username and password
3. Install and run:

# Claude Code
claude mcp add novada-proxy-mcp \
  -e NOVADA_PROXY_USER=your_username \
  -e NOVADA_PROXY_PASS=your_password \
  -- npx -y novada-proxy-mcp

# Or use the CLI directly
npx novada-proxy-mcp status
npx novada-proxy fetch https://example.com

For Agents

> [!NOTE] > Agents: Tell your human to complete steps 1-2 above. Once credentials are set as environment variables, all 10 tools are available immediately. No API key rotation, no token refresh — proxy credentials are persistent.

Required env vars:
  NOVADA_PROXY_USER   — from novada.com dashboard
  NOVADA_PROXY_PASS   — from novada.com dashboard

Optional (for extra features):
  NOVADA_API_KEY      — enables novada_proxy_search (Google search)
  NOVADA_BROWSER_WS   — enables novada_proxy_render (JS rendering)
  NOVADA_PROXY_ZONE   — "res" (default), "isp", or "dcp"

Need help? Contact [support@novada.com](mailto:support@novada.com)

---

Why Novada Proxy

AI agents get blocked on 60–70% of commercial websites. Standard HTTP requests are detected and rejected by Cloudflare, Akamai, DataDome, and PerimeterX. Novada Proxy routes your agent through real residential IPs — indistinguishable from a human browser.

| Problem | Solution | |---------|----------| | Amazon, LinkedIn, Cloudflare block your agent | 2M+ residential IPs from real home devices | | Bot challenges return 403 / CAPTCHA | Real device fingerprints bypass detection | | JS-rendered pages return blank content | novada_proxy_render runs real Chromium | | Geo-restricted or localized content | 195+ countries, city-level targeting | | Multi-step workflows need the same IP | Sticky sessions — consistent IP across calls | | Scraping 10+ URLs wastes time | novada_proxy_batch_fetch — concurrent, parallel | | Need structured fields, not raw HTML | novada_proxy_extract — title, price, rating, etc. | | Finding URLs before scraping | novada_proxy_map — discover all internal links | | Need clean search results | novada_proxy_search — Google results as JSON |

---

10 Tools at a Glance

| Tool | What It Does | Requires | |------|-------------|---------| | novada_proxy_fetch | Fetch any URL through residential proxy | Proxy credentials | | novada_proxy_batch_fetch | Fetch 2–20 URLs concurrently (up to 5x parallel) | Proxy credentials | | novada_proxy_extract | Extract structured fields — heuristic mode (fields) or LLM mode (schema) | Proxy credentials | | novada_proxy_map | Crawl a URL and return all internal links as JSON array | Proxy credentials | | novada_proxy_crawl | Recursively crawl a site (BFS, depth 1-5) with URL discovery | Proxy credentials | | novada_proxy_session | Sticky session — same IP across every call | Proxy credentials | | novada_proxy_search | Google search -> structured JSON (title, url, snippet) | NOVADA_API_KEY | | novada_proxy_render | Render JS-heavy pages with real Chromium [BETA] | NOVADA_BROWSER_WS | | novada_proxy_research | One-shot deep research — search + fetch + synthesize | NOVADA_API_KEY + Proxy | | novada_proxy_status | Check proxy network health + version | (none) |

---

Quick Decision Guide

| I want to... | Use this tool | |--------------|---------------| | Fetch a single URL | novada_proxy_fetch | | Fetch 2–20 URLs at once | novada_proxy_batch_fetch | | Extract specific fields (title, price...) | novada_proxy_extract with fields | | Extract ANY field via schema | novada_proxy_extract with schema | | Find all links on a page | novada_proxy_map | | Crawl an entire site | novada_proxy_crawl | | Research a topic | novada_proxy_research | | Search Google | novada_proxy_search | | Render a JS-heavy page | novada_proxy_render | | Keep same IP across calls | novada_proxy_session | | Check if proxy works | novada_proxy_status |

When To Use Which Tool

Goal: "Scrape a single URL"
  └─ Static HTML page?          → novada_proxy_fetch
  └─ Need specific fields?      → novada_proxy_extract (fields or schema mode)
  └─ React/Vue SPA / blank page? → novada_proxy_render

Goal: "Scrape multiple URLs"
  └─ You have the URLs already  → novada_proxy_batch_fetch
  └─ You need links from one page → novada_proxy_map → novada_proxy_batch_fetch
  └─ You need to crawl a whole site → novada_proxy_crawl → novada_proxy_batch_fetch

Goal: "Research a topic"        → novada_proxy_research (search + fetch + findings in one call)

Goal: "Search the web"          → novada_proxy_search → novada_proxy_batch_fetch

Goal: "Login + multi-page flow" → novada_proxy_session (same session_id)

Goal: "Check if proxy works"    → novada_proxy_status

---

5 Prompts

Pre-built agent workflows that chain multiple tools together. Call these from any MCP client to execute common patterns in one step.

| Prompt | Description | Key Arguments | |--------|-------------|---------------| | fetch_url | Fetch a URL through residential proxy with anti-bot bypass | url, country, format | | research_topic | Search + batch read workflow — find and read top pages on a topic | query, num_results, country | | extract_product | Extract structured product data from any e-commerce URL | url, fields | | crawl_site | Discover all pages on a site, then fetch them in parallel | url, limit, country | | troubleshoot | Step-by-step proxy diagnosis when things go wrong | error_message |

> [!NOTE] > Prompts orchestrate multi-tool workflows automatically. For example, research_topic runs novada_proxy_search then novada_proxy_batch_fetch in sequence — the agent doesn't need to figure out the pipeline.

---

5 Resources

Always-accessible reference data that agents can read at any time, without making proxy calls.

| Resource URI | Description | |-------------|-------------| | proxy://countries | Complete list of 195+ country codes with city-level targeting | | proxy://error-codes | All typed error codes with recovery instructions | | proxy://workflows | Common agent workflow patterns (crawl, research, monitoring) | | proxy://supported-fields | All fields novada_proxy_extract can extract with strategies | | proxy://cost-guide | Credits per tool, caching behavior, cost optimization tips |

---

Quick Install

Core — fetch any URL through residential proxy:

claude mcp add novada-proxy-mcp \
  -e NOVADA_PROXY_USER=your_username \
  -e NOVADA_PROXY_PASS=your_password \
  -- npx -y novada-proxy-mcp

Search only:

claude mcp add novada-proxy-mcp \
  -e NOVADA_API_KEY=your_key \
  -- npx -y novada-proxy-mcp

All tools (proxy + search + browser render):

claude mcp add novada-proxy-mcp \
  -e NOVADA_PROXY_USER=your_username \
  -e NOVADA_PROXY_PASS=your_password \
  -e NOVADA_API_KEY=your_key \
  -e NOVADA_BROWSER_WS=your_browser_ws_url \
  -- npx -y novada-proxy-mcp

Cursor / Windsurf / Cline — add to MCP config:

{
  "mcpServers": {
    "novada-proxy-mcp": {
      "command": "npx",
      "args": ["-y", "novada-proxy-mcp"],
      "env": {
        "NOVADA_PROXY_USER": "your_username",
        "NOVADA_PROXY_PASS": "your_password"
      }
    }
  }
}

Get credentials: novada.com -> Dashboard -> Residential Proxies -> Endpoint Generator

---

Providers

Novada Proxy works with any HTTP proxy provider. Novada is the built-in default with the deepest integration.

Priority: Novada -> BrightData -> Smartproxy -> Oxylabs -> Generic. First configured provider wins.

| Feature | Novada | BrightData | Smartproxy | Oxylabs | Generic HTTP | |---------|--------|------------|------------|---------|-------------| | Auto country targeting | ✓ | ✓ | ✓ | ✓ | manual | | Auto city targeting | ✓ | ✓ | ✓ | ✓ | manual | | Sticky sessions | ✓ | ✓ | ✓ | ✓ | manual | | Built-in search API | ✓ | — | — | — | — | | Browser API (JS render) | ✓ | — | — | — | — |

BrightData setup

claude mcp add novada-proxy-mcp \
  -e BRIGHTDATA_USER="brd-customer-abc123-zone-residential" \
  -e BRIGHTDATA_PASS=your_password \
  -- npx -y novada-proxy-mcp

BRIGHTDATA_USER is your full username including zone. Optional: BRIGHTDATA_HOST, BRIGHTDATA_PORT (default zproxy.lum-superproxy.io:22225).

Smartproxy setup

claude mcp add novada-proxy-mcp \
  -e SMARTPROXY_USER=your_username \
  -e SMARTPROXY_PASS=your_password \
  -- npx -y novada-proxy-mcp

Optional: SMARTPROXY_HOST, SMARTPROXY_PORT (default gate.smartproxy.com:10001).

Oxylabs setup

claude mcp add novada-proxy-mcp \
  -e OXYLABS_USER=your_username \
  -e OXYLABS_PASS=your_password \
  -- npx -y novada-proxy-mcp

Optional: OXYLABS_HOST, OXYLABS_PORT (default pr.oxylabs.io:7777).

Generic HTTP proxy (IPRoyal, any provider)

claude mcp add novada-proxy-mcp \
  -e PROXY_URL="http://username:password@geo.iproyal.com:12321" \
  -- npx -y novada-proxy-mcp

country, city, session_id params are ignored with Generic — encode targeting directly in your proxy URL.

---

Agent-First Design

> [!NOTE] > Novada Proxy is the only proxy MCP designed specifically for autonomous AI agents. Every response, error, and description is optimized for machine consumption.

| Feature | What It Means | |---------|--------------| | agent_instruction in errors | Every error tells the agent exactly what to do next | | Decision trees in descriptions | WHEN TO USE / USE INSTEAD guides in every tool | | cache_hit metadata | Agent knows when 0 credits were used (cached response) | | credits_estimated per call | Cost tracking built into every response | | Typed error codes | Machine-readable: BOT_DETECTION_SUSPECTED, PAGE_NOT_FOUND, etc. | | 5 workflow prompts | Pre-built agent workflows: research, crawl, extract, diagnose | | 5 reference resources | Countries, error codes, cost guide — always accessible |

---

Tools

novada_proxy_fetch

Fetch any URL through a residential proxy. Returns structured JSON with content, status code, and metadata. Auto-retry on network errors. Caches repeated calls (default 300s TTL — meta.cache_hit: true means no proxy credit used).

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | url | string | required | Target URL (http:// or https://) | | country | string | — | 2-letter ISO code: US, DE, JP, GB, BR... (195+ options) | | city | string | — | City: newyork, london, tokyo, paris, berlin... | | session_id | string | — | Reuse same ID for same IP across calls (no hyphens, max 64 chars) | | format | string | markdown | markdown strips HTML / raw returns full HTML | | timeout | number | 60 | Timeout in seconds (1–120) |

Response:

{
  "ok": true,
  "tool": "novada_proxy_fetch",
  "data": { "url": "...", "status_code": 200, "content": "...", "size_bytes": 34000 },
  "meta": { "latency_ms": 1800, "cache_hit": false, "quota": { "credits_estimated": 1 } }
}

---

novada_proxy_batch_fetch

Fetch 2–20 URLs concurrently through residential proxy. Up to 5x faster than sequential fetches. Per-URL errors are captured individually — the batch itself succeeds even if some URLs fail. Reuses response cache for URLs already fetched.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | urls | string[] | required | 2–20 URLs to fetch | | concurrency | number | 3 | Parallel requests (1–5) | | country | string | — | Same country for all URLs | | format | string | markdown | markdown or raw | | timeout | number | 60 | Per-URL timeout in seconds |

Response:

{
  "ok": true,
  "tool": "novada_proxy_batch_fetch",
  "data": {
    "requested": 3,
    "succeeded": 3,
    "failed": 0,
    "results": [
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": false, "latency_ms": 1200 },
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": true,  "latency_ms": 0 },
      { "url": "https://...", "ok": false, "error": { "code": "TLS_ERROR", "message": "..." } }
    ]
  },
  "meta": { "latency_ms": 4100, "quota": { "credits_estimated": 3 } }
}

---

novada_proxy_extract

Extract structured fields from any URL using heuristic pattern matching (meta tags, Open Graph, JSON-LD, Schema.org). Lightweight — no LLM needed. Set render_fallback: true to automatically retry via real Chromium if the proxy fetch fails.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | url | string | required | Target URL | | fields | string[] | required | Fields to extract: title, price, description, rating, image, author, date... | | render_fallback | boolean | false | Auto-retry via novada_proxy_render on TLS/bot block | | country | string | — | Geo-target the fetch | | timeout | number | 60 | Timeout in seconds |

Response:

{
  "ok": true,
  "tool": "novada_proxy_extract",
  "data": {
    "url": "https://books.toscrape.com/...",
    "fields": { "title": "A Light in the Attic", "price": "£51.77", "description": null },
    "extracted_via": "proxy_fetch"
  },
  "meta": { "latency_ms": 2100, "quota": { "credits_estimated": 1 } }
}

---

novada_proxy_map

Crawl a URL and return all internal links as a structured JSON array. Use as the discovery step before novada_proxy_batch_fetch to crawl an entire site without guessing URLs.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | url | string | required | Starting URL to crawl | | limit | number | 50 | Max URLs to return (10–200) | | include_external | boolean | false | Include off-domain links | | country | string | — | Geo-target the fetch | | timeout | number | 60 | Timeout in seconds |

Response:

{
  "ok": true,
  "tool": "novada_proxy_map",
  "data": {
    "domain": "books.toscrape.com",
    "internal_url_count": 20,
    "internal_urls": ["https://books.toscrape.com/catalogue/...", "..."],
    "sitemap_hint": "https://books.toscrape.com/sitemap.xml (check manually)"
  },
  "meta": { "latency_ms": 3800, "quota": { "credits_estimated": 1 } }
}

---

novada_proxy_session

Sticky session fetch — every call with the same session_id uses the same residential IP. Essential for login flows, paginated scraping, and price monitoring. Supports verify_sticky: true to confirm IP consistency before relying on it.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | session_id | string | required | Unique ID — reuse to keep same IP (no hyphens, max 64 chars) | | url | string | required | Target URL | | country | string | — | 2-letter country code | | city | string | — | City-level targe

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NovadaLabs
• Source: NovadaLabs/novada-proxy
• License: MIT
• Homepage: https://www.novada.com

Install and usage instructions live in the source repository linked above.