CAT
/MCP
SkillsMCPMarketplacesDigestToolsAdvertise

This week in Claude

Every Monday: Claude Code, Agent SDK, MCP, and the Anthropic platform moves worth your time.

Skills by Category
Frontend DevelopmentBackend & APIsTesting & QASecurityDevOps & CI/CDGit & Pull RequestsDocumentationCode Review & QualityAI & Agent BuildingSkill Development
MCP Servers by Category
Sales & MarketingWeb & Browser AutomationDatabasesAI & LLM ToolsCloud & InfrastructureCommunication & MessagingDeveloper ToolsDesign & CreativeDocuments & KnowledgeSearch & Web Crawling
Marketplaces by Category
AI Agents & OrchestrationLLM IntegrationDevelopment ToolsFrontend & UIBackend & APIsDatabasesTesting & Code QualityDevOps & CloudSecurity & ComplianceGit & Version Control

Cross AI Tools

Discover Claude Code plugins, extensions, and tools. Automatically updated directory of Anthropic Claude AI marketplaces with development tools, productivity plugins, and integrations.

Resources

  • Browse Skills
  • Browse MCP Servers
  • Browse Marketplaces
  • Plugins Reference

Community

  • About
  • Tools
  • Feedback
  • Privacy Policy
  • Advertise

Built for the Claude Code community with Claude Code by @mertduzgun

Independent project, not affiliated with Anthropic

Proxy4agents Mcp

novadalabs/proxy4agent
4authSTDIOregistry active
Summary

Wraps Novada's 2M+ residential proxy network in an MCP interface with 10 tools for bypassing anti-bot systems and scraping restricted content. Exposes operations like novada_proxy_fetch for single requests, novada_proxy_batch_fetch for concurrent fetching, novada_proxy_extract for structured data extraction with schema support, and novada_proxy_render for JavaScript-heavy pages via real Chromium. Includes sticky sessions to maintain the same IP across multi-step workflows, city-level geo-targeting across 195 countries, and novada_proxy_search for structured Google results. Reach for this when your agent needs to access content behind Cloudflare, scrape at scale without getting blocked, or pull localized data that standard HTTP clients can't touch. Requires Novada credentials from their dashboard, with optional API key for search features.

CodeRabbit
CodeRabbit
AI writes the code. CodeRabbit catches the slop.
Try For Free →
Keep your Mac awake
Keep your Mac awake
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Context.devContext.dev
Context.dev
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Make your agent a DeFi expert
Make your agent a DeFi expert
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make money from your Skills
Make money from your Skills
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
AppSignal
AppSignal
Monitor with ease. Code with confidence.
Start Free Trial →
CodeRabbit
CodeRabbit
AI writes the code. CodeRabbit catches the slop.
Try For Free →
Keep your Mac awake
Keep your Mac awake
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Context.devContext.dev
Context.dev
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Make your agent a DeFi expert
Make your agent a DeFi expert
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make money from your Skills
Make money from your Skills
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
AppSignal
AppSignal
Monitor with ease. Code with confidence.
Start Free Trial →

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.

npm version npm downloads License: MIT CI Node.js

10 tools 5 prompts 5 resources 430 tests 5 providers

LobeHub MCP LobeHub MCP Full Smithery MCP Registry

English 中文文档

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

Step 1 Step 2 Step 3

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


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.

ProblemSolution
Amazon, LinkedIn, Cloudflare block your agent2M+ residential IPs from real home devices
Bot challenges return 403 / CAPTCHAReal device fingerprints bypass detection
JS-rendered pages return blank contentnovada_proxy_render runs real Chromium
Geo-restricted or localized content195+ countries, city-level targeting
Multi-step workflows need the same IPSticky sessions — consistent IP across calls
Scraping 10+ URLs wastes timenovada_proxy_batch_fetch — concurrent, parallel
Need structured fields, not raw HTMLnovada_proxy_extract — title, price, rating, etc.
Finding URLs before scrapingnovada_proxy_map — discover all internal links
Need clean search resultsnovada_proxy_search — Google results as JSON

10 Tools at a Glance

ToolWhat It DoesRequires
novada_proxy_fetchFetch any URL through residential proxyProxy credentials
novada_proxy_batch_fetchFetch 2–20 URLs concurrently (up to 5x parallel)Proxy credentials
novada_proxy_extractExtract structured fields — heuristic mode (fields) or LLM mode (schema)Proxy credentials
novada_proxy_mapCrawl a URL and return all internal links as JSON arrayProxy credentials
novada_proxy_crawlRecursively crawl a site (BFS, depth 1-5) with URL discoveryProxy credentials
novada_proxy_sessionSticky session — same IP across every callProxy credentials
novada_proxy_searchGoogle search -> structured JSON (title, url, snippet)NOVADA_API_KEY
novada_proxy_renderRender JS-heavy pages with real Chromium [BETA]NOVADA_BROWSER_WS
novada_proxy_researchOne-shot deep research — search + fetch + synthesizeNOVADA_API_KEY + Proxy
novada_proxy_statusCheck proxy network health + version(none)

Quick Decision Guide

I want to...Use this tool
Fetch a single URLnovada_proxy_fetch
Fetch 2–20 URLs at oncenovada_proxy_batch_fetch
Extract specific fields (title, price...)novada_proxy_extract with fields
Extract ANY field via schemanovada_proxy_extract with schema
Find all links on a pagenovada_proxy_map
Crawl an entire sitenovada_proxy_crawl
Research a topicnovada_proxy_research
Search Googlenovada_proxy_search
Render a JS-heavy pagenovada_proxy_render
Keep same IP across callsnovada_proxy_session
Check if proxy worksnovada_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.

PromptDescriptionKey Arguments
fetch_urlFetch a URL through residential proxy with anti-bot bypassurl, country, format
research_topicSearch + batch read workflow — find and read top pages on a topicquery, num_results, country
extract_productExtract structured product data from any e-commerce URLurl, fields
crawl_siteDiscover all pages on a site, then fetch them in parallelurl, limit, country
troubleshootStep-by-step proxy diagnosis when things go wrongerror_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 URIDescription
proxy://countriesComplete list of 195+ country codes with city-level targeting
proxy://error-codesAll typed error codes with recovery instructions
proxy://workflowsCommon agent workflow patterns (crawl, research, monitoring)
proxy://supported-fieldsAll fields novada_proxy_extract can extract with strategies
proxy://cost-guideCredits 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.

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

FeatureWhat It Means
agent_instruction in errorsEvery error tells the agent exactly what to do next
Decision trees in descriptionsWHEN TO USE / USE INSTEAD guides in every tool
cache_hit metadataAgent knows when 0 credits were used (cached response)
credits_estimated per callCost tracking built into every response
Typed error codesMachine-readable: BOT_DETECTION_SUSPECTED, PAGE_NOT_FOUND, etc.
5 workflow promptsPre-built agent workflows: research, crawl, extract, diagnose
5 reference resourcesCountries, 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).

ParameterTypeDefaultDescription
urlstringrequiredTarget URL (http:// or https://)
countrystring—2-letter ISO code: US, DE, JP, GB, BR... (195+ options)
citystring—City: newyork, london, tokyo, paris, berlin...
session_idstring—Reuse same ID for same IP across calls (no hyphens, max 64 chars)
formatstringmarkdownmarkdown strips HTML / raw returns full HTML
timeoutnumber60Timeout 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.

ParameterTypeDefaultDescription
urlsstring[]required2–20 URLs to fetch
concurrencynumber3Parallel requests (1–5)
countrystring—Same country for all URLs
formatstringmarkdownmarkdown or raw
timeoutnumber60Per-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.

ParameterTypeDefaultDescription
urlstringrequiredTarget URL
fieldsstring[]requiredFields to extract: title, price, description, rating, image, author, date...
render_fallbackbooleanfalseAuto-retry via novada_proxy_render on TLS/bot block
countrystring—Geo-target the fetch
timeoutnumber60Timeout 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.

ParameterTypeDefaultDescription
urlstringrequiredStarting URL to crawl
limitnumber50Max URLs to return (10–200)
include_externalbooleanfalseInclude off-domain links
countrystring—Geo-target the fetch
timeoutnumber60Timeout 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.

ParameterTypeDefaultDescription
session_idstringrequiredUnique ID — reuse to keep same IP (no hyphens, max 64 chars)
urlstringrequiredTarget URL
countrystring—2-letter country code
citystring—City-level targeting
verify_stickybooleanfalseMake 3 proxy calls to confirm IP consistency (adds ~15–25s)
formatstringmarkdownmarkdown or raw
timeoutnumber60Timeout in seconds

novada_proxy_search

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

ParameterTypeDefaultDescription
querystringrequiredSearch query
numnumber10Results (1–20)
countrystring—Localize: us, uk, de, jp...
languagestring—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

ParameterTypeDefaultDescription
urlstringrequiredTarget URL
formatstringmarkdownmarkdown / html / text
wait_forstring—CSS selector to wait for before extracting (e.g. .product-title)
timeoutnumber60Timeout 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.

ParameterTypeDefaultDescription
urlstringrequiredStarting URL to crawl
depthnumber2BFS depth (1–5)
limitnumber50Max pages to crawl (10–200)
include_contentbooleanfalseAlso return page content for each URL
countrystring—Geo-target all fetches
formatstringmarkdownContent format when include_content: true
timeoutnumber60Per-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.

ParameterTypeDefaultDescription
querystringrequiredResearch question or topic
depthstring"standard""quick" (3 sources), "standard" (5 sources), "deep" (10 sources)
countrystring—Localize search results
timeoutnumber60Timeout 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).

ParameterTypeDefaultDescription
urlstringrequiredTarget URL
schemaobject—Keys = field names, values = field descriptions. Use instead of fields.
render_fallbackbooleanfalseAuto-retry via novada_proxy_render on TLS/bot block
countrystring—Geo-target the fetch
timeoutnumber60Timeout 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.

BehaviorDetail
Default TTL300 seconds (5 minutes)
Cache keyurl + format + country
Session bypasssession_id present -> never cached (sticky routing requires live calls)
DisableSet PROXY4AGENT_CACHE_TTL_SECONDS=0
Max entries200 (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.

CodeMeaningRecoverableAgent Action
BOT_DETECTION_SUSPECTEDHTTP 4xx — target blocked the request✓Retry with novada_proxy_render or different country
TLS_ERRORTLS/SSL connection failed through proxy✓Retry with a different country parameter
TIMEOUTRequest exceeded timeout limit✓Increase timeout or retry
RATE_LIMITEDHTTP 429 — too many requests✓Wait 5s and retry
NETWORK_ERRORDNS failure — hostname not found✗Verify the URL is correct
SESSION_STICKINESS_FAILEDSame IP not maintained✓Retry verify_sticky: true to confirm
INVALID_INPUTBad parameter value✗Fix the parameter and retry
PROVIDER_NOT_CONFIGUREDMissing env vars✗Set credentials and restart MCP
UNKNOWN_ERRORUnexpected 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

ClientInstall method
Claude Codeclaude mcp add novada-proxy-mcp -e ... -- npx -y novada-proxy-mcp
CursorSettings -> MCP -> Add server -> npx -y novada-proxy-mcp
WindsurfMCP config -> npx -y novada-proxy-mcp
ClineMCP settings -> command: npx, args: ["-y", "novada-proxy-mcp"]
Continue.continue/config.json -> mcpServers
Smitherysmithery.ai/server/novada-proxy-mcp
Any MCP clientstdio transport / npx -y novada-proxy-mcp

Network

MetricValue
Residential IPs2,000,000+
Live nodes7,000+
Countries195+
Device typesAndroid, Windows, Mac
Uptime99.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 TypeTestsPassNotes
Residential119Wikipedia, Shopify, HackerNews, geo-targeting work. Sticky sessions require endpoint config.
ISP77All tools work including sticky sessions (session_verified: true).
Datacenter88Fast, cost-effective. Anti-bot sites (Amazon, CNN) may block datacenter IPs — use residential for those.
Error handling77All 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 CaseRecommended ProxyWhy
Anti-bot sites (Amazon, LinkedIn, CNN)ResidentialReal home IPs, hardest to detect
Fast bulk scrapingDatacenterLowest latency, cheapest per GB
Sticky sessions (login flows)ISP6-hour sticky, stable IPs
General scrapingAnyAll types handle most sites

Known Limitations

LimitationWorkaround
Datacenter IPs blocked on anti-bot sitesUse residential or ISP proxy type (NOVADA_PROXY_ZONE=res)
Proxy-side DNS errors surface as TLS_ERRORCheck 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 keySet NOVADA_BROWSER_WS env var — get it from novada.com dashboard
Heuristic extraction misses a fieldUse 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: support@novada.com
  • GitHub Issues: github.com/NovadaLabs/Novada-proxy/issues
  • Website: novada.com

License

MIT © Novada — see LICENSE



Novada Proxy(中文文档)

AI 智能体专属住宅代理 MCP — 支持任意供应商。

通过 200 万+ 真实家庭设备(Android 手机、Windows 电脑、Mac)路由 HTTP 请求,绕过反机器人系统,按国家/城市精准定位,跨请求保持同一 IP。

返回英文 10 个工具 5 个提示词 5 个资源 430 个测试

工具 · 提示词 · 资源 · 安装 · 智能体优先 · 供应商


支持 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://countries195+ 国家代码完整列表,含城市级定位
proxy://error-codes所有类型化错误码及恢复指令
proxy://workflows常用智能体工作流模式(爬取、研究、监控)
proxy://supported-fieldsnovada_proxy_extract 支持的所有提取字段及策略
proxy://cost-guide每个工具的额度消耗、缓存行为、成本优化技巧

快速决策指南

我想要...使用工具
抓取单个 URLnovada_proxy_fetch
同时抓取 2-20 个 URLnovada_proxy_batch_fetch
提取特定字段(标题、价格…)novada_proxy_extract 使用 fields
提取任意字段(Schema 模式)novada_proxy_extract 使用 schema
获取页面上的所有链接novada_proxy_map
爬取整个站点novada_proxy_crawl
研究某个主题novada_proxy_research
搜索 Googlenovada_proxy_search
渲染 JS 重型页面novada_proxy_render
跨请求保持同一 IPnovada_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 }
配置项说明
默认 TTL300 秒(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(下一步操作):

{
  "ok": false,
  "error": {
    "code": "BOT_DETECTION_SUSPECTED",
    "recoverable": true,
    "agent_instruction": "Try novada_proxy_render (real browser). Or retry with a different country/session_id."
  }
}
错误码含义可恢复
BOT_DETECTION_SUSPECTED被目标站点封锁(403)✓
TLS_ERRORTLS/SSL 连接失败✓
TIMEOUT请求超时✓
RATE_LIMITEDHTTP 429 限速✓
NETWORK_ERRORDNS 解析失败✗
INVALID_INPUT参数错误✗
PROVIDER_NOT_CONFIGURED缺少凭证✗

6. 批量并发抓取

novada_proxy_batch_fetch 内置信号量并发控制:

// 10 个 URL,concurrency=5,wall time = ~8.8s(串行估计 ~50s)
{
  "data": {
    "results": [
      { "url": "...", "ok": true, "cache_hit": false, "latency_ms": 1200 },
      { "url": "...", "ok": true, "cache_hit": true,  "latency_ms": 0 },
      { "url": "...", "ok": false, "error": { "code": "TLS_ERROR" } }
    ]
  },
  "meta": { "latency_ms": 8800, "quota": { "credits_estimated": 10 } }
}

7. 多供应商支持

供应商环境变量说明
Novada(推荐)NOVADA_PROXY_USER + NOVADA_PROXY_PASS最深度集成,含搜索 + 浏览器 API
BrightDataBRIGHTDATA_USER + BRIGHTDATA_PASS完整自动定位
SmartproxySMARTPROXY_USER + SMARTPROXY_PASS完整自动定位
OxylabsOXYLABS_USER + OXYLABS_PASS完整自动定位
通用 HTTPPROXY_URL=http://user:pass@host:port任意代理服务商

8. 渐进式降级(render_fallback)

novada_proxy_extract 支持自动升级到浏览器渲染:

代理抓取失败(TLS / Bot检测)
        │
        ▼ render_fallback=true
novada_proxy_render(真实 Chromium)
        │
        ▼
data.extracted_via = "render"  (agent 知道走了哪条路径)
data.fetch_warning = "Proxy fetch failed... escalated to render"

快速安装

# 核心(住宅代理抓取)
claude mcp add novada-proxy-mcp \
  -e NOVADA_PROXY_USER=你的用户名 \
  -e NOVADA_PROXY_PASS=你的密码 \
  -- npx -y novada-proxy-mcp

# 仅搜索
claude mcp add novada-proxy-mcp \
  -e NOVADA_API_KEY=你的_API_Key \
  -- npx -y novada-proxy-mcp

# 全功能(代理 + 搜索 + 浏览器渲染)
claude mcp add novada-proxy-mcp \
  -e NOVADA_PROXY_USER=你的用户名 \
  -e NOVADA_PROXY_PASS=你的密码 \
  -e NOVADA_API_KEY=你的_API_Key \
  -e NOVADA_BROWSER_WS=你的_Browser_WS_URL \
  -- npx -y novada-proxy-mcp

获取凭证:novada.com -> 仪表盘 -> 住宅代理 -> 端点生成器

Cursor / Windsurf / Cline 配置:

{
  "mcpServers": {
    "novada-proxy-mcp": {
      "command": "npx",
      "args": ["-y", "novada-proxy-mcp"],
      "env": {
        "NOVADA_PROXY_USER": "你的用户名",
        "NOVADA_PROXY_PASS": "你的密码"
      }
    }
  }
}

工具参数速查

novada_proxy_fetch

参数类型默认说明
urlstring必填目标 URL
countrystring—国家代码(US、DE、JP...)
citystring—城市(newyork、london...)
session_idstring—复用同一 IP(不含连字符,最多 64 字符)
formatstringmarkdownmarkdown(去 HTML)或 raw(原始 HTML)
timeoutnumber60超时秒数(1-120)

novada_proxy_batch_fetch

参数类型默认说明
urlsstring[]必填2-20 个 URL
concurrencynumber3并发数(1-5)
countrystring—对所有 URL 使用相同国家
formatstringmarkdownmarkdown 或 raw

novada_proxy_extract

参数类型默认说明
urlstring必填目标 URL
fieldsstring[]必填要提取的字段(title、price、description、rating...)
render_fallbackbooleanfalse代理失败时自动切换到浏览器渲染
countrystring—地理定向

novada_proxy_map

参数类型默认说明
urlstring必填起始 URL
limitnumber50最多返回 URL 数(10-200)
include_externalbooleanfalse包含站外链接

novada_proxy_session

参数类型默认说明
session_idstring必填会话 ID(不含连字符,最多 64 字符)
urlstring必填目标 URL
verify_stickybooleanfalse验证 IP 一致性(需额外 15-25 秒)
countrystring—国家代码

novada_proxy_search

参数类型默认说明
querystring必填搜索关键词
numnumber10结果数量(1-20)
countrystring—本地化结果(us、de、jp...)
languagestring—语言(en、zh、de...)

novada_proxy_render [BETA]

参数类型默认说明
urlstring必填目标 URL
formatstringmarkdownmarkdown · html · text
wait_forstring—等待 CSS 选择器后再提取(如 .product-title)
timeoutnumber60超时秒数(5-120)

novada_proxy_crawl

递归 BFS 爬取站点,从起始 URL 出发,按深度逐层发现链接,返回完整 URL 树及元数据。

参数类型默认说明
urlstring必填起始 URL
depthnumber2BFS 深度(1-5)
limitnumber50最大爬取页数(10-200)
include_contentbooleanfalse同时返回每个页面的内容
countrystring—地理定向所有请求
formatstringmarkdowninclude_content: true 时的内容格式
timeoutnumber60每页超时秒数

适用场景: 全站抓取、站点地图生成、内容索引 — 需要抓取多个页面时使用。

改用 novada_proxy_map 的情况: 只需要单页链接(一层深度)。Map 更快、更省额度。

组合使用: 将 data.urls[] 传入 novada_proxy_batch_fetch 并发抓取。

请求示例:

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

响应: data.pages[](url、depth、status_code、total_links),data.urls[](扁平数组,可直接传给 novada_proxy_batch_fetch)


novada_proxy_research

一键深度研究工具 — 搜索网络、抓取排名靠前的结果,返回含来源预览的结构化分析。智能体可对 findings 进行进一步综合分析。

参数类型默认说明
querystring必填研究问题或主题
depthstring"standard""quick"(3 个来源)、"standard"(5 个)、"deep"(10 个)
countrystring—本地化搜索结果
timeoutnumber60超时秒数

需要: NOVADA_API_KEY(Google 搜索)+ 代理凭证(抓取来源页面)

适用场景: 研究问题、主题调研、竞品分析、事实核查 — 需要一次调用获取多个来源内容时。

改用 novada_proxy_search 的情况: 只需要搜索结果 URL,不需要完整页面内容。

组合使用: 对 data.urls[] 中的特定 URL 调用 novada_proxy_fetch 进行深度阅读。

注意: findings_summary 是各来源内容的拼接预览 — 智能体应分析 findings[] 进行实质性综合。

请求示例:

{
  "query": "2026年最佳住宅代理服务商",
  "depth": "standard"
}

响应: data.findings[](title、url、snippet、content_preview),data.urls[](可链式传给其他工具),data.findings_summary


novada_proxy_extract — Schema 模式(LLM 提取)

除 fields(启发式提取)外,novada_proxy_extract 还支持 schema 参数,通过智能体自身的 LLM 提取任意字段 — 零额外 API 费用。

传入 schema 替代 fields,工具返回清洗后的页面内容 + 提取提示词 — 由你的智能体完成提取。

参数类型默认说明
urlstring必填目标 URL
schemaobject—键 = 字段名,值 = 字段描述。替代 fields 使用。
render_fallbackbooleanfalse代理失败时自动切换到浏览器渲染
countrystring—地理定向
timeoutnumber60超时秒数

请求示例:

{
  "url": "https://example.com/product",
  "schema": {
    "product_name": "完整的产品名称",
    "price": "当前价格(含货币符号)",
    "warranty": "保修条款和期限",
    "return_policy": "退货政策摘要"
  }
}

响应: data.mode = "llm_extract",data.content(清洗后的 Markdown 内容),data.extraction_prompt(供智能体遵循并提取字段的指令)

安全限制: Schema 键名只能包含字母、数字、下划线(a-z、0-9、_),最多 50 字符;值最多 200 字符。


使用场景

AI 智能体需要:

  • 抓取电商网站(Amazon、eBay、Walmart)不被封锁
  • 跨国家监控价格变动
  • 访问 195+ 国家的地区限制内容
  • 对 Cloudflare/Akamai 保护站点进行竞争情报收集
  • 执行多步登录流程并保持同一 IP
  • 渲染无真实浏览器就返回空白的 JS 页面
  • Google 搜索返回结构化 JSON 结果

开发者构建:

  • AI 驱动的网页研究工具
  • 价格比较智能体
  • 全站内容爬取管道
  • SEO 监控仪表盘
  • 市场调研自动化

已验证可用

电商: Amazon、eBay、Walmart、Etsy、Shopify
职业网络: LinkedIn
反机器人保护: Cloudflare 站点、Akamai、DataDome
新闻内容: HackerNews、Reddit、BBC、CNN、NYTimes
科技: GitHub、Wikipedia、Stack Overflow、IMDB


反馈与支持

  • 邮箱: support@novada.com
  • GitHub Issues: github.com/NovadaLabs/Novada-proxy/issues
  • 官网: novada.com

许可证

MIT © Novada

Featured
CodeRabbit
CodeRabbit
AI writes the code. CodeRabbit catches the slop.
Try For Free →
Keep your Mac awake
Keep your Mac awake
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Context.devContext.dev
Context.dev
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Make your agent a DeFi expert
Make your agent a DeFi expert
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make money from your Skills
Make money from your Skills
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
AppSignal
AppSignal
Monitor with ease. Code with confidence.
Start Free Trial →

Configuration

NOVADA_PROXY_USERsecret

Novada residential proxy username

NOVADA_PROXY_PASSsecret

Novada residential proxy password

NOVADA_API_KEYsecret

Novada Scraper API key for search tool

NOVADA_BROWSER_WSsecret

Novada Browser API WebSocket URL for render tool

BRIGHTDATA_USERsecret

BrightData full username including zone

BRIGHTDATA_PASSsecret

BrightData proxy password

SMARTPROXY_USERsecret

Smartproxy username

SMARTPROXY_PASSsecret

Smartproxy password

OXYLABS_USERsecret

Oxylabs username

OXYLABS_PASSsecret

Oxylabs password

PROXY_URLsecret

Generic HTTP proxy URL (http://user:pass@host:port)

Registryactive
Packagebestproxy4agents-mcp
TransportSTDIO
AuthRequired
UpdatedApr 10, 2026
View on GitHub