# Proxy4agent

> Residential proxy MCP for AI agents — geo-targeting, sticky sessions, anti-bot bypass.

- **Type:** MCP server
- **Install:** `agentstack add mcp-novadalabs-proxy4agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [NovadaLabs](https://agentstack.voostack.com/s/novadalabs)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 1.7.0
- **License:** MIT
- **Upstream author:** [NovadaLabs](https://github.com/NovadaLabs)
- **Source:** https://github.com/NovadaLabs/novada-proxy
- **Website:** https://www.novada.com

## Install

```sh
agentstack add mcp-novadalabs-proxy4agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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.

  
  
  
  
  

  
  
  
  
  

  
  
  
  

  
  

  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](https://www.novada.com), no credit card required. Get free access to Scraper API, Web Unblocker, and residential proxies to start building immediately.

---

## Getting Started

  
  
  

### For Humans

1. **Create a free account** at [novada.com](https://www.novada.com) — no credit card required
2. **Get your credentials** at [Dashboard → Residential Proxies → Endpoint Generator](https://dashboard.novada.com/overview/res/endpoint-generator/) — copy your username and password
3. **Install and run:**

```bash
# 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](mailto:support@novada.com)

---

## Why Novada Proxy

AI agents get blocked on 60–70% of commercial websites. Standard HTTP requests are detected and rejected by Cloudflare, Akamai, DataDome, and PerimeterX. Novada Proxy routes your agent through real residential IPs — indistinguishable from a human browser.

| Problem | Solution |
|---------|----------|
| Amazon, LinkedIn, Cloudflare block your agent | 2M+ residential IPs from real home devices |
| Bot challenges return 403 / CAPTCHA | Real device fingerprints bypass detection |
| JS-rendered pages return blank content | `novada_proxy_render` runs real Chromium |
| Geo-restricted or localized content | 195+ countries, city-level targeting |
| Multi-step workflows need the same IP | Sticky sessions — consistent IP across calls |
| Scraping 10+ URLs wastes time | `novada_proxy_batch_fetch` — concurrent, parallel |
| Need structured fields, not raw HTML | `novada_proxy_extract` — title, price, rating, etc. |
| Finding URLs before scraping | `novada_proxy_map` — discover all internal links |
| Need clean search results | `novada_proxy_search` — Google results as JSON |

---

## 10 Tools at a Glance

| Tool | What It Does | Requires |
|------|-------------|---------|
| `novada_proxy_fetch` | Fetch any URL through residential proxy | Proxy credentials |
| `novada_proxy_batch_fetch` | Fetch 2–20 URLs concurrently (up to 5x parallel) | Proxy credentials |
| `novada_proxy_extract` | Extract structured fields — heuristic mode (fields) or LLM mode (schema) | Proxy credentials |
| `novada_proxy_map` | Crawl a URL and return all internal links as JSON array | Proxy credentials |
| `novada_proxy_crawl` | Recursively crawl a site (BFS, depth 1-5) with URL discovery | Proxy credentials |
| `novada_proxy_session` | Sticky session — same IP across every call | Proxy credentials |
| `novada_proxy_search` | Google search -> structured JSON (title, url, snippet) | `NOVADA_API_KEY` |
| `novada_proxy_render` | Render JS-heavy pages with real Chromium [BETA] | `NOVADA_BROWSER_WS` |
| `novada_proxy_research` | One-shot deep research — search + fetch + synthesize | `NOVADA_API_KEY` + Proxy |
| `novada_proxy_status` | Check proxy network health + version | _(none)_ |

---

## Quick Decision Guide

| I want to... | Use this tool |
|--------------|---------------|
| Fetch a single URL | `novada_proxy_fetch` |
| Fetch 2–20 URLs at once | `novada_proxy_batch_fetch` |
| Extract specific fields (title, price...) | `novada_proxy_extract` with `fields` |
| Extract ANY field via schema | `novada_proxy_extract` with `schema` |
| Find all links on a page | `novada_proxy_map` |
| Crawl an entire site | `novada_proxy_crawl` |
| Research a topic | `novada_proxy_research` |
| Search Google | `novada_proxy_search` |
| Render a JS-heavy page | `novada_proxy_render` |
| Keep same IP across calls | `novada_proxy_session` |
| Check if proxy works | `novada_proxy_status` |

## When To Use Which Tool

```
Goal: "Scrape a single URL"
  └─ Static HTML page?          → novada_proxy_fetch
  └─ Need specific fields?      → novada_proxy_extract (fields or schema mode)
  └─ React/Vue SPA / blank page? → novada_proxy_render

Goal: "Scrape multiple URLs"
  └─ You have the URLs already  → novada_proxy_batch_fetch
  └─ You need links from one page → novada_proxy_map → novada_proxy_batch_fetch
  └─ You need to crawl a whole site → novada_proxy_crawl → novada_proxy_batch_fetch

Goal: "Research a topic"        → novada_proxy_research (search + fetch + findings in one call)

Goal: "Search the web"          → novada_proxy_search → novada_proxy_batch_fetch

Goal: "Login + multi-page flow" → novada_proxy_session (same session_id)

Goal: "Check if proxy works"    → novada_proxy_status
```

---

## 5 Prompts

Pre-built agent workflows that chain multiple tools together. Call these from any MCP client to execute common patterns in one step.

| Prompt | Description | Key Arguments |
|--------|-------------|---------------|
| `fetch_url` | Fetch a URL through residential proxy with anti-bot bypass | `url`, `country`, `format` |
| `research_topic` | Search + batch read workflow — find and read top pages on a topic | `query`, `num_results`, `country` |
| `extract_product` | Extract structured product data from any e-commerce URL | `url`, `fields` |
| `crawl_site` | Discover all pages on a site, then fetch them in parallel | `url`, `limit`, `country` |
| `troubleshoot` | Step-by-step proxy diagnosis when things go wrong | `error_message` |

> [!NOTE]
> Prompts orchestrate multi-tool workflows automatically. For example, `research_topic` runs `novada_proxy_search` then `novada_proxy_batch_fetch` in sequence — the agent doesn't need to figure out the pipeline.

---

## 5 Resources

Always-accessible reference data that agents can read at any time, without making proxy calls.

| Resource URI | Description |
|-------------|-------------|
| `proxy://countries` | Complete list of 195+ country codes with city-level targeting |
| `proxy://error-codes` | All typed error codes with recovery instructions |
| `proxy://workflows` | Common agent workflow patterns (crawl, research, monitoring) |
| `proxy://supported-fields` | All fields `novada_proxy_extract` can extract with strategies |
| `proxy://cost-guide` | Credits per tool, caching behavior, cost optimization tips |

---

## Quick Install

**Core — fetch any URL through residential proxy:**
```bash
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:**
```bash
claude mcp add novada-proxy-mcp \
  -e NOVADA_API_KEY=your_key \
  -- npx -y novada-proxy-mcp
```

**All tools (proxy + search + browser render):**
```bash
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:**
```json
{
  "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](https://www.novada.com)** -> Dashboard -> Residential Proxies -> Endpoint Generator

---

## Providers

Novada Proxy works with **any HTTP proxy provider**. Novada is the built-in default with the deepest integration.

**Priority:** Novada -> BrightData -> Smartproxy -> Oxylabs -> Generic. First configured provider wins.

| Feature | Novada | BrightData | Smartproxy | Oxylabs | Generic HTTP |
|---------|--------|------------|------------|---------|-------------|
| Auto country targeting | ✓ | ✓ | ✓ | ✓ | manual |
| Auto city targeting | ✓ | ✓ | ✓ | ✓ | manual |
| Sticky sessions | ✓ | ✓ | ✓ | ✓ | manual |
| Built-in search API | ✓ | — | — | — | — |
| Browser API (JS render) | ✓ | — | — | — | — |

BrightData setup

```bash
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

```bash
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

```bash
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)

```bash
claude mcp add novada-proxy-mcp \
  -e PROXY_URL="http://username:password@geo.iproyal.com:12321" \
  -- npx -y novada-proxy-mcp
```
`country`, `city`, `session_id` params are ignored with Generic — encode targeting directly in your proxy URL.

---

## Agent-First Design

> [!NOTE]
> Novada Proxy is the only proxy MCP designed specifically for autonomous AI agents. Every response, error, and description is optimized for machine consumption.

| Feature | What It Means |
|---------|--------------|
| `agent_instruction` in errors | Every error tells the agent exactly what to do next |
| Decision trees in descriptions | WHEN TO USE / USE INSTEAD guides in every tool |
| `cache_hit` metadata | Agent knows when 0 credits were used (cached response) |
| `credits_estimated` per call | Cost tracking built into every response |
| Typed error codes | Machine-readable: `BOT_DETECTION_SUSPECTED`, `PAGE_NOT_FOUND`, etc. |
| 5 workflow prompts | Pre-built agent workflows: research, crawl, extract, diagnose |
| 5 reference resources | Countries, error codes, cost guide — always accessible |

---

## Tools

### `novada_proxy_fetch`
Fetch any URL through a residential proxy. Returns structured JSON with content, status code, and metadata. Auto-retry on network errors. Caches repeated calls (default 300s TTL — `meta.cache_hit: true` means no proxy credit used).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | Target URL (`http://` or `https://`) |
| `country` | string | — | 2-letter ISO code: `US`, `DE`, `JP`, `GB`, `BR`... (195+ options) |
| `city` | string | — | City: `newyork`, `london`, `tokyo`, `paris`, `berlin`... |
| `session_id` | string | — | Reuse same ID for same IP across calls (no hyphens, max 64 chars) |
| `format` | string | `markdown` | `markdown` strips HTML / `raw` returns full HTML |
| `timeout` | number | `60` | Timeout in seconds (1–120) |

**Response:**
```json
{
  "ok": true,
  "tool": "novada_proxy_fetch",
  "data": { "url": "...", "status_code": 200, "content": "...", "size_bytes": 34000 },
  "meta": { "latency_ms": 1800, "cache_hit": false, "quota": { "credits_estimated": 1 } }
}
```

---

### `novada_proxy_batch_fetch`
Fetch 2–20 URLs concurrently through residential proxy. Up to 5x faster than sequential fetches. Per-URL errors are captured individually — the batch itself succeeds even if some URLs fail. Reuses response cache for URLs already fetched.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `urls` | string[] | required | 2–20 URLs to fetch |
| `concurrency` | number | `3` | Parallel requests (1–5) |
| `country` | string | — | Same country for all URLs |
| `format` | string | `markdown` | `markdown` or `raw` |
| `timeout` | number | `60` | Per-URL timeout in seconds |

**Response:**
```json
{
  "ok": true,
  "tool": "novada_proxy_batch_fetch",
  "data": {
    "requested": 3,
    "succeeded": 3,
    "failed": 0,
    "results": [
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": false, "latency_ms": 1200 },
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": true,  "latency_ms": 0 },
      { "url": "https://...", "ok": false, "error": { "code": "TLS_ERROR", "message": "..." } }
    ]
  },
  "meta": { "latency_ms": 4100, "quota": { "credits_estimated": 3 } }
}
```

---

### `novada_proxy_extract`
Extract structured fields from any URL using heuristic pattern matching (meta tags, Open Graph, JSON-LD, Schema.org). Lightweight — no LLM needed. Set `render_fallback: true` to automatically retry via real Chromium if the proxy fetch fails.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | Target URL |
| `fields` | string[] | required | Fields to extract: `title`, `price`, `description`, `rating`, `image`, `author`, `date`... |
| `render_fallback` | boolean | `false` | Auto-retry via `novada_proxy_render` on TLS/bot block |
| `country` | string | — | Geo-target the fetch |
| `timeout` | number | `60` | Timeout in seconds |

**Response:**
```json
{
  "ok": true,
  "tool": "novada_proxy_extract",
  "data": {
    "url": "https://books.toscrape.com/...",
    "fields": { "title": "A Light in the Attic", "price": "£51.77", "description": null },
    "extracted_via": "proxy_fetch"
  },
  "meta": { "latency_ms": 2100, "quota": { "credits_estimated": 1 } }
}
```

---

### `novada_proxy_map`
Crawl a URL and return all internal links as a structured JSON array. Use as the discovery step before `novada_proxy_batch_fetch` to crawl an entire site without guessing URLs.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | Starting URL to crawl |
| `limit` | number | `50` | Max URLs to return (10–200) |
| `include_external` | boolean | `false` | Include off-domain links |
| `country` | string | — | Geo-target the fetch |
| `timeout` | number | `60` | Timeout in seconds |

**Response:**
```json
{
  "ok": true,
  "tool": "novada_proxy_map",
  "data": {
    "domain": "books.toscrape.com",
    "internal_url_count": 20,
    "internal_urls": ["https://books.toscrape.com/catalogue/...", "..."],
    "sitemap_hint": "https://books.toscrape.com/sitemap.xml (check manually)"
  },
  "meta": { "latency_ms": 3800, "quota": { "credits_estimated": 1 } }
}
```

---

### `novada_proxy_session`
Sticky session fetch — every call with the same `session_id` uses the same residential IP. Essential for login flows, paginated scraping, and price monitoring. Supports `verify_sticky: true` to confirm IP consistency before relying on it.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `session_id` | string | required | Unique ID — reuse to keep same IP (no hyphens, max 64 chars) |
| `url` | string | required | Target URL |
| `country` | string | — | 2-letter country code |
| `city` | string | — | City-level targe

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NovadaLabs](https://github.com/NovadaLabs)
- **Source:** [NovadaLabs/novada-proxy](https://github.com/NovadaLabs/novada-proxy)
- **License:** MIT
- **Homepage:** https://www.novada.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v1.7.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **1.7.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-novadalabs-proxy4agent
- Seller: https://agentstack.voostack.com/s/novadalabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.