Novada Proxy MCP server
✓ VerifiedRoute HTTP requests through residential IPs to bypass anti-bot systems, geo-target content, and maintain sticky sessions for AI agents.
Also known as NovadaLabs/proxy4agent, proxy4agent, bestproxy4agents-mcp
- Stars
- 4
- Tools
- 30
- Downloads, 30 days
- —
- Latest version
- 1.7.0
- Last commit
- Jun 18, 2026
- License
- MIT
What is Novada Proxy MCP?
Novada Proxy is an MCP server. Route HTTP requests through residential IPs to bypass anti-bot systems, geo-target content, and maintain sticky sessions for AI agents. It exposes 30 tools, such as novada_proxy_fetch, novada_proxy_batch_fetch, novada_proxy_extract.
Summary generated from the project's README
About Novada Proxy MCP server
Routing HTTP requests through residential IPs to bypass anti-bot systems is what proxy4agents-mcp enables for AI agents. This server allows developers to use real home device fingerprints from over 2 million Android, Windows, and Mac devices to access websites that typically block automated traffic from services like Cloudflare or Akamai. It is designed for use with MCP-compatible clients such as Claude Code, Cursor, Windsurf, Cline, and Continue.
Users set up the server by providing credentials like NOVADA_PROXY_USER and NOVADA_PROXY_PASS as environment variables. For advanced capabilities, the NOVADA_API_KEY enables Google search via novada_proxy_search, while NOVADA_BROWSER_WS allows for JavaScript rendering through novada_proxy_render. The server provides specialized tools for different web interaction needs, including novada_proxy_batch_fetch for concurrent requests, novada_proxy_extract for structured data retrieval, and novada_proxy_session to maintain a consistent IP address across multi-step workflows.
What you can do with it
- 1Bypass website bot detectionAn agent can access commercial websites that usually reject standard HTTP requests by using residential IP addresses.
Written from the project's README. Every use case is checked against a quote from it.
How to install Novada Proxy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Novada Proxy MCP in Claude Code
$ claude mcp add --env 'BRIGHTDATA_PASS=<YOUR_BRIGHTDATA_PASS>' --env 'BRIGHTDATA_USER=<YOUR_BRIGHTDATA_USER>' --env 'NOVADA_API_KEY=<YOUR_NOVADA_API_KEY>' --env 'NOVADA_BROWSER_WS=<YOUR_NOVADA_BROWSER_WS>' --env 'NOVADA_PROXY_PASS=<YOUR_NOVADA_PROXY_PASS>' --env 'NOVADA_PROXY_USER=<YOUR_NOVADA_PROXY_USER>' --env 'OXYLABS_PASS=<YOUR_OXYLABS_PASS>' --env 'OXYLABS_USER=<YOUR_OXYLABS_USER>' --env 'PROXY_URL=<YOUR_PROXY_URL>' --env 'SMARTPROXY_PASS=<YOUR_SMARTPROXY_PASS>' --env 'SMARTPROXY_USER=<YOUR_SMARTPROXY_USER>' proxy4agent -- npx -y bestproxy4agents-mcpInstall Novada Proxy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"proxy4agent": {
"command": "npx",
"args": [
"-y",
"bestproxy4agents-mcp"
],
"env": {
"BRIGHTDATA_PASS": "<YOUR_BRIGHTDATA_PASS>",
"BRIGHTDATA_USER": "<YOUR_BRIGHTDATA_USER>",
"NOVADA_API_KEY": "<YOUR_NOVADA_API_KEY>",
"NOVADA_BROWSER_WS": "<YOUR_NOVADA_BROWSER_WS>",
"NOVADA_PROXY_PASS": "<YOUR_NOVADA_PROXY_PASS>",
"NOVADA_PROXY_USER": "<YOUR_NOVADA_PROXY_USER>",
"OXYLABS_PASS": "<YOUR_OXYLABS_PASS>",
"OXYLABS_USER": "<YOUR_OXYLABS_USER>",
"PROXY_URL": "<YOUR_PROXY_URL>",
"SMARTPROXY_PASS": "<YOUR_SMARTPROXY_PASS>",
"SMARTPROXY_USER": "<YOUR_SMARTPROXY_USER>"
}
}
}
}Install Novada Proxy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"proxy4agent": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"bestproxy4agents-mcp"
],
"env": {
"BRIGHTDATA_PASS": "<YOUR_BRIGHTDATA_PASS>",
"BRIGHTDATA_USER": "<YOUR_BRIGHTDATA_USER>",
"NOVADA_API_KEY": "<YOUR_NOVADA_API_KEY>",
"NOVADA_BROWSER_WS": "<YOUR_NOVADA_BROWSER_WS>",
"NOVADA_PROXY_PASS": "<YOUR_NOVADA_PROXY_PASS>",
"NOVADA_PROXY_USER": "<YOUR_NOVADA_PROXY_USER>",
"OXYLABS_PASS": "<YOUR_OXYLABS_PASS>",
"OXYLABS_USER": "<YOUR_OXYLABS_USER>",
"PROXY_URL": "<YOUR_PROXY_URL>",
"SMARTPROXY_PASS": "<YOUR_SMARTPROXY_PASS>",
"SMARTPROXY_USER": "<YOUR_SMARTPROXY_USER>"
}
}
}
}Install Novada Proxy MCP in VS Code CLI
$ code --add-mcp '{"name":"proxy4agent","type":"stdio","command":"npx","args":["-y","bestproxy4agents-mcp"],"env":{"BRIGHTDATA_PASS":"<YOUR_BRIGHTDATA_PASS>","BRIGHTDATA_USER":"<YOUR_BRIGHTDATA_USER>","NOVADA_API_KEY":"<YOUR_NOVADA_API_KEY>","NOVADA_BROWSER_WS":"<YOUR_NOVADA_BROWSER_WS>","NOVADA_PROXY_PASS":"<YOUR_NOVADA_PROXY_PASS>","NOVADA_PROXY_USER":"<YOUR_NOVADA_PROXY_USER>","OXYLABS_PASS":"<YOUR_OXYLABS_PASS>","OXYLABS_USER":"<YOUR_OXYLABS_USER>","PROXY_URL":"<YOUR_PROXY_URL>","SMARTPROXY_PASS":"<YOUR_SMARTPROXY_PASS>","SMARTPROXY_USER":"<YOUR_SMARTPROXY_USER>"}}'Install Novada Proxy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"proxy4agent": {
"command": "npx",
"args": [
"-y",
"bestproxy4agents-mcp"
],
"env": {
"BRIGHTDATA_PASS": "<YOUR_BRIGHTDATA_PASS>",
"BRIGHTDATA_USER": "<YOUR_BRIGHTDATA_USER>",
"NOVADA_API_KEY": "<YOUR_NOVADA_API_KEY>",
"NOVADA_BROWSER_WS": "<YOUR_NOVADA_BROWSER_WS>",
"NOVADA_PROXY_PASS": "<YOUR_NOVADA_PROXY_PASS>",
"NOVADA_PROXY_USER": "<YOUR_NOVADA_PROXY_USER>",
"OXYLABS_PASS": "<YOUR_OXYLABS_PASS>",
"OXYLABS_USER": "<YOUR_OXYLABS_USER>",
"PROXY_URL": "<YOUR_PROXY_URL>",
"SMARTPROXY_PASS": "<YOUR_SMARTPROXY_PASS>",
"SMARTPROXY_USER": "<YOUR_SMARTPROXY_USER>"
}
}
}
}Install Novada Proxy MCP in Codex
$ codex mcp add proxy4agent --env 'BRIGHTDATA_PASS=<YOUR_BRIGHTDATA_PASS>' --env 'BRIGHTDATA_USER=<YOUR_BRIGHTDATA_USER>' --env 'NOVADA_API_KEY=<YOUR_NOVADA_API_KEY>' --env 'NOVADA_BROWSER_WS=<YOUR_NOVADA_BROWSER_WS>' --env 'NOVADA_PROXY_PASS=<YOUR_NOVADA_PROXY_PASS>' --env 'NOVADA_PROXY_USER=<YOUR_NOVADA_PROXY_USER>' --env 'OXYLABS_PASS=<YOUR_OXYLABS_PASS>' --env 'OXYLABS_USER=<YOUR_OXYLABS_USER>' --env 'PROXY_URL=<YOUR_PROXY_URL>' --env 'SMARTPROXY_PASS=<YOUR_SMARTPROXY_PASS>' --env 'SMARTPROXY_USER=<YOUR_SMARTPROXY_USER>' -- npx -y bestproxy4agents-mcpInstall Novada Proxy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.proxy4agent] command = "npx" args = ["-y", "bestproxy4agents-mcp"] [mcp_servers.proxy4agent.env] BRIGHTDATA_PASS = "<YOUR_BRIGHTDATA_PASS>" BRIGHTDATA_USER = "<YOUR_BRIGHTDATA_USER>" NOVADA_API_KEY = "<YOUR_NOVADA_API_KEY>" NOVADA_BROWSER_WS = "<YOUR_NOVADA_BROWSER_WS>" NOVADA_PROXY_PASS = "<YOUR_NOVADA_PROXY_PASS>" NOVADA_PROXY_USER = "<YOUR_NOVADA_PROXY_USER>" OXYLABS_PASS = "<YOUR_OXYLABS_PASS>" OXYLABS_USER = "<YOUR_OXYLABS_USER>" PROXY_URL = "<YOUR_PROXY_URL>" SMARTPROXY_PASS = "<YOUR_SMARTPROXY_PASS>" SMARTPROXY_USER = "<YOUR_SMARTPROXY_USER>"
Install Novada Proxy MCP in Gemini CLI
$ gemini mcp add -s user -e 'BRIGHTDATA_PASS=<YOUR_BRIGHTDATA_PASS>' -e 'BRIGHTDATA_USER=<YOUR_BRIGHTDATA_USER>' -e 'NOVADA_API_KEY=<YOUR_NOVADA_API_KEY>' -e 'NOVADA_BROWSER_WS=<YOUR_NOVADA_BROWSER_WS>' -e 'NOVADA_PROXY_PASS=<YOUR_NOVADA_PROXY_PASS>' -e 'NOVADA_PROXY_USER=<YOUR_NOVADA_PROXY_USER>' -e 'OXYLABS_PASS=<YOUR_OXYLABS_PASS>' -e 'OXYLABS_USER=<YOUR_OXYLABS_USER>' -e 'PROXY_URL=<YOUR_PROXY_URL>' -e 'SMARTPROXY_PASS=<YOUR_SMARTPROXY_PASS>' -e 'SMARTPROXY_USER=<YOUR_SMARTPROXY_USER>' proxy4agent npx -- -y bestproxy4agents-mcpInstall Novada Proxy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"proxy4agent": {
"command": "npx",
"args": [
"-y",
"bestproxy4agents-mcp"
],
"env": {
"BRIGHTDATA_PASS": "<YOUR_BRIGHTDATA_PASS>",
"BRIGHTDATA_USER": "<YOUR_BRIGHTDATA_USER>",
"NOVADA_API_KEY": "<YOUR_NOVADA_API_KEY>",
"NOVADA_BROWSER_WS": "<YOUR_NOVADA_BROWSER_WS>",
"NOVADA_PROXY_PASS": "<YOUR_NOVADA_PROXY_PASS>",
"NOVADA_PROXY_USER": "<YOUR_NOVADA_PROXY_USER>",
"OXYLABS_PASS": "<YOUR_OXYLABS_PASS>",
"OXYLABS_USER": "<YOUR_OXYLABS_USER>",
"PROXY_URL": "<YOUR_PROXY_URL>",
"SMARTPROXY_PASS": "<YOUR_SMARTPROXY_PASS>",
"SMARTPROXY_USER": "<YOUR_SMARTPROXY_USER>"
}
}
}
}Novada Proxy MCP tools 30
Detected from the READMEnovada_proxy_fetchnovada_proxy_batch_fetchnovada_proxy_extractnovada_proxy_mapnovada_proxy_crawlnovada_proxy_sessionnovada_proxy_searchnovada_proxy_rendernovada_proxy_researchnovada_proxy_statusurlcountry
Show all 30 toolsShow fewer tools
citysession_idformattimeouturlsconcurrencyfieldsrender_fallbacklimitinclude_externalverify_stickyquerynumlanguagewait_fordepthinclude_contentschema
Configuration
BRIGHTDATA_PASSSecretBrightData proxy password
BRIGHTDATA_USERSecretBrightData full username including zone
NOVADA_API_KEYSecretNovada Scraper API key for search tool
NOVADA_BROWSER_WSSecretNovada Browser API WebSocket URL for render tool
NOVADA_PROXY_PASSSecretNovada residential proxy password
NOVADA_PROXY_USERSecretNovada residential proxy username
OXYLABS_PASSSecretOxylabs password
OXYLABS_USERSecretOxylabs username
PROXY_URLSecretGeneric HTTP proxy URL (http://user:pass@host:port)
SMARTPROXY_PASSSecretSmartproxy password
SMARTPROXY_USERSecretSmartproxy username
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenovadalabs/proxy4agent is public and reachablegithub.com/novadalabs/proxy4agent ↗Pass
- Package names this repository as its sourcebestproxy4agents-mcp names novadalabs/proxy4agent as sourcenpmjs.com/package/bestproxy4agents-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-18github.com/novadalabs/proxy4agent ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from bestproxy4agents-mcpPass
- No critical advisory in the package or its dependencies199 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model30 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWorks 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 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_topicrunsnovada_proxy_searchthennovada_proxy_batch_fetchin 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: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 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. Usenovada_proxy_extractwithrender_fallback: truefor 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.
Novada Proxy MCP questions
How do I add Novada Proxy MCP to Claude Code?
Run claude mcp add --env 'BRIGHTDATA_PASS=<YOUR_BRIGHTDATA_PASS>' --env 'BRIGHTDATA_USER=<YOUR_BRIGHTDATA_USER>' --env 'NOVADA_API_KEY=<YOUR_NOVADA_API_KEY>' --env 'NOVADA_BROWSER_WS=<YOUR_NOVADA_BROWSER_WS>' --env 'NOVADA_PROXY_PASS=<YOUR_NOVADA_PROXY_PASS>' --env 'NOVADA_PROXY_USER=<YOUR_NOVADA_PROXY_USER>' --env 'OXYLABS_PASS=<YOUR_OXYLABS_PASS>' --env 'OXYLABS_USER=<YOUR_OXYLABS_USER>' --env 'PROXY_URL=<YOUR_PROXY_URL>' --env 'SMARTPROXY_PASS=<YOUR_SMARTPROXY_PASS>' --env 'SMARTPROXY_USER=<YOUR_SMARTPROXY_USER>' proxy4agent -- npx -y bestproxy4agents-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Novada Proxy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Novada Proxy MCP provide?
It exposes 30 tools, including novada_proxy_fetch, novada_proxy_batch_fetch, novada_proxy_extract, novada_proxy_map, novada_proxy_crawl.
How can I bypass anti-bot systems like Cloudflare or Akamai?
The server routes your requests through over 2 million real residential IPs from devices like Android phones, Windows PCs, and Macs, making them indistinguishable from human browsers.
Can I use this with other proxy providers?
Yes, the server is designed to work with any HTTP proxy provider, including BrightData, Smartproxy, and Oxylabs.
Does it support JavaScript-heavy websites?
Yes, by using the novada_proxy_render tool, you can render JS-heavy pages using a real Chromium instance.