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

Let your agent set it up

Paste this prompt into Claude Code, Cursor, Codex, Windsurf or any coding agent. It reads /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.

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.

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 mcp add --transport http alterlab https://mcp.alterlab.io/mcp

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

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

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

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.

npm install -g alterlab-mcp-server

npx -y alterlab-mcp-server

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.

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.

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

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

export ALTERLAB_API_KEY=sk_live_your_key_here

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

Claude Desktop

Add AlterLab as a custom connector, or run the npm package locally through the mcpServers block in your Claude Desktop config file.

https://mcp.alterlab.io/mcp

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

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 (or .cursor/mcp.json in a project)
{
  "mcpServers": {
    "alterlab": {
      "url": "https://mcp.alterlab.io/mcp"
    }
  }
}

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

Windsurf

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

~/.codeium/windsurf/mcp_config.json

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

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

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.

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

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

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.

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

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.

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.

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.