Novada-MCP

Single-call account & billing dashboard. Composes wallet balance, plan balances, capture logs, and health entitlements based on the section param.

Best for: "What's my Novada account status?" / "How much do I have left?" / one-shot health snapshot. section="summary" (default): Full dashboard — wallet balance + plan quotas + recent capture logs + product entitlements (proxy/browser/wallet-funded services). This is what novada_account_summary + novada_health combined. section="balance": Master wallet currency balance. section="usage": Paginated wallet transaction / usage history. Pass start_time/end_time/page/page_size. section="plans": Per-product plan balances (residential/isp/mobile/datacenter/static/capture). Pass products[] to filter. section="traffic": Daily proxy traffic consumption across products. Pass start_time/end_time/products[]. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY). Aliases (backward compat): novada_wallet_balance, novada_wallet_usage_record, novada_plan_balance_all, novada_traffic_daily, novada_capture_logs, novada_account_summary, novada_health, novada_health_all — all route here.

Search PUBLIC indexed pages on AI-company domains for brand mentions and sentiment — this is NOT page-change monitoring (that's novada_monitor) and does NOT query live AI models.

Searches indexed pages on chatgpt.com/openai.com, perplexity.ai, anthropic.com, and similar domains for public mentions of a brand or product. Returns per-source mention counts, sentiment signals, and competitor mentions. A brand not discussed on those indexed domains will show few/zero mentions — that reflects indexed-page coverage, not the models' actual behavior.

How it works: For each selected domain group, executes a Google search scoped to that domain (e.g. site:openai.com "brandname") and analyzes the returned page snippets for sentiment, claims, and competitor co-mentions. Best for: Checking whether a brand appears on AI-company public docs/blogs/changelogs; competitive presence on indexed pages of AI platforms. Not for: Finding out how ChatGPT/Perplexity/Claude actually answer questions about your brand (those are live model responses, not indexed pages); general web search (use novada_search); real-time social monitoring (use novada_scrape with twitter/reddit). Output: Per-domain sentiment (positive/neutral/negative), key claims from indexed snippets, competitor mentions, source URLs. Domains searched: chatgpt.com+openai.com, perplexity.ai, grok.com+x.com/i/grok, claude.ai+anthropic.com, gemini.google.com. Default: chatgpt, perplexity, grok.

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_extract with format="html"). Actions: navigate, click, type, screenshot, snapshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select — up to 20 per call. snapshot = full DOM text; aria_snapshot = smaller semantic tree (prefer aria_snapshot for most extraction tasks). Sessions: Pass session_id to reuse the same browser page (cookies, login) across calls. Persistent cross-call sessions are reliable only on the local/long-lived server; on the hosted serverless endpoint treat each call as one-shot (a session_id may not survive between calls). Use close_session to release early. Auth: NOVADA_API_KEY (auto-provisions Browser API credentials). NOVADA_BROWSER_WS is optional — set it to override auto-provision. Platform note: Use wait with domcontentloaded (never networkidle) for SPAs. (The country param is accepted but NOT yet applied to the browser exit node — do not rely on it for geo-routing.) Constraint: close_session and list_sessions must be the only action in the call — they cannot be combined with other actions.

Simplified browser automation with a 5-action flow API (click, scroll, wait, type, screenshot). Use only if you specifically need this simplified flow interface or novada_browser is unavailable.

novada_browser is the primary, more capable tool — it provides full CDP access with 12 automation action types (navigate, click, type, screenshot, snapshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select) plus 2 session-management actions (close_session, list_sessions). Prefer novada_browser for all new browser automation. Use novada_browser_flow when: you specifically need the simplified flow API, or you have an existing workflow built around it. 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. Not for: Single URL reading without interaction (use novada_extract), structured platform data (use novada_scrape).

Get or reset the Capture API key for the account. Wraps POST /v1/capture/get_apikey and /v1/capture/reset_apikey.

Actions: "get" = retrieve the current capture/scraper API key (read-only). "reset" = regenerate the key — DESTRUCTIVE, invalidates the old key, requires confirm:true. Behavior: Without confirm:true on "reset", returns a warning preview and does NOT call the API. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

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

IMPORTANT — wrong tool for whole-site jobs: If you need to copy more than ~20 pages or want an entire docs site / knowledge base on disk, use novada_site_copy instead (up to 1000 pages, manifest output, streams files to disk). novada_crawl hard-caps at 20 pages and returns bodies inline — it will silently hit that cap on large sites.

Best for: Competitive content analysis, extracting a handful of related pages inline (returns page bodies directly). Not for: A single page (use novada_extract), URL discovery without content extraction (use novada_map — much faster), copying an entire site to disk (use novada_site_copy — it handles hundreds of pages and writes files).

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 a small set of related pages on one domain (e.g., all /docs/* pages, up to 20).
• You need BFS discovery of related content under a path prefix and want bodies inline.

Not for:

• Single-URL extraction — use novada_extract.
• Finding all URLs on a site without downloading content — use novada_map.
• Copying a whole docs site or knowledge base to disk — use novada_site_copy (handles hundreds of pages, returns a manifest).

Rendering: The render param defaults to "auto" (tries static first, escalates to JS rendering on detection) — it is not static-only.

List all available Novada tools with name, description, category, and status.

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, Account & Billing, Health & Discovery. Filter: Pass category to narrow to a specific group (e.g. category="Proxy" to see all proxy tools). Status legend: active = available now. Output also includes server_version (the running package version).

KEY FACT: ONE API KEY COVERS ALL PRODUCTS. NOVADA_API_KEY authenticates search, extract, research, crawl, scrape, unblock, and proxy auto-provisioning. No separate keys needed for any product. NOVADA_BROWSER_WS and NOVADA_PROXY_ENDPOINT unlock additional capabilities but require no extra API key. If a tool fails, call novada_account (section="summary") to check your balance, plans, and entitlements.

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

CRITICAL — Format Selection:

• format="markdown" (default): full-page content for reading/analysis. Best for articles, docs.
• format="json": structured object. Key fields: url, title, content, quality, links, structured_data, fields, hints, mode, fetched_at. Use fields=["price","title"] to populate the fields key — this is the primary reason to choose format="json".
• format="html": raw HTML source (truncated at 100K chars by default; pass max_chars to adjust). Best for debugging or custom DOM parsing.
• clean=true: strip nav/sidebar, return main content only (~15K chars vs ~100K full page).

Common mistake: using markdown when you need specific data — use format="json" + fields=["price","title"] instead.

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. By default returns full page content for maximum information. Add clean=true to extract only the main article body (strips nav/footer/ads).

Geo-routing: Pass country="de" (ISO 2-letter) to route render fetches through an exit IP in that country — useful for localized pricing, geo-restricted content, or comparing the same page across countries. Results auto-saved: Every extraction saves to ~/Downloads/novada-mcp/YYYY-MM-DD/ automatically. File path shown at the top of each response. Project grouping: Pass project="my-project" to group all outputs in a subfolder (e.g. ~/Downloads/novada-mcp/2026-06-26/my-project/). Useful for multi-step research tasks.

Manage IP whitelist for proxy products. Supports add/list/delete/remark for Residential (1), Unlimited (4), and Static ISP (5) products.

Actions: "add" (WRITE — requires confirm), "list" (read-only), "del" (WRITE — requires confirm), "remark" (update note on entry). Required: action, product (1=Residential, 4=Unlimited, 5=Static ISP). Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

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. Hard cap: 100 URLs.

Best for: Site structure discovery, finding the correct subpage URL when you extracted the wrong page, pre-flight before novada_crawl or novada_extract. Not for: Reading page content (follow with novada_extract or novada_crawl). Copying an entire site to disk (use novada_site_copy — it handles hundreds of pages). Note: Limited results on JavaScript SPAs — will flag this in output.

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. Not for: One-time extraction (novada_extract), full crawl (novada_crawl).

⚠️ Hosted endpoint (mcp.novada.com) limitation: Baselines do NOT survive between calls on the hosted serverless endpoint — each invocation lands on a cold function with no prior state, so change detection will always return baseline_recorded. For real change detection you must run the local server (npx novada-mcp, a long-lived process) or schedule calls from your own job runner and diff externally. This is a known interim limitation until persistent KV storage ships.

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. Requires: NOVADA_PROXY_ENDPOINT env var. NOVADA_PROXY_USER/PASS are auto-fetched from your account using NOVADA_API_KEY if not explicitly set.

Proxy type guide (pass as type param):

• residential — strongest anti-bot bypass, real home ISP IPs, best for geo-restricted / protected pages; escalate HERE when blocked
• isp — looks like a home user (ISP-assigned), best for social media / ecommerce; note: ignores country param
• datacenter — fastest and cheapest, best for non-anti-bot targets and high-volume scraping
• mobile — 4G/5G device IPs, best for mobile-targeted content and app APIs
• static — same dedicated ISP IP every request (requires session_id + country), best for account-management workflows
• dedicated — exclusive clean datacenter IP not shared with others (requires session_id), best for high-trust platforms

Escalation path when blocked: datacenter → isp → residential

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

One call → 3-10 parallel searches across Google/Bing/DuckDuckGo → dedup → extract full content from top sources → returns CITED SOURCE MATERIAL (numbered source sections), not a written answer. Extractive, not generative: it gathers and ranks the most relevant passages; YOU compose the final answer from them.

Use for: Any complex question where you want relevant passages from ≥3 independent sources gathered in one call. Comparative analysis, market research, technical deep dives, competitive intelligence. Replaces 5-10 manual search+extract calls. Not for: Single fact lookup or finding one URL — use novada_search for that (faster, cheaper). Reading a known URL — use novada_extract. A finished prose report — this returns source material, you write the answer. Rule of thumb: If the answer could fit in one search result snippet, use novada_search. If you need source material pulled from multiple pages to reason over, use novada_research. Depth: "quick" (3 queries), "deep" (6), "comprehensive" (8-9), "auto" (default: picks quick or deep by question length — never comprehensive). Key advantage: Agents call this ONCE instead of orchestrating search→extract manually. Saves tokens, time, and complexity. Project grouping: Pass project="my-project" to group all outputs in a subfolder (e.g. ~/Downloads/novada-mcp/2026-06-26/my-project/). Useful for multi-step research tasks. Recency: Supports time_range ("day"|"week"|"month"|"year"), start_date, and end_date (ISO YYYY-MM-DD) for recency-constrained research — all are propagated to every internal search call.

Use when you need structured data from a specific platform — not raw HTML, but clean tabular records. Supports 16 platforms (~87 operations): Amazon, Walmart, SHEIN, Google (incl. Shopping), Bing, DuckDuckGo, Yandex, X/Twitter, TikTok, Instagram, Facebook, YouTube, LinkedIn, GitHub, ChatGPT, Perplexity.

Best for: E-commerce product data, social posts/comments, job listings, reviews, real estate, market data. Not for: General web pages not in the platform list — use novada_extract for arbitrary URLs instead. Output formats: "markdown" (default, agent-optimized table), "json" (structured records array returned inside a "## Scrape Results" wrapper — a fenced json block, not a bare object), "toon" (token-optimized pipe-separated format — 40-65% smaller than JSON/markdown, best for large result sets in context-constrained situations), "csv" (inline CSV text), "excel" (inline .xlsx base64), "html" (inline HTML table). Example: platform="amazon.com", operation="amazon_product_keywords", params={keyword:"iphone 16", num:5} Amazon price fields: trust final_price/price (check _price_source); initial_price and buybox_prices.final_price are frequently 0 by design, not a bug; buybox_prices.unit_price is raw upstream per-unit data and may be empty/inconsistent — never treat it as the listing price. Discover platforms: Read the novada://scraper-platforms MCP resource for the complete platform list with operation IDs and required params. Resume slow-platform scrapes: Pass task_id from a previous call that returned status:processing to fetch its result without submitting a new billable task. platform and operation are still required (display only when resuming). Project grouping: Pass project="my-project" to group all outputs in a subfolder (e.g. ~/Downloads/novada-mcp/2026-06-26/my-project/). Useful for multi-step research tasks.

Extract structured Amazon data — product details, reviews, seller info, bestseller lists, and category/brand listings — through an Amazon-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="amazon.com".

Use when: "get the price/rating/title for Amazon ASIN B0...", "pull the reviews for this Amazon product URL", "search Amazon for <keyword> with price and rating", "who is this Amazon seller", "what's in this Amazon Best Sellers list". Not for: Any other platform — use novada_scrape with the target platform's domain instead (e.g. platform="walmart.com"). A general Google/web search — use novada_search. Reading one arbitrary URL's raw content — use novada_extract. Returns: Structured product/review/seller records (title, price, rating, asin, availability, etc.) in the chosen format — same rendering as novada_scrape (markdown/json/csv/excel/html/toon). Operations: 10 verified-working Amazon operations (see the operation param's description for the exact params keys each needs). 3 known backend-broken Amazon operations are intentionally NOT in this enum — this tool rejects them before any backend call, unlike novada_scrape(platform="amazon.com", ...), which still forwards them with a warning.

Extract structured Bing SERP data — organic web search results, video results, news results, and shopping listings — through a Bing-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="bing.com". Bing is NOT a selectable engine on novada_search — this is the only intentional way to query Bing specifically.

Use when: "get the raw Bing search results (titles, links, ranks) for <query>", "find Bing video results for <query>", "find Bing news results for <query>, sorted by date", "search Bing Shopping for <keyword>". Not for: A general question that just needs an answer or a few good links — use novada_search — google/duckduckgo/yandex only (Bing is not selectable there); ranked, reranked, answer-oriented, and cheaper than a raw-SERP scrape. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content (not a search results page) — use novada_extract. A different platform's structured data (Amazon, LinkedIn, TikTok, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured SERP records per operation — organic results (title/url/snippet/rank), video results, news results (with date), and shopping listings (price/rating) — in the chosen format (markdown/json/csv/excel/html/toon), same rendering as novada_scrape. Operations: 4 verified-working Bing operations: web search, videos, news, and shopping (see the operation param's description for the exact params keys each needs). Every bing.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured DuckDuckGo web search SERP data through a DuckDuckGo-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="duckduckgo.com". Returns the raw organic-results SERP, with region/time/adult-content filters novada_search does not expose, not a generated answer.

Use when: "get the raw DuckDuckGo search results (titles, links, ranks) for <query>", "search DuckDuckGo restricted to a specific region (params.kl) or time range (params.df)", "compare DuckDuckGo's ranking for <query> against another engine's raw SERP". Not for: A general question that just needs an answer or a few good links — use novada_search with engine="duckduckgo" — same engine, but ranked/reranked and answer-oriented instead of a raw SERP dump. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content (not a search results page) — use novada_extract. A different platform's structured data (Amazon, LinkedIn, TikTok, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured organic-result SERP records (title/url/snippet/rank) in the chosen format (markdown/json/csv/excel/html/toon), same rendering as novada_scrape. Operations: 1 verified-working DuckDuckGo operation (web search — see the operation param's description for the exact params keys it needs). The single duckduckgo.com catalog operation is currently status:"ok".

Extract structured Facebook data — public profile pages, posts, comments, and events — through a Facebook-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="facebook.com".

Use when: "get this public Facebook page's profile info", "pull the comments on this Facebook post", "get details for this Facebook event", "find events matching <query> on Facebook", "list the upcoming events on this Facebook page". Not for: A single Facebook URL you just want read as plain text — use novada_extract. A general web search not scoped to Facebook — use novada_search. A different platform's structured data (Instagram, X, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured profile/post/comment/event records (page name, post text, comment author/text, event name/date/location, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 6 verified-working Facebook operations spanning public profile pages, posts, comments, and events (search / single event / event list) (see the operation param's description for the exact params keys each needs). Every facebook.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured GitHub repository data — repository details by URL, or multiple repositories from a GitHub search-results URL — through a GitHub-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="github.com".

Use when: "get repository info (stars, forks, description, language, etc.) for this GitHub repo URL", "get the repositories listed on this GitHub search-results URL". Not for: A single GitHub URL (repo, issue, PR, user) you just want read as plain text — use novada_extract. A general web/code search not scoped to GitHub, or a GitHub issue/PR/user lookup (no catalog operation exists for those) — use novada_search, or novada_extract for a known URL. A different platform's structured data (LinkedIn, Amazon, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured repository records (name, description, stars, forks, language, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 3 verified-working GitHub operations: two repository-by-URL lookups (repository_by_url and repository_details_by_url map to distinct catalog scraper_ids — github_repository_repo-url and github_repository_url respectively — both taking the same url param; the catalog documents no behavioral difference between them) and repository listing from a GitHub search-results URL (see the operation param's description for the exact params keys each needs). Every github.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Google SERP data — organic web search results, AI Mode answers, Maps place/review details, Shopping listings, Jobs, Hotels, and Videos — through a Google-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="google.com". Returns raw structured SERP records, not a generated answer.

Use when: "get the raw Google search results (titles, links, ranks) for <query>", "what's in Google's AI Mode answer for <query>", "pull Google Maps reviews or place details for this URL / place_id / CID", "search Google Shopping for <keyword>", "find Google Jobs, Hotels, or Videos results for <query>". Not for: A general question that just needs an answer or a few good links — use novada_search — multi-engine (google/duckduckgo/yandex), ranked and reranked, answer-oriented, and far cheaper than a raw-SERP scrape. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content (not a search results page) — use novada_extract. A different platform's structured data (Amazon, LinkedIn, TikTok, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured SERP records per operation — organic results (title/url/snippet/rank), AI Mode answer content, Maps place details/reviews, Shopping listings (price/rating), and Jobs/Hotels/Videos listings — in the chosen format (markdown/json/csv/excel/html/toon), same rendering as novada_scrape. Operations: 13 verified-working Google operations spanning web search, AI Mode, Maps (location/place_id/CID/URL lookups + reviews), Shopping, Jobs, Hotels, and Videos (see the operation param's description for the exact params keys each needs). Every google.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Instagram data — profiles, posts, reels, and comments — through an Instagram-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="instagram.com".

Use when: "get the latest posts from this Instagram profile", "pull the comments on this Instagram post or reel", "get details for this single Instagram post or reel URL", "get Instagram profile info by URL or username", "get the reels posted by this Instagram profile". Not for: A single Instagram URL you just want read as plain text — use novada_extract. A general web search not scoped to Instagram — use novada_search. A different platform's structured data (TikTok, Facebook, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured profile/post/reel/comment records (username, follower count, caption, like count, comment author/text, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 7 verified-working Instagram operations spanning profile lookup (by URL or username), posts and reels (by profile or by direct URL), and comments (see the operation param's description for the exact params keys each needs). posts_by_profile requires BOTH profileurl AND resultsLimit together. Every instagram.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured LinkedIn data — job listings (by location/filters, by a jobs search-results URL, or a single job posting URL) and company profile info by URL — through a LinkedIn-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="linkedin.com".

Use when: "find LinkedIn job listings in <location> matching <keyword/level/remote/etc.>", "get all the job listings from this LinkedIn jobs search URL", "get details for this single LinkedIn job posting URL", "get company info for this LinkedIn company URL". Not for: A single LinkedIn URL you just want read as plain text — use novada_extract. A general web search not scoped to LinkedIn — use novada_search. A LinkedIn personal PROFILE (not a company or job) — no catalog operation exists for this today — use novada_extract on the profile URL, or novada_search. A different platform's structured data (GitHub, Amazon, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured job-listing/company records (title, location, level, company name, follower count, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 4 verified-working LinkedIn operations spanning job search (by location, with optional keyword/level/remote/company filters), job listings from a search-results URL, a single job posting by URL, and company info by URL (see the operation param's description for the exact params keys each needs). jobs_search requires params.location — the catalog's actual required key for this op, despite its upstream name reading "By Keywords" (keyword itself is optional there). Every linkedin.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract the actual AI-generated answer Perplexity returns for a query — by a Perplexity query URL or a raw search term — through a Perplexity-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="perplexity.ai". This scrapes Perplexity's own live-rendered answer page (the model's actual response text) — it is NOT a web search results list and NOT an indexed-page brand-mention scan.

Use when: "what does Perplexity AI answer for <query>", "get Perplexity's generated answer for this perplexity.ai URL", "get Perplexity's answer for the search term <term>". Not for: A general web/multi-engine search for information (not specifically Perplexity's own generated answer) — use novada_search. Checking whether a brand is mentioned on AI-company indexed public pages (chatgpt.com/perplexity.ai/openai.com/etc.) — use novada_ai_monitor — that tool scans INDEXED PUBLIC PAGES for brand mentions across AI-company domains; it does not fetch a live generated answer for an arbitrary query the way this tool does. A complex question needing cited, multi-source synthesis — use novada_research. Reading one already-known URL's raw page content — use novada_extract. A different platform's structured data (Amazon, LinkedIn, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Perplexity's rendered answer content (the text of its generated response) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 2 verified-working Perplexity operations: answer by a perplexity.ai query URL, or answer by a raw search term (see the operation param's description for the exact params keys each needs). Every perplexity.ai catalog operation is currently status:"ok" — none are excluded for being backend_broken, unlike its sibling chatgpt.com, whose only 2 catalog operations are BOTH backend_broken (verified 2026-07-13, "submit hangs >120s") — which is why no novada_scrape_chatgpt tool exists.

Extract structured SHEIN product data — product details by product ID or product URL — through a SHEIN-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="shein.com".

Use when: "get SHEIN product details for this product ID", "get SHEIN product details for this product URL". Not for: A single SHEIN URL you just want read as plain text — use novada_extract. A general web search not scoped to SHEIN — use novada_search. SHEIN keyword or category product-list search (no working operation exists for these today) — use novada_search, or novada_extract on a SHEIN category/search page URL — the 3 catalog operations that would cover this (product list by keyword, by category ID, by category URL) are all backend_broken (submit endpoint hangs 60s+) and deliberately excluded from this tool's enum. A different platform's structured data (Amazon, Walmart, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured product records (title, price, rating, images, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 2 verified-working SHEIN operations: product lookup by product ID or by product URL (see the operation param's description for the exact params keys each needs). 3 known backend_broken SHEIN operations — product-list by keyword, by category ID, and by category URL, all failing with a 60s+ submit-endpoint hang — are intentionally NOT in this enum; this tool rejects them before any backend call, unlike novada_scrape(platform="shein.com", ...), which still forwards them with a warning.

Extract structured TikTok data — profile info, post/video details, and post lists by profile, hashtag, or search URL — through a TikTok-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="tiktok.com".

Use when: "get the latest posts from this TikTok profile", "get details for this single TikTok video URL", "pull TikTok profile info for this URL", "search TikTok profiles from this discover/search URL", "get posts from this TikTok hashtag/discover page". Not for: A single TikTok URL you just want read as plain text — use novada_extract. A general web search not scoped to TikTok — use novada_search. A different platform's structured data (YouTube, Instagram, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured profile/post records (username, follower count, video description, likes, view count, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 5 verified-working TikTok operations: profile search by list URL, profile by URL, posts by list URL, posts by profile URL, and a single post by URL (see the operation param's description for the exact params keys each needs). Every tiktok.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Walmart data — product details by keyword search, category URL, SKU, zip-code-specific pricing, or direct product URL — through a Walmart-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="walmart.com".

Use when: "search Walmart for <keyword> and give me prices/ratings", "get product listings from this Walmart category URL", "what's the price/availability for this Walmart SKU", "get this Walmart product's info for a specific zip code", "get product details for this Walmart product URL". Not for: A single Walmart URL you just want read as plain text — use novada_extract. A general web search not scoped to Walmart — use novada_search. A different platform's structured data (Amazon, SHEIN, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured product records (title, price, rating, availability, SKU, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 5 verified-working Walmart operations spanning keyword search, category-URL listings, SKU lookup, zip-code-specific pricing, and direct product URL (see the operation param's description for the exact params keys each needs). product_by_keyword requires BOTH domain AND keyword together; product_by_category_url requires ALL THREE of category_url, all, AND page_limit together; product_by_url_and_zipcode requires BOTH url AND zipcode together. Every walmart.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured X (Twitter) data — a single post and profile lookups by username or URL — through an X-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="x.com".

Use when: "get the text/engagement stats for this X post URL", "get this X profile's info by username", "get this X profile's info by profile URL". Not for: A single X/Twitter URL you just want read as plain text — use novada_extract. A general web search not scoped to X — use novada_search. A different platform's structured data (YouTube, Instagram, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured post/profile records (post text, like/reply/repost counts, profile bio, follower count, etc.) in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 3 verified-working X (Twitter) operations: a single post by URL, and profile lookup by username or by profile URL (see the operation param's description for the exact params keys each needs). Every x.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Yandex web search SERP data through a Yandex-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="yandex.com". Returns the raw organic-results SERP, with TLD/language/time-range controls novada_search does not expose, not a generated answer.

Use when: "get the raw Yandex search results (titles, links, ranks) for <query>", "search a specific Yandex TLD (params.yandex_domain, e.g. "yandex.ru") for Russian/Eastern European content", "search Yandex restricted to a time range (params.within)". Not for: A general question that just needs an answer or a few good links — use novada_search with engine="yandex" — same engine, but ranked/reranked and answer-oriented instead of a raw SERP dump. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content (not a search results page) — use novada_extract. A different platform's structured data (Amazon, LinkedIn, TikTok, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured organic-result SERP records (title/url/snippet/rank) in the chosen format (markdown/json/csv/excel/html/toon), same rendering as novada_scrape. Operations: 1 verified-working Yandex operation (web search — see the operation param's description for the exact params keys it needs, including the required params.yandex_domain TLD selector). The single yandex.com catalog operation is currently status:"ok".

Extract structured YouTube data — video and channel metadata, transcripts, comments, and downloadable video/audio files — through a YouTube-only tool with a closed, typed operation enum. Same underlying engine as novada_scrape, pinned to platform="youtube.com".

Use when: "get the transcript/subtitles for this YouTube video", "pull the comments on this YouTube video", "get channel info for this YouTube channel URL", "search YouTube channels for <keyword>", "find YouTube videos matching <keyword>, filtered by duration/upload date/attributes". Not for: A single YouTube URL you just want read as plain text — use novada_extract. A general web/video search not scoped to YouTube — use novada_search. A different platform's structured data (TikTok, Instagram, etc.) — use novada_scrape with that platform's domain, or its own novada_scrape_<platform> tool. Returns: Structured video/channel/comment records (title, views, transcript text, comment author/text, channel subscriber count, etc.) plus downloadable video/audio file links, in the chosen format (markdown/json/csv/excel/html/toon) — same rendering as novada_scrape. Operations: 13 verified-working YouTube operations spanning transcripts, video/audio file downloads, channel lookup + search, comments, and video search by keyword/label/filters/playlist/channel (see the operation param's description for the exact params keys each needs). Every youtube.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Search the web and get clean, ready-to-use content. 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='google' (default) is the fastest and most reliable. duckduckgo/yandex are fallbacks and can be markedly slower. Domain filtering: includeDomains/excludeDomains are applied by injecting site:domain operators into the query (not API-side filtering). Project grouping: Pass project="my-project" to group all outputs in a subfolder (e.g. ~/Downloads/novada-mcp/2026-06-26/my-project/). Useful for multi-step research tasks.

Record search-result quality so future ranking can learn from it. Returns a thank-you/echo confirmation with an agent_instruction.

Best for: After a novada_search call, tell Novada which result URLs were useful and rate the set (good/ok/bad). The signal biases future ranking. Params: search_id (the prior search's id), query, rating ('good'|'ok'|'bad'), useful_urls? (results you clicked/cited, max 50), note? (what was missing). Scope: In-memory feedback store, per-process — resets when the MCP server restarts. Nothing is persisted to disk. Auth-free (no API key needed).

Return per-process / per-session usage telemetry: tool-call counts, the last-N calls, and process uptime.

Best for: "What have I called this session?" / debugging an agent loop / seeing which Novada tools dominate usage. Returns: session_started, uptime, total_calls, per-tool counts (high→low), and the most-recent calls (newest first, capped by recent_limit). Scope: In-memory, per-process — resets when the MCP server restarts. Nothing is persisted to disk and nothing leaves the process. Auth-free (no API key needed).

The onboarding concierge and first-run front door of the Novada MCP. Call this FIRST when starting out, or whenever a tool reports a missing/invalid key.

What it does:

1. Validates your key — makes one cheap, authoritative account read (wallet balance) to confirm your key actually works, and shows your balance. No synthetic per-product probes, no credit cost.
2. Guides you if you have no key — tells you to register at the Novada dashboard (free credits included for testing), where to copy your API key, and the exact config snippet for Claude Code / Claude Desktop / Cursor / VS Code / Windsurf.
3. Orients you — a plain-language list of the core things you can do (search, extract, scrape, browser, account) plus the add-ons.

Three states it reports: key present + valid (ready) · key present but rejected (fix it) · no key yet (register + free credits). Output also includes server_version (the running package version).

Auth-free by design: this is the tool that helps you GET a key, so a missing key is the normal first-run state — it guides, it never errors. Includes a machine-usable agent_instruction so an AI knows exactly what to tell the user next.

Unified key: NOVADA_API_KEY covers search, extract, unblock, scraper, research, crawl, map, browser and proxy auto-provisioning. NOVADA_BROWSER_WS and NOVADA_PROXY_ENDPOINT are optional add-ons that need no separate key.

Copy an entire docs site or site section to disk as clean markdown — one .md file per page — and return a COMPACT manifest, not the page bodies. Use when you need a whole knowledge base on disk (offline docs ingest, RAG corpus, full-site mirror).

Discovery (in order): (1) llms.txt / llms-full.txt if present (canonical, flat page list), (2) sitemap.xml, (3) scoped same-host BFS drained to completion. Path filters (select_paths/exclude_paths) and same-host are always enforced. Best for: "Copy all of docs.x.com", building a local docs corpus, ingesting an llms.txt index. Not for: A single page (use novada_extract), a handful of pages inline (use novada_crawl — it returns bodies), URL discovery only (use novada_map). Output: Each page is written to ~/Downloads/novada-mcp/<date>/<project|domain>/site-copy/<slug>.md as it completes. A manifest.json records {url,file,title,word_count,depth,bytes,status} per page plus run meta. The tool RETURNS a compact summary + the manifest path — Read the .md files or manifest.json, do not expect inline content. Scale: max_pages default 200, hard max 1000. Drains the in-scope queue until empty or the ceiling is hit. Key rule: Files are streamed to disk; the response is intentionally small. After it completes, Read manifest.json then open the specific .md files you need.

Manage static ISP IPs on the account. Wraps /v1/static_house/* developer-api endpoints.

Actions: "open" = purchase new static IPs (WRITE, requires confirm:true). "renew" = renew existing IPs (WRITE, requires confirm:true). "export" = export filtered IP list (read-only). "list" = paginated IP list (read-only). Behavior: Without confirm:true on "open"/"renew", returns a preview and does NOT hit the API. Auth: NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

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.