Search the web via 5 engines (Google, Bing, DuckDuckGo, Yahoo, Yandex). Returns titles, URLs, snippets — reranked by relevance. For complex questions needing multiple sources, use novada_research instead (it's faster and more thorough).

Use for: Current events, finding URLs, fact lookup, competitive research. Set enrich_top=true to auto-extract the #1 result. Not for: Reading a known URL (novada_extract), multi-source report (novada_research). Tip: engine='duckduckgo' is 3x faster than Google and works for most queries.

Extract clean content from any URL. Handles Cloudflare, DataDome, Kasada automatically via auto-escalation (static → JS render → Browser CDP). Batch mode: pass url as array for up to 10 pages in parallel.

Use for: Reading pages, batch-extracting search results, pulling structured fields (price, author, date). Works on anti-bot pages automatically. Not for: URL discovery (novada_map), multi-page crawl (novada_crawl), platform data like Amazon/LinkedIn (novada_scrape is richer). Key rule: Leave render="auto" (default). Only set render="render" for known JS-heavy SPAs. Auto mode is 15-100x faster on static sites.

Use when you need content from multiple pages of a site and don't have the URLs yet. Crawls BFS or DFS up to 20 pages, extracts content from each. Use select_paths regex to target specific sections (e.g. "/docs/api/.*").

Best for: Doc site ingestion, competitive content analysis, building knowledge bases from a domain. Not for: A single page (use novada_extract), URL discovery without content extraction (use novada_map — much faster).

Common mistakes:

• Do NOT set max_pages > 10 for large sites — crawl time scales linearly (~1.4s/page). At max_pages=20, expect 28s minimum.

• Do NOT use novada_crawl to fetch one page — use novada_extract which is faster and simpler.

• Use select_paths to restrict to relevant URL patterns before setting max_pages high.

When to use:

• You need content from multiple pages on one domain (e.g., all /docs/* pages).

• You need BFS discovery of related content under a path prefix.

Not for:

• Single-URL extraction — use novada_extract.

• Finding all URLs on a site without downloading content — use novada_map.

The most powerful research tool in any MCP server. One call → 3-10 parallel searches across Google/Bing/DuckDuckGo → dedup → extract full content from top 5 sources → synthesized cited report. No other MCP server can do this.

Use for: Any complex question needing multiple sources. Comparative analysis, market research, technical deep dives, competitive intelligence. Replaces 5-10 manual search+extract calls. Not for: Single fact lookup (novada_search) or reading one URL (novada_extract). Depth: "quick" (3 queries), "deep" (5-6), "comprehensive" (8-10), "auto" (default). Key advantage: Agents call this ONCE instead of orchestrating search→extract→synthesize manually. Saves tokens, time, and complexity.

Use when you need to know what URLs exist on a site before deciding what to read. Tries sitemap.xml first (fast), falls back to BFS crawl. Returns URL list only — no content.

Best for: Site structure discovery, finding the correct subpage URL when you extracted the wrong page. Not for: Reading page content (follow with novada_extract or novada_crawl). Note: Limited results on JavaScript SPAs — will flag this in output.

Use when you need structured data from a specific platform — not raw HTML, but clean tabular records. Supports 129 platforms: Amazon, Reddit, TikTok, LinkedIn, Google Shopping, Glassdoor, GitHub, Zillow, Airbnb, and more.

Best for: E-commerce product data, social posts/comments, job listings, reviews, real estate, market data. Not for: General web pages (use novada_extract), unknown domains not in the platform list (use novada_crawl). Output formats: "markdown" (default, agent-optimized table), "json" (structured, for programmatic use). Example: platform="amazon.com", operation="amazon_product_keywords", params={keyword:"iphone 16", num:5} Discover platforms: Read the novada://scraper-platforms MCP resource for the complete platform list with operation IDs and required params.

Use when you need to route your own HTTP requests through residential or mobile IPs — for geo-targeting, IP rotation, or bypassing IP-based rate limits. Returns proxy URL, shell export commands, or curl --proxy flag.

Best for: When you need a specific country/city IP, sticky sessions for multi-step workflows, or testing geo-restricted content. Not for: Web page extraction (use novada_extract — proxy is automatic), web search (use novada_search). Formats: "url" for Node.js/Python, "env" for shell variables, "curl" for CLI requests. Note: Requires NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars. Specialized tools: For specific proxy types, use novada_proxy_residential, novada_proxy_isp, novada_proxy_datacenter, novada_proxy_mobile, novada_proxy_static, or novada_proxy_dedicated.

Route requests through residential IPs — real home ISP addresses from a 100M+ IP pool. Best anti-bot bypass for geo-restricted or protected pages.

Best for: Anti-bot protected pages, geo-restricted content, platforms that block datacenter IPs. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), country (ISO 2-letter), city (optional, requires country), session_id (optional for sticky IP). Formats: "url", "env", "curl". agent_instruction: Best for geo-restricted content. Use country param for targeting. Strongest anti-bot bypass — escalate here from isp/datacenter when blocked. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Route requests through ISP-assigned IPs that look like real home users — ideal for social media and ecommerce platforms.

Best for: Social media scraping, ecommerce platforms, any site distinguishing home users from datacenter IPs. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), country (ISO 2-letter, optional), session_id (optional for sticky IP). Formats: "url", "env", "curl". agent_instruction: ISP proxies look like real home users. Best for social/ecommerce. Escalate to novada_proxy_residential for stronger anti-bot. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Route requests through datacenter IPs — fastest and most cost-effective option for high-volume scraping of targets without aggressive anti-bot.

Best for: APIs, public data feeds, high-volume scraping of non-protected targets. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), country (ISO 2-letter, optional), session_id (optional for sticky IP). Formats: "url", "env", "curl". agent_instruction: Fastest proxies. Best for high-volume, non-anti-bot targets. Escalate to isp → residential if blocked. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Route requests through 4G/5G mobile IPs — real mobile device IPs ideal for mobile-targeted content and apps.

Best for: Mobile-targeted content, app APIs, platforms serving different content to mobile vs desktop. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), country (ISO 2-letter, optional), carrier (optional, e.g. 'verizon'), session_id (optional for sticky IP). Formats: "url", "env", "curl". agent_instruction: Mobile IPs. Best for mobile-targeted content and apps. Pair with mobile User-Agent for full simulation. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Route requests through a dedicated static ISP IP that never changes — same IP every request for a given session_id + country.

Best for: Account management, login-dependent workflows, platforms that flag IP changes as suspicious. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), country (ISO 2-letter, REQUIRED), session_id (REQUIRED — determines your dedicated IP). Formats: "url", "env", "curl". agent_instruction: Same IP every request. Best for accounts requiring consistent identity. Keep the same session_id for the entire account lifecycle. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Route requests through an exclusive datacenter IP not shared with any other user — clean reputation, zero contamination risk.

Best for: High-trust platforms, workflows needing a pristine IP with no negative history. Not for: novada_extract or novada_crawl — they handle proxy routing internally. These credentials are for your own HTTP clients (curl, requests, axios). Params: url (optional), session_id (REQUIRED — maps to your exclusive dedicated IP). Formats: "url", "env", "curl". agent_instruction: Exclusive datacenter IP. Best for high-trust platforms. No other user shares this IP. For human-like IP appearance, use novada_proxy_residential instead. Requires: NOVADA_PROXY_USER, NOVADA_PROXY_PASS, NOVADA_PROXY_ENDPOINT env vars.

Use when you have a factual claim and need to check if it's supported by web sources. Runs 3 parallel searches (supporting, skeptical, fact-check angles) and returns a verdict: supported / unsupported / contested / insufficient_data.

Best for: Checking claims before citing them, cross-validating research findings, detecting misinformation. Not for: Open-ended questions (use novada_research), reading a specific URL (use novada_extract). Note: Verdict is signal-based (search balance), not a definitive ruling. Confidence 0–100 indicates certainty.

Use when you need the raw rendered HTML of a blocked or JS-heavy page. Forces JS rendering via Web Unblocker or Browser API. Returns raw HTML, not cleaned text.

Best for: When you need raw HTML (not cleaned text) for custom DOM parsing. When novada_extract with render="render" still fails. Returns the full JS-rendered HTML source. Tip: For most anti-bot pages, try novada_extract with render="render" first — it returns clean text. Use novada_unblock when you specifically need the raw HTML source. Not for: Reading cleaned text (use novada_extract with render="render"), structured platform data (use novada_scrape). Methods: "render" (Web Unblocker, faster/cheaper), "browser" (full Chromium CDP, handles complex SPAs). Wait hint: Use wait_for to specify a CSS selector to wait for before capturing HTML. Note: wait_ms, block_resources, auto_runs are accepted but not yet implemented — they have no effect in the current version.

Common mistakes:

• This tool returns RAW HTML, not parsed/cleaned text. Passing the output directly to an LLM expecting markdown will produce garbled, token-heavy responses.

• For extracted content from bot-protected pages, use novada_extract (it calls the unblocker internally with render='render').

• Do not use novada_unblock for simple static pages — it adds 9-16 seconds of latency vs 112ms for novada_extract.

When to use:

• You need the original DOM structure for CSS selector parsing in a processing pipeline.

• You are feeding the HTML into a downstream parser, not directly to an LLM.

• You need raw access to a page's complete HTML before novada_extract's content selection.

Not for:

• Getting readable content from protected pages — use novada_extract with render='render'.

Use when you need to interact with a web page — click buttons, fill forms, scroll, take screenshots, or execute JavaScript. Chain multiple actions in one call for efficiency.

Best for: Login flows, paginated content, interactive SPAs, form submission, visual verification, scraping behind user interactions. Not for: Simple page reading (use novada_extract), structured data (use novada_scrape), raw HTML (use novada_unblock). Actions: navigate, click, type, screenshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select — up to 20 per call. Sessions: Pass session_id to maintain state (cookies, login) across multiple calls. Sessions expire after 10 min of inactivity. Use close_session to release early. Requires: NOVADA_BROWSER_WS environment variable. Platform note: TikTok is geo-restricted in some regions — pass country="us" in actions that support it. Use wait with domcontentloaded (never networkidle) for SPAs. Constraint: close_session and list_sessions must be the only action in the call — they cannot be combined with other actions.

Check which Novada API products are active on your API key.

Best for: First-time setup, diagnosing why a tool is failing, confirming your account has the right products activated. Returns: Status table for Search, Extract, Scraper API, Proxy, and Browser API — with activation links for anything not yet enabled.

Extended health check that tests ALL Novada product endpoints in parallel and returns detailed per-product status.

agent_instruction: Call this when novada_health shows an issue and you need per-product details, or when setting up Novada for the first time and want to confirm every product is reachable. Returns: Per-product table — product | status | latency | notes — covering Search, Extract, Scraper, Proxy, Browser, and Unblock APIs. Degraded mode: If one product probe fails, all others still return — never hard-fails. Activation links: Any PRODUCT_UNAVAILABLE result includes a direct link to activate that product on your dashboard. Difference from novada_health: This tool tests 6 products (vs 5), includes the Unblock API probe, and provides richer notes per product.

List all available Novada tools with name, description, category, and status (active/todo).

agent_instruction: Call this first to see all available Novada tools and capabilities — especially useful when starting a new task and you need to find the right tool. Returns: Markdown table grouped by category — Content Retrieval, Scraping & Verification, Proxy, Browser & Rendering, Health & Discovery, Auth. Filter: Pass category to narrow to a specific group (e.g. category="Proxy" to see all proxy tools). Status legend: active = available now; todo = planned but not yet implemented.

Submit an async scraping task for any URL. Returns a task_id — use novada_scraper_status to poll progress, then novada_scraper_result to retrieve data.

Best for: Scraping URLs that require async processing (JS-heavy pages, rate-limited targets, long-running extractions). Workflow: submit → poll status → retrieve result. Three separate calls. Required: url (the page to scrape). Optional: scraper_type (default 'universal'), country (2-letter ISO code). Next step: After calling this tool, use novada_scraper_status with the returned task_id to check progress. Note: If the endpoint returns a placeholder task_id, contact Novada support at support@novada.com to confirm scraper_type availability. Alternative: For 129 supported platforms (Amazon, Reddit, TikTok), use novada_scrape instead — it's synchronous and returns results directly.

Check the status of an async scraping task by task_id. Returns: pending, running, complete, or failed.

Required: task_id (from novada_scraper_submit). Pending/running: Retry in 5–10 seconds. Use exponential backoff (5s → 10s → 20s → 40s). Complete: Call novada_scraper_result with the same task_id to retrieve formatted data. Failed: Re-submit with novada_scraper_submit, or use novada_extract / novada_unblock as alternatives. agent_instruction: Each response includes the next action to take — always follow it.

Retrieve the completed result of an async scraping task by task_id.

Required: task_id (from novada_scraper_submit). Confirm status='complete' with novada_scraper_status first. Formats: 'markdown' (default — human-readable table), 'json' (structured array for programmatic use), 'raw' (unprocessed API response). agent_instruction: Call novada_scraper_status first to confirm task is complete before calling this tool. Calling this on a pending task returns a not_ready response. Note: If result is unavailable, check novada_scraper_status and contact Novada support at support@novada.com with the task_id if the endpoint is returning errors.

Execute multi-step browser automation with Novada's cloud browser. Use for JS-heavy sites, login flows, or multi-page sequences.

Best for: Automating sequences of clicks, form fills, scrolls, and screenshots on a single page or across a multi-step flow. Maintains session state across calls when session_id is provided. Actions: click, scroll, wait, type, screenshot — up to 20 per call. Sessions: Pass session_id to reuse the same browser instance across calls (preserves cookies, login state). Sessions expire after 10 minutes of inactivity. Fallback: If this tool fails, use novada_browser — it uses CDP directly and supports more action types (navigate, aria_snapshot, evaluate, hover, press_key, select). Not for: Single URL reading without interaction (use novada_extract or novada_unblock), structured platform data (use novada_scrape).

Use when you need to check how AI models (ChatGPT, Perplexity, Grok, Claude, Gemini) reference a brand or product. Searches each AI platform's indexed content for brand mentions, analyzes sentiment, extracts claims, and identifies competitor mentions.

Best for: Brand monitoring across AI search engines, competitive positioning analysis, detecting how AI recommends or compares your product. Not for: General web search (use novada_search), real-time social monitoring (use novada_scrape with twitter/reddit). Output: Per-model sentiment (positive/neutral/negative), key claims, competitor mentions, source URLs. Models supported: chatgpt, perplexity, grok, claude, gemini. Default checks: chatgpt, perplexity, grok.

Detect changes on a web page over time. Extracts content, computes a hash, compares with previous check. Returns changed/unchanged + field-level diffs.

Use for: E-commerce price monitoring, stock availability tracking, content change detection, competitive pricing alerts. How: First call = baseline. Subsequent calls compare against baseline and report changes. Pass fields=["price","availability"] for field-level diffs with % change. Session-scoped: State lives in memory for the MCP session duration. Not persisted across restarts. Not for: One-time extraction (novada_extract), full crawl (novada_crawl).

Check environment configuration and get step-by-step setup instructions. Safe to call before NOVADA_API_KEY is configured.

Use for: First-time setup, diagnosing missing credentials, getting exact config snippets for Claude Code / Claude Desktop / Cursor / VS Code / Windsurf. Output: Status of all env vars (NOVADA_API_KEY, NOVADA_BROWSER_WS, NOVADA_PROXY_*), setup commands for all MCP clients, and which tools are currently active. No auth required: This tool works even when NOVADA_API_KEY is not set.

Read the master Novada wallet balance (currency). Wraps developer-api POST /v1/wallet/balance.

Best for: Confirming credit available before launching billable scraper/proxy jobs. Not for: Per-product MB/quota — use novada_plan_balance_all for residential/isp/mobile/datacenter/static/capture sub-balances. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Paginated wallet transaction / usage history. Wraps developer-api POST /v1/wallet/usage_record.

Best for: Auditing recent spend, exporting billing rows. Not for: Aggregate by-product spend (use novada_traffic_daily) or current balances (use novada_plan_balance_all). Params: start_time/end_time (YYYY-MM-DD, optional — server default ~30d), page, page_size (max 200). Tool emits both start_time AND server's typo'd strat_time for forward-compat. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

⚠️ WRITE — Create a proxy sub-account. Two-step confirm gate.

Behavior: Without confirm: true the tool returns a confirmation_required JSON preview (password masked) and DOES NOT hit the API. Show preview to the human user; only re-call with confirm: true after explicit human approval.

Best for: Provisioning a team-member or per-project sub-account against your master plan. Params: product ("1"=Residential, "2"=Rotating ISP, "3"=Rotating Datacenter, "4"=Unlimited, "7"=Unblocker, "9"=Mobile), account (3-64, [a-zA-Z0-9_-]), password (8-64), status ("1" active default | "-3" disabled), remark?, limit_flow? (GB cap as string), confirm. Wire format: multipart/form-data (per developer-api spec). Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

List proxy sub-accounts. Wraps developer-api POST /v1/proxy_account/list.

Best for: Auditing sub-accounts, finding account names before rotating credentials. Params: product (REQUIRED — same codes as create), page, limit (max 200), status? ("1"|"-3"), account? (exact-match filter). Wire format: multipart/form-data. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Aggregate daily traffic consumption across all 5 Novada proxy products in PARALLEL. Fans out to residential/isp/mobile/datacenter/static *_flow/consume_log endpoints.

Best for: "How much have we spent on proxies in the last N days?" / dashboarding spend per product. Returns: total_mb_across_products + per_product[].raw (server's day-by-day breakdown) + per-product error flags. Partial failures (e.g. a product not provisioned) do NOT block successful ones. Params: start_time/end_time (YYYY-MM-DD, optional — emits both start_time AND typo'd strat_time), products (optional subset). Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Per-product balance across all 6 Novada flow products in PARALLEL (residential/isp/mobile/datacenter/static/capture).

Best for: "Do we have quota left on product X?" / pre-flight check before launching a scrape job. Not for: Master wallet currency balance — use novada_wallet_balance. Returns: per_product[].balance (raw server response — typical fields: balance_mb, remaining_mb, plan_mb). Partial failures isolated per product. Params: products (optional subset). Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Paginated capture-task logs. Wraps developer-api POST /v1/capture/logs.

Best for: Auditing what was captured, debugging failed capture jobs. Params: start_time/end_time (YYYY-MM-DD, optional — emits both start_time AND strat_time), page, page_size (max 200), status filter. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Single-call account dashboard. Calls wallet_balance + plan_balance_all + capture_logs (last 5 rows) in PARALLEL and returns a unified headline + per-section detail.

Best for: "What's my Novada account status?" / "How much do I have left?" / one-shot health snapshot. Returns: headline (one-line human summary), sections.{wallet,plans,capture_recent} (raw per-tool output), agent_instruction (next-step hint — e.g. "all plans expired, buy at dashboard"). Why not 3 calls: Halves round-trip cost for the most common account-status query. Plans section already includes derived expired/expires_at_human and unavailable_products so agents don't compute timestamps. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).