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

Create a free account at novada.com — no credit card required
Get your credentials at Dashboard → Residential Proxies → Endpoint Generator — copy your username and password
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 [email protected]

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)	✓	—	—	—	—

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).

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).

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).

claude mcp add novada-proxy-mcp \
  -e PROXY_URL="http://username:[email protected]: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 targeting
`verify_sticky`	boolean	`false`	Make 3 proxy calls to confirm IP consistency (adds ~15–25s)
`format`	string	`markdown`	`markdown` or `raw`
`timeout`	number	`60`	Timeout in seconds

`novada_proxy_search`

Structured Google search via Novada Scraper API. Returns titles, URLs, and snippets as clean JSON — no HTML parsing needed.

Parameter	Type	Default	Description
`query`	string	required	Search query
`num`	number	`10`	Results (1–20)
`country`	string	—	Localize: `us`, `uk`, `de`, `jp`...
`language`	string	—	Language: `en`, `zh`, `de`, `ja`...

`novada_proxy_render` [BETA]

Render JavaScript-heavy pages using Novada's Browser API (real Chromium, full JS execution). Use for SPAs, React/Vue apps, and pages that return blank with a standard HTTP fetch.

Requires: NOVADA_BROWSER_WS — copy the Puppeteer URL from Dashboard -> Browser API -> Playground

Parameter	Type	Default	Description
`url`	string	required	Target URL
`format`	string	`markdown`	`markdown` / `html` / `text`
`wait_for`	string	—	CSS selector to wait for before extracting (e.g. `.product-title`)
`timeout`	number	`60`	Timeout in seconds (5–120)

Costs ~5 proxy credits per call vs 1 for novada_proxy_fetch. Use novada_proxy_extract with render_fallback: true for automatic escalation when needed.

`novada_proxy_crawl`

Recursively crawl a website via BFS traversal. Starts from a URL, discovers links at each depth level, and returns the full URL tree with metadata.

Parameter	Type	Default	Description
`url`	string	required	Starting URL to crawl
`depth`	number	`2`	BFS depth (1–5)
`limit`	number	`50`	Max pages to crawl (10–200)
`include_content`	boolean	`false`	Also return page content for each URL
`country`	string	—	Geo-target all fetches
`format`	string	`markdown`	Content format when `include_content: true`
`timeout`	number	`60`	Per-page timeout in seconds

When to use: Full-site scraping, sitemap generation, content indexing — when you need MORE than a single page.

Use novada_proxy_map instead if: You only need links from ONE page (one level deep). Map is faster and cheaper for single-page link discovery.

Chain with: novada_proxy_batch_fetch to scrape specific pages from the URL tree.

Example:

{
  "url": "https://example.com",
  "depth": 2,
  "limit": 50,
  "include_content": false
}

Response: data.pages[] (url, depth, status_code, total_links), data.urls[] (flat array for chaining into novada_proxy_batch_fetch)

`novada_proxy_research`

One-shot research tool — searches the web, fetches top results, and returns structured findings with source previews. The agent can analyze the findings for deeper synthesis.

Parameter	Type	Default	Description
`query`	string	required	Research question or topic
`depth`	string	`"standard"`	`"quick"` (3 sources), `"standard"` (5 sources), `"deep"` (10 sources)
`country`	string	—	Localize search results
`timeout`	number	`60`	Timeout in seconds

Requires: NOVADA_API_KEY (for Google search) + Proxy credentials (for fetching sources)

When to use: Research questions, topic investigation, competitive analysis, fact-finding — when you need content from multiple sources in one call.

Use novada_proxy_search instead if: You just need search result URLs, not full page content.

Chain with: novada_proxy_fetch on specific urls[] for deeper reading of individual sources.

Note: findings_summary is a concatenated preview of sources — your agent should analyze findings[] for actual synthesis.

Example:

{
  "query": "best residential proxy providers 2026",
  "depth": "standard"
}

Response: data.findings[] (title, url, snippet, content_preview), data.urls[] (for chaining), data.findings_summary

`novada_proxy_extract` — Schema Mode

In addition to fields (heuristic extraction), novada_proxy_extract supports a schema parameter for extracting any arbitrary field via your agent's LLM — zero additional API cost.

Schema Mode (LLM Extraction)

Pass schema instead of fields for arbitrary field extraction. The tool returns cleaned page content + an extraction prompt — your agent does the extraction (zero additional API cost).

Parameter	Type	Default	Description
`url`	string	required	Target URL
`schema`	object	—	Keys = field names, values = field descriptions. Use instead of `fields`.
`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

Example:

{
  "url": "https://example.com/product",
  "schema": {
    "product_name": "The full product name",
    "price": "Current price with currency",
    "warranty": "Warranty terms and duration",
    "return_policy": "Return policy summary"
  }
}

Response: data.mode = "llm_extract", data.content (cleaned markdown), data.extraction_prompt (instructions for your agent to follow and extract the fields)

Security: Schema keys must be alphanumeric/underscore (a-z, 0-9, _), max 50 chars. Values max 200 chars.

`novada_proxy_status`

Check proxy network connectivity and version. Makes a live proxy call to verify the connection is working. No credentials required.

Agent Workflows

Site crawl pipeline (map -> batch)

# Agent task: "Read all products on this catalogue"
1. novada_proxy_map(url="https://books.toscrape.com", limit=50)
   → returns 20–50 internal URLs in 4s, 1 credit

2. novada_proxy_batch_fetch(urls=[...20 URLs], concurrency=5)
   → fetches all 20 pages in parallel, ~4s wall time, 20 credits
   (vs ~60s sequential = 15x speedup)

Research pipeline (search -> batch)

# Agent task: "Find and read top 5 pages about X"
1. novada_proxy_search(query="residential proxy MCP", num=5)
   → structured JSON: titles, URLs, snippets

2. novada_proxy_batch_fetch(urls=[...5 URLs], format="markdown")
   → full content of all 5 pages in parallel

Sticky session — login + multi-page scrape

# Same IP across all calls
novada_proxy_session(session_id="job_001", url="https://example.com/login")
novada_proxy_session(session_id="job_001", url="https://example.com/dashboard")
novada_proxy_session(session_id="job_001", url="https://example.com/data/page/1")
novada_proxy_session(session_id="job_001", url="https://example.com/data/page/2")

Price monitoring — same product, three markets

novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="US")
novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="DE")
novada_proxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="JP")
# Second call per URL is a cache hit (0ms, 0 credits) if within 300s TTL

Extract structured data

# Agent task: "Get product details without parsing HTML"
novada_proxy_extract(
  url="https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  fields=["title", "price", "description", "rating"],
  render_fallback=true  # auto-retry via Chromium if proxy gets blocked
)

Response Cache

All novada_proxy_fetch and novada_proxy_batch_fetch calls are cached in-process. Repeated fetches to the same URL within the TTL window consume zero proxy credits.

Behavior	Detail
Default TTL	300 seconds (5 minutes)
Cache key	`url + format + country`
Session bypass	`session_id` present -> never cached (sticky routing requires live calls)
Disable	Set `PROXY4AGENT_CACHE_TTL_SECONDS=0`
Max entries	200 (oldest evicted when full)

Reading cache status from response:

"meta": {
  "cache_hit": true,          // served from cache — no proxy credit used
  "cache_age_seconds": 12,    // seconds since the entry was stored
  "latency_ms": 0             // ~0ms for cache hits
}

Typed Error Codes

Every error response includes a typed error.code, recoverable flag, and agent_instruction with the correct next step. Agents never need to parse error messages.

Code	Meaning	Recoverable	Agent Action
`BOT_DETECTION_SUSPECTED`	HTTP 4xx — target blocked the request	✓	Retry with `novada_proxy_render` or different `country`
`TLS_ERROR`	TLS/SSL connection failed through proxy	✓	Retry with a different `country` parameter
`TIMEOUT`	Request exceeded timeout limit	✓	Increase `timeout` or retry
`RATE_LIMITED`	HTTP 429 — too many requests	✓	Wait 5s and retry
`NETWORK_ERROR`	DNS failure — hostname not found	✗	Verify the URL is correct
`SESSION_STICKINESS_FAILED`	Same IP not maintained	✓	Retry `verify_sticky: true` to confirm
`INVALID_INPUT`	Bad parameter value	✗	Fix the parameter and retry
`PROVIDER_NOT_CONFIGURED`	Missing env vars	✗	Set credentials and restart MCP
`UNKNOWN_ERROR`	Unexpected error	✓	Check `novada_proxy_status`, retry

Error response format:

{
  "ok": false,
  "error": {
    "code": "BOT_DETECTION_SUSPECTED",
    "message": "HTTP 403 — request blocked by target",
    "recoverable": true,
    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."
  }
}

Geo Coverage

195+ countries including:

US GB DE FR JP CA AU BR IN KR SG NL IT ES MX RU PL SE NO DK FI CH AT BE PT CZ HU RO UA TR IL ZA NG EG AR CL CO PE VN TH ID MY PH TW HK NZ + 148 more

City-level targeting: newyork · losangeles · chicago · london · paris · berlin · tokyo · seoul · sydney · toronto · singapore · dubai · mumbai · saopaulo

Compatible With

Client	Install method
Claude Code	`claude mcp add novada-proxy-mcp -e ... -- npx -y novada-proxy-mcp`
Cursor	Settings -> MCP -> Add server -> `npx -y novada-proxy-mcp`
Windsurf	MCP config -> `npx -y novada-proxy-mcp`
Cline	MCP settings -> command: `npx`, args: `["-y", "novada-proxy-mcp"]`
Continue	`.continue/config.json` -> mcpServers
Smithery	smithery.ai/server/novada-proxy-mcp
Any MCP client	stdio transport / `npx -y novada-proxy-mcp`

Network

Metric	Value
Residential IPs	2,000,000+
Live nodes	7,000+
Countries	195+
Device types	Android, Windows, Mac
Uptime	99.9%

Confirmed Working

E-commerce: Amazon, eBay, Walmart, Etsy, Shopify stores
Professional: LinkedIn
Anti-bot protected: Cloudflare, Akamai, DataDome
News & content: HackerNews, Reddit, BBC, CNN, NYTimes
Tech: GitHub, Wikipedia, Stack Overflow, IMDB

Real-World Test Results

Tested across 3 Novada proxy types with 33 real-world tests (2026-04-28):

Proxy Type	Tests	Pass	Notes
Residential	11	9	Wikipedia, Shopify, HackerNews, geo-targeting work. Sticky sessions require endpoint config.
ISP	7	7	All tools work including sticky sessions (`session_verified: true`).
Datacenter	8	8	Fast, cost-effective. Anti-bot sites (Amazon, CNN) may block datacenter IPs — use residential for those.
Error handling	7	7	All error codes return structured JSON with `agent_instruction`.

Success rate: 94% (31/33 pass). Failures are proxy-type limitations (datacenter on anti-bot sites), not code bugs.

Proxy Type Guide

Use Case	Recommended Proxy	Why
Anti-bot sites (Amazon, LinkedIn, CNN)	Residential	Real home IPs, hardest to detect
Fast bulk scraping	Datacenter	Lowest latency, cheapest per GB
Sticky sessions (login flows)	ISP	6-hour sticky, stable IPs
General scraping	Any	All types handle most sites

Known Limitations

Limitation	Workaround
Datacenter IPs blocked on anti-bot sites	Use residential or ISP proxy type (`NOVADA_PROXY_ZONE=res`)
Proxy-side DNS errors surface as `TLS_ERROR`	Check if domain exists before retrying with different country
CLI is stateless (no cross-invocation cache)	Use MCP server for cache benefits, or re-fetch same URLs within one CLI batch
`novada_proxy_render` requires Browser API key	Set `NOVADA_BROWSER_WS` env var — get it from novada.com dashboard
Heuristic extraction misses a field	Use `schema` mode: pass `schema:{"field":"description"}` — returns cleaned content + extraction prompt for your agent to extract any field (zero-cost LLM extraction)

Feedback & Support

Email: [email protected]
GitHub Issues: github.com/NovadaLabs/Novada-proxy/issues
Website: novada.com

License

Novada Proxy（中文文档）

支持 Claude Code、Cursor、Windsurf、Cline、Continue 及所有 MCP 兼容智能体。由 Novada 提供支持。

[!TIP] 免费套餐 — 在 novada.com 注册，无需信用卡。免费使用 Scraper API、Web Unblocker 和住宅代理。

10 个工具

novada_proxy_fetch       → 通过住宅代理抓取任意 URL
novada_proxy_batch_fetch → 并发抓取 2-20 个 URL（最高 5 倍加速）
novada_proxy_extract     → 从页面提取结构化字段（标题、价格、评分…）
novada_proxy_map         → 爬取页面，返回所有内部链接 JSON 数组
novada_proxy_crawl       → 递归爬取站点（BFS，深度 1-5），自动发现 URL
novada_proxy_session     → 粘性会话 — 同一 session_id 始终同一 IP
novada_proxy_search      → Google 搜索，返回结构化 JSON（无需解析 HTML）
novada_proxy_render      → 真实 Chromium 渲染 JS 页面 [BETA]
novada_proxy_research    → 一键深度研究 — 搜索 + 抓取 + 综合分析
novada_proxy_status      → 检查代理网络健康状态

5 个提示词

预构建的智能体工作流，将多个工具链式组合。

提示词	描述	主要参数
`fetch_url`	通过住宅代理抓取 URL，自动绕过反机器人	`url`, `country`, `format`
`research_topic`	搜索 + 批量阅读工作流 — 搜索主题并阅读排名靠前的页面	`query`, `num_results`, `country`
`extract_product`	从任意电商 URL 提取结构化产品数据	`url`, `fields`
`crawl_site`	发现站点所有页面，然后并行抓取	`url`, `limit`, `country`
`troubleshoot`	代理故障逐步诊断	`error_message`

5 个资源

智能体可随时读取的参考数据，无需消耗代理额度。

资源 URI	描述
`proxy://countries`	195+ 国家代码完整列表，含城市级定位
`proxy://error-codes`	所有类型化错误码及恢复指令
`proxy://workflows`	常用智能体工作流模式（爬取、研究、监控）
`proxy://supported-fields`	`novada_proxy_extract` 支持的所有提取字段及策略
`proxy://cost-guide`	每个工具的额度消耗、缓存行为、成本优化技巧

快速决策指南

我想要...	使用工具
抓取单个 URL	`novada_proxy_fetch`
同时抓取 2-20 个 URL	`novada_proxy_batch_fetch`
提取特定字段（标题、价格…）	`novada_proxy_extract` 使用 `fields`
提取任意字段（Schema 模式）	`novada_proxy_extract` 使用 `schema`
获取页面上的所有链接	`novada_proxy_map`
爬取整个站点	`novada_proxy_crawl`
研究某个主题	`novada_proxy_research`
搜索 Google	`novada_proxy_search`
渲染 JS 重型页面	`novada_proxy_render`
跨请求保持同一 IP	`novada_proxy_session`
检查代理是否正常	`novada_proxy_status`

工具选择决策树

目标：抓取单个 URL
  ├─ 静态 HTML 页面？                    → novada_proxy_fetch
  ├─ 需要特定字段（价格/标题）？          → novada_proxy_extract（fields 或 schema 模式）
  └─ React/Vue SPA / 内容为空？          → novada_proxy_render

目标：批量抓取多个 URL
  ├─ 已有 URL 列表？                     → novada_proxy_batch_fetch
  ├─ 需要获取单页链接？                  → novada_proxy_map → novada_proxy_batch_fetch
  └─ 需要爬取整个站点？                  → novada_proxy_crawl → novada_proxy_batch_fetch

目标：研究某个主题                       → novada_proxy_research（一次调用搜索 + 抓取 + 分析）

目标：网页搜索                          → novada_proxy_search → novada_proxy_batch_fetch

目标：登录 + 多步骤流程                  → novada_proxy_session（相同 session_id）

目标：验证代理是否正常工作               → novada_proxy_status

三大流水线模式

全站爬取流水线（推荐）

novada_proxy_map(url, limit=50)
        │
        ▼
  返回 20-50 个内部链接（1 credit，4 秒）
        │
        ▼
novada_proxy_batch_fetch(urls, concurrency=5)
        │
        ▼
  并发抓取所有页面（N credits，~4 秒，比串行快 15x）

搜索研究流水线

novada_proxy_search(query, num=10)
        │
        ▼
  结构化 JSON：标题 + URL + 摘要
        │
        ▼
novada_proxy_batch_fetch(urls, format="markdown")
        │
        ▼
  全部页面内容并行返回

粘性会话 — 登录 + 多页抓取

session_id = "job_001"

novada_proxy_session(session_id, url="/login")    → 同一 IP
novada_proxy_session(session_id, url="/dashboard") → 同一 IP
novada_proxy_session(session_id, url="/data/1")    → 同一 IP
novada_proxy_session(session_id, url="/data/2")    → 同一 IP

智能体优先设计

[!NOTE] Novada Proxy 是唯一专为自主 AI 智能体设计的代理 MCP。每个响应、错误和描述都为机器消费而优化。

特性	含义
错误中的 `agent_instruction`	每个错误都告诉智能体下一步该做什么
描述中的决策树	每个工具都有 WHEN TO USE / USE INSTEAD 指引
`cache_hit` 元数据	智能体知道是否消耗了 0 额度（缓存命中）
`credits_estimated`	每个响应都内置成本追踪
类型化错误码	机器可读：`BOT_DETECTION_SUSPECTED`、`PAGE_NOT_FOUND` 等
5 个工作流提示词	预构建工作流：研究、爬取、提取、诊断
5 个参考资源	国家、错误码、成本指南 — 随时可访问

核心特性

1. 住宅 IP 网络

200 万+ 真实设备：Android 手机、Windows 电脑、Mac
7,000+ 活跃节点，99.9% 在线率
真实家庭 IP 指纹，绕过 Cloudflare、Akamai、DataDome 检测

2. 地理定向

195+ 国家，两字母 ISO 代码（US、DE、JP、BR...）
城市级定位：newyork、london、tokyo、singapore...
同一 URL 不同国家 = 独立缓存键，互不干扰

3. 响应缓存

重复抓取相同 URL 不消耗代理额度：

// 第一次调用（live fetch）
"meta": { "cache_hit": false, "latency_ms": 1800, "quota": { "credits_estimated": 1 } }

// 第二次调用（cache hit）
"meta": { "cache_hit": true, "cache_age_seconds": 5, "latency_ms": 0 }

配置项	说明
默认 TTL	300 秒（5 分钟）
缓存键	`url + format + country`
禁用缓存	`PROXY4AGENT_CACHE_TTL_SECONDS=0`
session_id	有 session_id 的请求永不缓存（粘性路由需要实时调用）

4. 智能体优先的 JSON 输出

所有工具返回统一结构：

{
  "ok": true / false,
  "tool": "工具名称",
  "data": { ... },
  "meta": {
    "latency_ms": 1800,
    "cache_hit": false,
    "quota": { "credits_estimated": 1 }
  }
}

5. 类型化错误码 + 恢复指令

每个错误都包含 code（枚举）、recoverable（布尔）、agent_instruction（下一步操作）：

Novada Proxy

README

Getting Started

For Humans

For Agents

Why Novada Proxy

10 Tools at a Glance

Quick Decision Guide

When To Use Which Tool

5 Prompts

5 Resources

Quick Install

Providers

Agent-First Design

Tools

novada_proxy_fetch

novada_proxy_batch_fetch

novada_proxy_extract

novada_proxy_map

novada_proxy_session

novada_proxy_search

novada_proxy_render [BETA]

novada_proxy_crawl

novada_proxy_research

novada_proxy_extract — Schema Mode

Schema Mode (LLM Extraction)

novada_proxy_status

Agent Workflows

Site crawl pipeline (map -> batch)

Research pipeline (search -> batch)

Sticky session — login + multi-page scrape

Price monitoring — same product, three markets

Extract structured data

Response Cache

Typed Error Codes

Geo Coverage

Compatible With

Network

Confirmed Working

Real-World Test Results

Proxy Type Guide

Known Limitations

Feedback & Support

License

Novada Proxy（中文文档）

10 个工具

5 个提示词

5 个资源

快速决策指南

工具选择决策树

三大流水线模式

全站爬取流水线（推荐）

搜索研究流水线

粘性会话 — 登录 + 多页抓取

智能体优先设计

核心特性

1. 住宅 IP 网络

2. 地理定向

3. 响应缓存

4. 智能体优先的 JSON 输出

5. 类型化错误码 + 恢复指令

Comments (0)

`novada_proxy_fetch`

`novada_proxy_batch_fetch`

`novada_proxy_extract`

`novada_proxy_map`

`novada_proxy_session`

`novada_proxy_search`

`novada_proxy_render` [BETA]

`novada_proxy_crawl`

`novada_proxy_research`

`novada_proxy_extract` — Schema Mode

`novada_proxy_status`