> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/ai-workflows/mcp.md).

# Model Context Protocol (MCP)

Use Oxylabs MCP to give AI assistants live web scraping, search, and extraction tools via Oxylabs products.

Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data. With Oxylabs MCP integrations, assistants such as [Claude](https://claude.ai/) and [Cursor](https://www.cursor.com/) can access live web data – scrape pages, search the web, crawl sites, and control remote browsers.

Oxylabs offers MCP integrations for two products:

<table><thead><tr><th width="136">Product</th><th width="183">MCP server</th><th>Setup</th></tr></thead><tbody><tr><td><a href="#web-api">Web API</a></td><td><code>oxylabs-web-api-mcp</code></td><td>Remote (hosted by Oxylabs) or self-hosted (run by you)</td></tr><tr><td><a href="#agent-browser">Agent Browser</a></td><td><code>hb-mcp</code></td><td>Self-hosted</td></tr></tbody></table>

{% hint style="info" %}
**Note:** Each product has its own MCP server and credentials. Set up only the ones you need – they can also be combined.
{% endhint %}

## Web API

Connect Web API to your AI agent to search the web, scrape pages in the format of your choice, extract fields as JSON, and call dedicated scrapers – all through one MCP connection. You can find all details in the [Web API MCP GitHub repository](https://github.com/oxylabs/web-api-mcp).

You can connect in two ways:

* [**Remote MCP**](#option-1-remote-mcp) – connect to the server hosted and maintained by Oxylabs. There is nothing to install or update.
* [**Self-hosted MCP**](#option-2-self-hosted-mcp) – deploy and manage the server in your own environment for more control.

<table><thead><tr><th width="160"></th><th width="288">Remote MCP</th><th>Self-hosted MCP</th></tr></thead><tbody><tr><td><strong>Server runs on</strong></td><td>Oxylabs infrastructure</td><td>Your machine or infrastructure</td></tr><tr><td><strong>Setup</strong></td><td>Add the server URL and your API key to your client</td><td>Install <code>uv</code>, Python, and the server, then configure your client</td></tr><tr><td><strong>Updates and maintenance</strong></td><td>Managed by Oxylabs</td><td>Managed by you</td></tr><tr><td><strong>Server settings</strong></td><td>Managed by Oxylabs</td><td>Configurable with environment variables</td></tr><tr><td><strong>Best for</strong></td><td>The quickest way to give a compatible agent access to Web API</td><td>Full control over the environment, or clients that can't connect to remote servers with a custom header</td></tr></tbody></table>

### Requirements

* **Web API key:** in the [Oxylabs dashboard](https://dashboard.oxylabs.io/), create a Web API product instance, open it, and copy the API key shown at the top of the instance page.
* **For remote MCP:** An MCP client that supports remote (HTTP) MCP servers with custom headers, such as Claude Code, Codex, Cursor, etc.
* **For self-hosted MCP:** [**`uv`**](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10 or higher.

### Available tools

<table><thead><tr><th width="188.30078125">Tool</th><th>What it does</th></tr></thead><tbody><tr><td><code>search</code></td><td>Search the live web – <code>query</code>, <code>max_results</code>, <code>location</code></td></tr><tr><td><code>scrape</code></td><td>Read one URL, Markdown by default, or return named fields as JSON – <code>url</code>, <code>format</code>, <code>location</code>, <code>device</code>, <code>run_js</code>, <code>json_prompt</code>, <code>json_schema</code></td></tr><tr><td><code>scrape_target</code></td><td>Call a target-specific scraper – <code>endpoint</code>, <code>params</code>, <code>structured</code>, <code>parser</code>, <code>json_prompt</code>, <code>json_schema</code></td></tr><tr><td><code>list_scrapers</code></td><td>List available scrape endpoints, or describe one – <code>endpoint</code></td></tr><tr><td><code>check_scrape</code></td><td>Collect a queued job, such as a JavaScript-rendering scrape – <code>request_id</code></td></tr><tr><td><code>read_scraped</code></td><td>Read a large page that was offloaded to disk, in chunks – only when the server runs locally (stdio)</td></tr></tbody></table>

{% hint style="info" %}
**Note:** All tools are read-only, so many clients can run them without asking for approval.
{% endhint %}

### Option 1: Remote MCP

Connect your client to the Oxylabs-hosted server:

```
https://mcp.oxylabs.io/web-api-mcp
```

The server authenticates each request with your Web API key, sent as an `Authorization: Bearer` header.

Set your API key as an environment variable in the terminal where you will run your client:

```bash
export OXYLABS_WEB_API_KEY="your_api_key_here"
```

Then add the server to your client:

{% tabs %}
{% tab title="Claude Code" icon="claude" %}

```bash
claude mcp add --transport http --scope user oxylabs-web-api \
  https://mcp.oxylabs.io/web-api-mcp \
  --header "Authorization: Bearer ${OXYLABS_WEB_API_KEY}"
```

`--scope user` makes the server available in all your projects. Make sure `OXYLABS_WEB_API_KEY` is set in the environment where you start Claude Code.
{% endtab %}

{% tab title="ChatGPT/Codex" icon="openai" %}

```bash
codex mcp add oxylabs-web-api \
  --url https://mcp.oxylabs.io/web-api-mcp \
  --bearer-token-env-var OXYLABS_WEB_API_KEY
```

Codex reads the key from the `OXYLABS_WEB_API_KEY` environment variable, so it must be set in the environment where you start Codex.
{% endtab %}

{% tab title="Cursor (+ others)" icon="cursor" %}
For any client that supports remote MCP servers with custom headers, add the server URL and an `Authorization` header to the client's MCP configuration. For example, in Cursor's `mcp.json`:

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "url": "https://mcp.oxylabs.io/web-api-mcp",
      "headers": {
        "Authorization": "Bearer ${env:OXYLABS_WEB_API_KEY}"
      }
    }
  }
}
```

Field names can differ between clients – check your client's documentation for how to add a remote MCP server with headers.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Important:** Your API key grants access to your Web API usage. Don't commit config files that include it, and use environmental variables where your client supports them.
{% endhint %}

{% hint style="info" %}
**Note:** Clients that only support OAuth sign-in for remote servers, such as custom connectors in the claude.ai web interface, can't send custom headers and can't connect to the Remote MCP server. Use the self-hosted option with those clients instead.
{% endhint %}

### Option 2: Self-hosted MCP

{% hint style="info" %}
**Note:** Remote and self-hosted commands on this page use the same server name, `oxylabs-web-api`. If you switch from one option to the other, remove the existing server from your client first.
{% endhint %}

Self-host your Web API MCP server as either **Local (stdio)** process or a **Shared Server (HTTP)**:

{% tabs %}
{% tab title="Local (stdio)" %}

```bash
uv tool install git+https://github.com/oxylabs/web-api-mcp
```

Then point your client at the `oxylabs-web-api-mcp` command. The source is available in the [Web API MCP GitHub repository](https://github.com/oxylabs/web-api-mcp).

<details>

<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add oxylabs-web-api \
  --env OXYLABS_WEB_API_KEY='${OXYLABS_WEB_API_KEY}' \
  -- oxylabs-web-api-mcp
```

</details>

<details>

<summary><strong>Claude Desktop</strong></summary>

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_ENV_FILE": "/absolute/path/to/.env" }
    }
  }
}
```

</details>

<details>

<summary><strong>Cursor</strong></summary>

{% code overflow="wrap" expandable="true" %}

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_WEB_API_KEY": "${env:OXYLABS_WEB_API_KEY}" }
    }
  }
}
```

{% endcode %}

</details>

The agent skill is already built into the server. If you prefer to manage skills separately, Claude Code can instead take the [skills](https://github.com/oxylabs/web-api-skills) repository as a plugin, which wires this server and the skills together:

```bash
/plugin marketplace add oxylabs/web-api-skills
/plugin install oxylabs-web-api
```

{% endtab %}

{% tab title="Shared server (HTTP)" %}
Run one shared server for a team, or for agents that can't start local processes:

```bash
export OXYLABS_WEB_API_KEY=WEB_API_KEY
export MCP_ALLOWED_HOSTS='mcp.internal.example.com,localhost:*'
oxylabs-web-api-mcp --transport http --host 0.0.0.0 --port 8080
```

{% hint style="warning" %}
**Important:** `MCP_ALLOWED_HOSTS` is required – list the hostname clients connect to, or every request is rejected with `421 Misdirected Request`. The server has no authentication of its own, so anyone who can reach it can spend the key set in its environment: keep it behind a VPN or an authenticated ingress, never on the public internet.
{% endhint %}

The endpoint is `http://<host>:8080/mcp`. Callers can send their own key in an `Authorization: Bearer` header. Otherwise, the server uses `OXYLABS_WEB_API_KEY`.

A `Dockerfile` is also available in the [repository](https://github.com/oxylabs/web-api-mcp). To run the server with Docker:

{% code overflow="wrap" expandable="true" %}

```bash
docker build -t oxylabs-web-api-mcp .
docker run --rm -p 8080:8080 \
  -e OXYLABS_WEB_API_KEY \
  -e MCP_ALLOWED_HOSTS='localhost:*,mcp.internal.example.com' \
  oxylabs-web-api-mcp
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Self-hosted MCP configuration

<details>

<summary><strong>Configuration variables table</strong></summary>

<table><thead><tr><th width="231.22265625">Variable</th><th width="413.6328125">Description</th><th>Default value</th></tr></thead><tbody><tr><td><code>OXYLABS_WEB_API_KEY</code></td><td>Web API key, sent as <code>Authorization: Bearer &#x3C;key></code>. Required on stdio. Over HTTP, a per-request <code>Authorization</code> header takes precedence.</td><td>–</td></tr><tr><td><code>OXYLABS_BASE_URL</code></td><td>Overrides the API base URL, for example to go through a proxy.</td><td><code>https://webapi.oxylabs.io</code></td></tr><tr><td><code>OXYLABS_RETRIES</code></td><td>Retries on temporary errors (<code>429</code>, <code>500</code>, <code>502</code>, <code>503</code>, <code>504</code>).</td><td>2</td></tr><tr><td><code>OXYLABS_RATE_LIMIT</code></td><td>Caps the server's spend, e.g. <code>100/1h</code> or <code>50/30m</code>.</td><td>Off</td></tr><tr><td><code>OXYLABS_MAX_INLINE_TOKENS</code></td><td>Content above this size, in tokens, is saved to disk (stdio) or truncated (HTTP).</td><td>10000</td></tr><tr><td><code>OXYLABS_SPILL_DIR</code></td><td>Where saved pages are written (stdio only).</td><td>System temp directory</td></tr><tr><td><code>OXYLABS_SPILL</code></td><td>Set to <code>0</code> to keep all content inline, even on stdio.</td><td>1</td></tr><tr><td><code>MCP_TRANSPORT</code></td><td><code>stdio</code> or <code>http</code>.</td><td><code>stdio</code></td></tr><tr><td><code>HOST</code> / <code>PORT</code></td><td>HTTP bind address.</td><td><code>127.0.0.1</code> / <code>8080</code></td></tr><tr><td><code>MCP_ALLOWED_HOSTS</code></td><td>Comma-separated <code>Host</code> allowlist (HTTP only).</td><td><code>localhost:*,127.0.0.1:*</code></td></tr><tr><td><code>MCP_ALLOWED_ORIGINS</code></td><td>Comma-separated <code>Origin</code> allowlist for browser clients (HTTP only).</td><td>Empty</td></tr></tbody></table>

{% hint style="info" %}
On `stdio`, the server also reads `OXYLABS_*` variables from a `.env` file in its working directory, or from the file set in `OXYLABS_ENV_FILE`. Variables already set in the environment take precedence. The API key is read at request time and is never written to disk or logged.
{% endhint %}

</details>

## Agent Browser

Connect Agent Browser through its MCP server `hb-mcp`, to let your assistant open remote browsers, navigate pages, interact with elements, and collect content using advanced autonomous navigation capabilities and [**Residential Proxy**](https://oxylabs.io/products/residential-proxy-pool) integration. You can find all details in the [Agent Browser MCP GitHub repository](https://github.com/oxylabs/oxylabs-ab-mcp).

### Available tools

`hb_connect` returns a session label that you pass to the other tools, so you can run several sessions in parallel. Sessions last up to 1 hour and count toward your concurrent session limit until closed.

<table><thead><tr><th width="227">Tool</th><th>What it does</th></tr></thead><tbody><tr><td><code>hb_connect</code></td><td>Open a session – accepts Agent Browser parameters such as <code>p_cc</code>, <code>p_device</code>, <code>p_src</code>, <code>p_fp_tag</code>, <code>session_name</code>, <code>o_profile</code>, <code>record</code>, <code>page_handler</code></td></tr><tr><td><code>hb_disconnect</code></td><td>Close one session, or all sessions</td></tr><tr><td><code>hb_session_info</code></td><td>List open sessions, or show the details of one</td></tr><tr><td><code>hb_page_status</code>,<br><code>hb_page_handle</code>,<br><code>hb_classify_page</code></td><td>Work with the Page Handler: read page status, handle a challenge that appeared after page load (<code>hb_page_handle</code> requires <code>page_handler=true</code>), classify the current page</td></tr><tr><td><code>hb_sessions_list</code>,<br><code>hb_session_stop</code></td><td>List and stop live sessions on your account</td></tr><tr><td><code>hb_recordings_list</code>,<br><code>hb_recording_url</code>,<br><code>hb_recording_delete</code></td><td>Manage session recordings</td></tr><tr><td><code>hb_profiles_list</code>,<br><code>hb_profile_delete</code></td><td>Manage persistent profiles</td></tr><tr><td><code>hb_reference</code></td><td>Return the parameter and error reference</td></tr><tr><td><code>browser_navigate</code></td><td>Open a URL</td></tr><tr><td><code>browser_snapshot</code></td><td>Read the page content</td></tr><tr><td><code>browser_click</code></td><td>Click an element from the snapshot</td></tr><tr><td><code>browser_type</code>,<br><code>browser_fill_form</code></td><td>Type into one field, or fill several form fields</td></tr><tr><td><code>browser_take_screenshot</code></td><td>Capture a screenshot</td></tr><tr><td><code>browser_close</code></td><td>Close the session</td></tr><tr><td>Other <code>browser_*</code> tools</td><td>Tabs, hovering, key presses, waiting, file upload, PDF export, and more</td></tr></tbody></table>

### Prerequisites

* Agent Browser `username` and `password` from the [Oxylabs dashboard](https://dashboard.oxylabs.io/).
* [Node.js](https://nodejs.org/) 20.0.0 or higher and `git`.

### Installation

Install the server from GitHub, as it is not published to the `npm` registry:

{% code expandable="true" %}

```
npm install -g github:oxylabs/oxylabs-ab-mcp
```

{% endcode %}

Then point your client at the `hb-mcp` binary:

<details>

<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add oxylabs-agent-browser \
  -e OXY_HB_USERNAME="USERNAME" \
  -e OXY_HB_PASSWORD="PASSWORD" \
  -- hb-mcp
```

</details>

<details>

<summary><strong>Claude Desktop or Cursor</strong></summary>

Add this to your `claude_desktop_config.json` or `.mcp.json` file:

```json
{
  "mcpServers": {
    "oxylabs-agent-browser": {
      "command": "hb-mcp",
      "env": {
        "OXY_HB_USERNAME": "USERNAME",
        "OXY_HB_PASSWORD": "PASSWORD"
      }
    }
  }
}
```

</details>

To skip the global install, use `npx -y github:oxylabs/oxylabs-ab-mcp` as the command instead of `hb-mcp`. Startup is slower.

#### Location selection

Ask your assistant to open the browser in a specific country with `p_cc` parameter, or set a default for every session with the `--default-params` argument:

```json
"oxylabs-agent-browser": {
  "command": "hb-mcp",
  "args": ["--default-params", "p_cc=US"],
  "env": {
    "OXY_HB_USERNAME": "USERNAME",
    "OXY_HB_PASSWORD": "PASSWORD"
  }
}
```

To choose the browser's location options, visit the [Geolocation & Proxy Selection](/products/agent-browser/geolocation-and-proxy-selection.md) page. If you don't specify a location, one is assigned automatically based on availability.

## Use multiple products together

You can run both servers in the same client. Combine their entries under one `mcpServers` object.

<details>

<summary>Example</summary>

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_WEB_API_KEY": "${env:OXYLABS_WEB_API_KEY}" }
    },
    "oxylabs-agent-browser": {
      "command": "hb-mcp",
      "env": {
        "OXY_HB_USERNAME": "${env:OXY_HB_USERNAME}",
        "OXY_HB_PASSWORD": "${env:OXY_HB_PASSWORD}"
      }
    }
  }
}
```

To use the Remote MCP server for Web API instead, replace the `oxylabs-web-api` entry with the remote entry from [Option 1](#option-1-remote-mcp), in a client that supports remote servers with headers.

</details>

## Verify the setup

1. Check that your servers appear as enabled in your client's MCP list (in Claude Code, run `/mcp`, or in Codex, run `codex mcp list`).
2. Send a test prompt for each product you set up, and approve the tool call if prompted (e.g. `Search the web for "oxylabs" and show the top 3 results.`).

{% hint style="success" %}
**Note:** A server can appear connected and list its tools even when the API key is missing or incorrect. The key is checked when a tool runs, so only a test prompt confirms that your setup works.
{% endhint %}

## Troubleshooting

<table><thead><tr><th width="341.37109375">Issue</th><th>Solution</th></tr></thead><tbody><tr><td>Server doesn't appear in the client</td><td>Make sure the JSON is valid, then restart the app. If you used a command, run it again and check the server list.</td></tr><tr><td>Server is connected and tools are listed, but tool calls fail</td><td>The API key is checked only when a tool runs. Check that the key is correct and that you're using credentials for the right product: Web API uses an API key, and Agent Browser uses a username and password.</td></tr><tr><td><code>Authentication failed (401)</code></td><td>The Web API key is invalid. Copy it again from the top of your Web API instance in the <a href="https://dashboard.oxylabs.io/">dashboard</a>.</td></tr><tr><td rowspan="2">Message that no Web API key was provided</td><td>Remote MCP: the <code>Authorization</code> header is missing, or <code>OXYLABS_WEB_API_KEY</code> is empty in the environment where you started the client – set it, then restart the client. </td></tr><tr><td>Self-hosted: the key isn't set in the server's environment.</td></tr><tr><td>Remote MCP server won't connect, or your client has no way to set a header</td><td>Your client may support only OAuth sign-in for remote servers or not support custom headers. Use the <a href="#option-2-self-hosted-mcp">self-hosted</a> option instead.</td></tr><tr><td>Page content is cut off</td><td>Pages above the token limit are truncated when the server runs over HTTP, which includes Remote MCP. Request only the data you need with <code>json_prompt</code>, or run the self-hosted server locally (<code>stdio</code>), which saves large pages to disk so the agent can read them in chunks.</td></tr><tr><td><code>oxylabs-web-api-mcp</code>: command not found (self-hosted)</td><td>Install <code>uv</code> and Python 3.10 or higher, install the server, and make sure the <code>uv</code> tool directory is on your <code>PATH</code> (<code>uv tool update-shell</code>).</td></tr><tr><td><code>421 Misdirected Request</code> (self-hosted HTTP server)</td><td>Add the hostname clients connect to in <code>MCP_ALLOWED_HOSTS</code>.</td></tr><tr><td><code>hb-mcp</code> or <code>npx</code>: command not found</td><td>Install <a href="https://nodejs.org/">Node.js</a> 20.0.0 or higher and <code>git</code>, and make sure they are on your <code>PATH</code>.</td></tr><tr><td>Agent Browser won't connect</td><td>Verify your credentials and make sure your firewall isn't interfering with WebSocket connections.</td></tr><tr><td>Cursor menus look different</td><td>Edit <code>mcp.json</code> directly – menu labels can change between Cursor versions. Check logs in <strong>Output → MCP Logs</strong>.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/ai-workflows/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.