Integration

MCP

MCP Server

Give any AI agent the ability to scrape, extract, and screenshot the web. One npm package, any MCP-compatible client.

9 Tools

Zero Config

Anti-Bot Bypass

Structured Extraction

Overview

The AlterLab MCP server (alterlab-mcp-server on npm) implements the Model Context Protocol so that AI agents running in Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, and Gemini CLI can scrape any website, extract structured data, take full-page screenshots, and manage authenticated sessions — all without leaving the agent environment.

The server proxies every request through AlterLab's intelligent tier system, automatically handling JavaScript rendering, TLS fingerprinting, and anti-bot challenges. Your agent describes what it needs; AlterLab handles the complexity of actually retrieving it.

Tools exposed to your agent

Supported AI clients

Free credits on sign-up

Installation

The MCP server runs as a local process. You can install it globally or let your client invoke it on-demand with npx. Node.js 18 or later is required.

Global install (recommended for frequent use)

Bash

npm install -g alterlab-mcp-server

On-demand via npx (no install needed)

Bash

npx -y alterlab-mcp-server

API Key

All tools require your AlterLab API key, passed via the ALTERLAB_API_KEY environment variable. Get your key from the Dashboard → API Keys.

Available Tools

The MCP server exposes 9 tools. Each tool maps directly to an AlterLab API capability. Your agent can call any of them by name once the server is connected.

Tool	Description
`alterlab_scrape`	Scrape any URL and return content as markdown, plain text, HTML, or structured JSON. Supports JavaScript rendering, anti-bot bypass, and extraction profiles.
`alterlab_extract`	Extract structured JSON from a URL using a named profile (e.g. `product`, `article`) or a custom JSON Schema. Returns typed, validated data.
`alterlab_screenshot`	Capture a full-page PNG screenshot of any URL. Returns a hosted image URL. Useful for visual inspection or documentation.
`alterlab_estimate_cost`	Pre-estimate the cost of scraping a URL before making the request. Returns estimated USD cost and confidence level based on domain history.
`alterlab_check_balance`	Check the remaining credit balance on the account associated with the API key. Useful for budget-aware agents.
`alterlab_list_sessions`	List all stored browser sessions on the account. Sessions hold cookies for authenticated scraping of sites that require login.
`alterlab_create_session`	Store a set of browser cookies as a named session for reuse across scrape requests. Accepts a domain, session name, and cookie dictionary.
`alterlab_validate_session`	Check whether a stored session's cookies are still valid by making a test request to the session's domain. Returns a boolean validity status.
`alterlab_delete_session`	Permanently remove a stored session by its ID. Use after cookies have expired or the session is no longer needed.

Claude Code

Add the AlterLab MCP server to your Claude Code session with a single command. The server will be available to all future sessions on your machine.

Step 1 — Register the server

Bash

claude mcp add alterlab -- npx -y alterlab-mcp-server

Step 2 — Set your API key

Bash

export ALTERLAB_API_KEY=sk_live_your_key_here

Add this to your shell profile (~/.bashrc or ~/.zshrc) to persist it across sessions.

Verify the connection

After registering, start a new Claude Code session and ask: “Use AlterLab to scrape https://example.com and summarize the content.” Claude will call alterlab_scrape automatically.

Claude Desktop

Add AlterLab to the mcpServers block in your Claude Desktop config file.

Config file location

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add to config

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart required

Quit and reopen Claude Desktop after editing the config file for the server to appear.

Cursor

Cursor supports MCP servers scoped to a project via a .cursor/mcp.json file in the repository root, or globally via ~/.cursor/mcp.json.

.cursor/mcp.json (project-scoped)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Commit this file to your repository so all collaborators get the integration automatically. Each developer supplies their own API key via their environment.

Use environment variables for the key

Instead of hard-coding ALTERLAB_API_KEY in the JSON, omit the env block and export the variable in your shell profile. Cursor inherits your shell environment when launching MCP servers.

Windsurf

Windsurf reads MCP server configuration from a global JSON file in the Codeium directory.

Config file location

Bash

~/.codeium/windsurf/mcp_config.json

Add to config

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Windsurf after editing

Close and reopen Windsurf to load newly added MCP servers.

Codex CLI

OpenAI's Codex CLI supports MCP servers via a global config or a project-level override file.

Global config (~/.codex/config.json)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Project override (.codex/mcp.json in repo root)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

The project-level file takes precedence over the global config when both are present.

Gemini CLI

Google's Gemini CLI reads MCP server configuration from the settings file in the ~/.gemini directory.

~/.gemini/settings.json

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Verify available tools

Run gemini /mcp in the CLI to list all connected MCP servers and confirm the 9 AlterLab tools are visible.

Extraction Profiles

When calling alterlab_extract or passing a profile to alterlab_scrape, you can specify a named profile to receive a consistent, typed JSON structure optimized for that content type. Profiles eliminate the need to write a JSON Schema for common data formats.

Profile	Best For	Key Fields Returned
`auto`	Any page — AlterLab infers the best schema	Varies by content type detected
`product`	E-commerce product pages	name, price, currency, in_stock, images, description, rating, review_count, sku, brand
`article`	Blog posts, news articles	title, author, published_at, body_markdown, tags, summary, image_url
`job_posting`	Job boards, career pages	title, company, location, remote, salary_range, description, requirements, posted_at, apply_url
`faq`	FAQ sections, help pages	items[ ] with question and answer fields
`recipe`	Cooking and food sites	name, ingredients, instructions, prep_time, cook_time, servings, nutrition, author
`event`	Event listings, ticketing pages	name, start_date, end_date, location, organizer, ticket_url, price, description

Custom schemas

For data that doesn't fit a built-in profile, pass a JSON Schema directly in the schema parameter of alterlab_extract. AlterLab's extraction engine will populate it from the page content.

Authenticated Scraping

Some sites require a logged-in browser session to return meaningful content — dashboards, order history pages, paywalled articles. AlterLab sessions let your agent store a set of cookies once and reuse them across many requests without re-authenticating each time.

Typical agent workflow

Call alterlab_list_sessions to see if a session for the target domain already exists.
If no session exists, call alterlab_create_session with the domain and cookies extracted from your browser.
Pass the session_id to alterlab_scrape or alterlab_extract to make authenticated requests.
If a scrape fails with an authentication error, call alterlab_validate_session to check whether cookies have expired, then refresh them as needed.

Cookie security

Session cookies are encrypted at rest and scoped to your API key. Never pass session tokens for financial or healthcare platforms unless you own those accounts.

Pricing

Each tool call consumes credits based on the scraping tier required and any add-ons applied. AlterLab's tier system automatically selects the cheapest tier that can successfully retrieve the page — your agent only pays for what is needed. New accounts receive $1 in free credits with no credit card required.

Base tier cost per request

Tier	Name	Cost	Requests per $1	When used
1	Curl	$0.0002	5,000	Plain static HTML with no bot protection
2	HTTP	$0.0003	3,333	TLS fingerprinting and header challenges
3	Stealth	$0.0005	2,000	Browser fingerprint checks without full JS execution
3.5	Light JS	$0.0007	1,428	Lightweight JS rendering for simple SPAs
4	Browser	$0.001	1,000	Full headless browser for heavy JS and anti-bot walls

Add-on costs (applied on top of base tier)

Add-on	Additional cost	Description
JavaScript rendering	+$0.0006	Full JS execution on top of an HTTP-tier request
Residential proxy	+$0.0002	Routes request through a residential IP for geo-sensitive targets
OCR extraction	+$0.001	Optical character recognition on image-based content

Use alterlab_estimate_cost first

For budget-aware agents, call alterlab_estimate_cost before scraping an unfamiliar domain. The tool returns a cost estimate and confidence level based on historical data for that domain, so your agent can decide whether to proceed.

$1 free on sign-up

New accounts receive $1 in credits with no credit card required. That's up to 5,000 basic scrapes or ~1,000 full browser renders to explore the platform before committing. Create a free account.

From ScrapingBee / ScraperAPI n8n Node

Last updated: March 2026

Integration

MCP

MCP Server

Give any AI agent the ability to scrape, extract, and screenshot the web. One npm package, any MCP-compatible client.

9 Tools

Zero Config

Anti-Bot Bypass

Structured Extraction

Overview

Tools exposed to your agent

Supported AI clients

Free credits on sign-up

Installation

The MCP server runs as a local process. You can install it globally or let your client invoke it on-demand with npx. Node.js 18 or later is required.

Global install (recommended for frequent use)

Bash

npm install -g alterlab-mcp-server

On-demand via npx (no install needed)

Bash

npx -y alterlab-mcp-server

API Key

All tools require your AlterLab API key, passed via the ALTERLAB_API_KEY environment variable. Get your key from the Dashboard → API Keys.

Available Tools

The MCP server exposes 9 tools. Each tool maps directly to an AlterLab API capability. Your agent can call any of them by name once the server is connected.

Tool	Description
`alterlab_scrape`	Scrape any URL and return content as markdown, plain text, HTML, or structured JSON. Supports JavaScript rendering, anti-bot bypass, and extraction profiles.
`alterlab_extract`	Extract structured JSON from a URL using a named profile (e.g. `product`, `article`) or a custom JSON Schema. Returns typed, validated data.
`alterlab_screenshot`	Capture a full-page PNG screenshot of any URL. Returns a hosted image URL. Useful for visual inspection or documentation.
`alterlab_estimate_cost`	Pre-estimate the cost of scraping a URL before making the request. Returns estimated USD cost and confidence level based on domain history.
`alterlab_check_balance`	Check the remaining credit balance on the account associated with the API key. Useful for budget-aware agents.
`alterlab_list_sessions`	List all stored browser sessions on the account. Sessions hold cookies for authenticated scraping of sites that require login.
`alterlab_create_session`	Store a set of browser cookies as a named session for reuse across scrape requests. Accepts a domain, session name, and cookie dictionary.
`alterlab_validate_session`	Check whether a stored session's cookies are still valid by making a test request to the session's domain. Returns a boolean validity status.
`alterlab_delete_session`	Permanently remove a stored session by its ID. Use after cookies have expired or the session is no longer needed.

Claude Code

Add the AlterLab MCP server to your Claude Code session with a single command. The server will be available to all future sessions on your machine.

Step 1 — Register the server

Bash

claude mcp add alterlab -- npx -y alterlab-mcp-server

Step 2 — Set your API key

Bash

export ALTERLAB_API_KEY=sk_live_your_key_here

Add this to your shell profile (~/.bashrc or ~/.zshrc) to persist it across sessions.

Verify the connection

After registering, start a new Claude Code session and ask: “Use AlterLab to scrape https://example.com and summarize the content.” Claude will call alterlab_scrape automatically.

Claude Desktop

Add AlterLab to the mcpServers block in your Claude Desktop config file.

Config file location

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add to config

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart required

Quit and reopen Claude Desktop after editing the config file for the server to appear.

Cursor

Cursor supports MCP servers scoped to a project via a .cursor/mcp.json file in the repository root, or globally via ~/.cursor/mcp.json.

.cursor/mcp.json (project-scoped)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Commit this file to your repository so all collaborators get the integration automatically. Each developer supplies their own API key via their environment.

Use environment variables for the key

Instead of hard-coding ALTERLAB_API_KEY in the JSON, omit the env block and export the variable in your shell profile. Cursor inherits your shell environment when launching MCP servers.

Windsurf

Windsurf reads MCP server configuration from a global JSON file in the Codeium directory.

Config file location

Bash

~/.codeium/windsurf/mcp_config.json

Add to config

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Windsurf after editing

Close and reopen Windsurf to load newly added MCP servers.

Codex CLI

OpenAI's Codex CLI supports MCP servers via a global config or a project-level override file.

Global config (~/.codex/config.json)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Project override (.codex/mcp.json in repo root)

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

The project-level file takes precedence over the global config when both are present.

Gemini CLI

Google's Gemini CLI reads MCP server configuration from the settings file in the ~/.gemini directory.

~/.gemini/settings.json

JSON

{
  "mcpServers": {
    "alterlab": {
      "command": "npx",
      "args": ["-y", "alterlab-mcp-server"],
      "env": {
        "ALTERLAB_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Verify available tools

Run gemini /mcp in the CLI to list all connected MCP servers and confirm the 9 AlterLab tools are visible.

Extraction Profiles

Profile	Best For	Key Fields Returned
`auto`	Any page — AlterLab infers the best schema	Varies by content type detected
`product`	E-commerce product pages	name, price, currency, in_stock, images, description, rating, review_count, sku, brand
`article`	Blog posts, news articles	title, author, published_at, body_markdown, tags, summary, image_url
`job_posting`	Job boards, career pages	title, company, location, remote, salary_range, description, requirements, posted_at, apply_url
`faq`	FAQ sections, help pages	items[ ] with question and answer fields
`recipe`	Cooking and food sites	name, ingredients, instructions, prep_time, cook_time, servings, nutrition, author
`event`	Event listings, ticketing pages	name, start_date, end_date, location, organizer, ticket_url, price, description

Custom schemas

For data that doesn't fit a built-in profile, pass a JSON Schema directly in the schema parameter of alterlab_extract. AlterLab's extraction engine will populate it from the page content.

Authenticated Scraping

Typical agent workflow

Call alterlab_list_sessions to see if a session for the target domain already exists.
If no session exists, call alterlab_create_session with the domain and cookies extracted from your browser.
Pass the session_id to alterlab_scrape or alterlab_extract to make authenticated requests.
If a scrape fails with an authentication error, call alterlab_validate_session to check whether cookies have expired, then refresh them as needed.

Cookie security

Session cookies are encrypted at rest and scoped to your API key. Never pass session tokens for financial or healthcare platforms unless you own those accounts.

Pricing

Base tier cost per request

Tier	Name	Cost	Requests per $1	When used
1	Curl	$0.0002	5,000	Plain static HTML with no bot protection
2	HTTP	$0.0003	3,333	TLS fingerprinting and header challenges
3	Stealth	$0.0005	2,000	Browser fingerprint checks without full JS execution
3.5	Light JS	$0.0007	1,428	Lightweight JS rendering for simple SPAs
4	Browser	$0.001	1,000	Full headless browser for heavy JS and anti-bot walls

Add-on costs (applied on top of base tier)

Add-on	Additional cost	Description
JavaScript rendering	+$0.0006	Full JS execution on top of an HTTP-tier request
Residential proxy	+$0.0002	Routes request through a residential IP for geo-sensitive targets
OCR extraction	+$0.001	Optical character recognition on image-based content

Use alterlab_estimate_cost first

$1 free on sign-up

New accounts receive $1 in credits with no credit card required. That's up to 5,000 basic scrapes or ~1,000 full browser renders to explore the platform before committing. Create a free account.

From ScrapingBee / ScraperAPI n8n Node

Last updated: March 2026