```yaml
product: AlterLab
title: "MCP Server — Give AI Agents Live Web Access via AlterLab"
comparison_context: "AlterLab is an alternative to Firecrawl, ScrapingBee, and Bright Data."
source_url: https://alterlab.io/docs/integrations/mcp
```

Integration

MCP

# MCP Server

Give any AI agent the ability to scrape, extract, and screenshot the web. Connect any MCP-compatible client by URL, or run the npm package locally.

9 of 25 Tools

Connect by URL

Anti-Bot Handling

Structured Extraction

[![npm version](https://badge.fury.io/js/alterlab-mcp-server.svg)](https://www.npmjs.com/package/alterlab-mcp-server)[![GitHub stars](https://img.shields.io/github/stars/RapierCraft/alterlab-mcp-server?style=social)](https://github.com/RapierCraft/alterlab-mcp-server)

## Overview

The AlterLab MCP server — hosted at `https://mcp.alterlab.io/mcp` and published as `alterlab-mcp-server` on npm for local use — implements the [Model Context Protocol](https://modelcontextprotocol.io/) 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.

9

Tools exposed to your agent

6

Supported AI clients

Free

Up to 5,000 free requests on sign-up

## Let your agent set it up

Paste this prompt into Claude Code, Cursor, Codex, Windsurf or any coding agent. It reads [/agent-setup.md](https://alterlab.io/agent-setup.md), connects this MCP server, installs the SDK, and requests an API key through the human-approved signup flow: you approve it on your dashboard, and no key is pasted into chat or committed to a file. Then it runs a test scrape.

```
Set up AlterLab in this project. Read https://alterlab.io/agent-setup.md and follow it. It connects the AlterLab MCP server, installs the SDK, requests an API key that I approve, and runs a test scrape. Never ask me to paste a key.
```

Paste into Claude Code, Cursor, Codex, Windsurf or any coding agent.

## Connect by URL (recommended)

The hosted endpoint speaks the MCP Streamable HTTP transport and signs you in with OAuth. Add the URL to your client; the first time it connects, a browser window opens where you sign in to AlterLab and approve access. Nothing to install and no API key in a config file.

TEXT

```
https://mcp.alterlab.io/mcp
```

Client-specific steps are below for Claude Code, Claude Desktop, Cursor, and Windsurf. The hosted endpoint exposes the 67 core tools listed under Available Tools; requests are billed to the account you approve.

## Try Search Without a Key

No account needed to try search: 10 requests per minute and 200 per day per IP, 10 results per query. Up to 5,000 free requests when you create an account.

Claude Code

Bash

```
claude mcp add --transport http alterlab https://mcp.alterlab.io/mcp
```

Gemini CLI

Bash

```
gemini mcp add --transport http alterlab https://mcp.alterlab.io/mcp
```

VS Code

Bash

```
code --add-mcp '{"name":"alterlab","type":"http","url":"https://mcp.alterlab.io/mcp"}'
```

LangChain

Python

```
MultiServerMCPClient({"alterlab": {"transport": "streamable_http", "url": "https://mcp.alterlab.io/mcp"}})
```

OpenAI Agents SDK

Python

```
MCPServerStreamableHttp(params={"url": "https://mcp.alterlab.io/mcp"})
```

## Run Locally (npx)

For local development, self-hosting, air-gapped setups, and clients without remote MCP support.

The npm package runs as a local process and includes all 25 tools. 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

The local package authenticates with your AlterLab API key, passed via the `ALTERLAB_API_KEY` environment variable. Get your key from the [Dashboard → API Keys](https://alterlab.io/dashboard/api-keys).

## Available Tools

The hosted endpoint exposes the 67 core tools below; the local npm package exposes 25, adding session-management and beta-feature tools. Each 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 handling, 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 Claude Code with a single command. The server will be available to all future sessions on your machine.

### Recommended — connect by URL

Bash

```
claude mcp add --transport http alterlab https://mcp.alterlab.io/mcp
```

Then run `/mcp` inside Claude Code, select `alterlab`, and sign in to approve access in the browser.

### Local (npx) — Step 1: register the server

Bash

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

### Local (npx) — 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.

### Local (npx) — project config (`.mcp.json`)

Prefer committing the server to a project instead of your machine? Claude Code auto-loads an `.mcp.json` file from the project root — drop this in to make AlterLab available to anyone who opens the repo, including starter templates and CLAUDE.md-based project scaffolds.

JSON

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

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 as a custom connector, or run the npm package locally through the `mcpServers` block in your Claude Desktop config file.

### Recommended — connect by URL

Settings → Connectors → Add custom connector, name it AlterLab and paste the URL, then approve access in the browser window that opens.

TEXT

```
https://mcp.alterlab.io/mcp
```

### Local (npx) — config file location

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

### Local (npx) — add to config

JSON

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

Restart required for local config

Quit and reopen Claude Desktop after editing the config file for the local 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`.

### Recommended — connect by URL

JSON

```
// ~/.cursor/mcp.json (or .cursor/mcp.json in a project)
{
  "mcpServers": {
    "alterlab": {
      "url": "https://mcp.alterlab.io/mcp"
    }
  }
}
```

Cursor opens the AlterLab sign-in window the first time it connects. No API key is stored in the file, so it is safe to commit.

### Local (npx) — .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.

Local (npx): 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
```

### Recommended — connect by URL

JSON

```
// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "alterlab": {
      "serverUrl": "https://mcp.alterlab.io/mcp"
    }
  }
}
```

Refresh MCP servers in Cascade, then sign in to AlterLab in the browser window that opens.

### Local (npx) — 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. These examples run the local npm package.

### 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. These examples run the local npm package.

### ~/.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 AlterLab tools are visible (25 available).

## 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

1. Call `alterlab_list_sessions` to see if a session for the target domain already exists.
2. If no session exists, call `alterlab_create_session` with the domain and cookies extracted from your browser.
3. Pass the `session_id` to `alterlab_scrape` or `alterlab_extract` to make authenticated requests.
4. 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 get up to 5,000 free requests, 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 | Enhanced | $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.

Up to 5,000 free requests

New accounts get a one-time free starter balance with no credit card required: about 5,000 direct fetch, 500 managed sessions or 250 full browser rendering requests, to explore the platform before committing. [Create a free account](https://alterlab.io/auth/register).

Open Source

The MCP server is open source. Star us on [GitHub](https://github.com/RapierCraft/alterlab-mcp-server) and contribute — issues and PRs welcome.

[Overview](https://alterlab.io/docs/integrations)[n8n Node](https://alterlab.io/docs/integrations/n8n)

Last updated: June 2026