> 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 three products:

<table><thead><tr><th width="211">Product</th><th>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>Hosted or local</td></tr><tr><td><a href="#agent-browser">Agent Browser</a></td><td><code>hb-mcp</code></td><td>Local</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 through its self-hosted MCP server `oxylabs-web-api-mcp`, to search the web, read pages as Markdown, extract fields as JSON, and call dedicated scrapers. You can find all details in the [Web API MCP GitHub repository](https://github.com/oxylabs/web-api-mcp).

### Prerequisites

•       Web API key:  From the Web API instance and generate an API key from the [dashboard](https://dashboard.oxylabs.io/).

•       [**`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 – <code>url</code>, <code>format</code>, <code>location</code>, <code>device</code>, <code>run_js</code></td></tr><tr><td><code>extract</code></td><td>Named fields off a page as JSON – <code>url</code>, <code>prompt</code>, <code>location</code>, <code>run_js</code></td></tr><tr><td><code>check_scrape</code></td><td>Collect a JavaScript-rendering job – <code>job_id</code></td></tr><tr><td><code>read_scraped</code></td><td>Read a large page that was offloaded to disk, in chunks</td></tr><tr><td><code>list_scrapers</code></td><td>List implemented scrape endpoints, or describe one – <code>endpoint</code></td></tr><tr><td><code>scrape_target</code></td><td>Call a target-specific endpoint – <code>endpoint</code>, <code>params</code></td></tr></tbody></table>

### Installation

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

Then point your client at the `oxylabs/web-api-mcp` binary.&#x20;

<details>

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

```bash
claude mcp add oxylabs-web-api -- oxylabs-web-api-mcp
```

</details>

<details>

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

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

</details>

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

#### Self-hosted 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 spends its key: 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).

### Configuration

<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_RATE_LIMIT</code></td><td>Caps the server's spend, e.g. <code>100/1h</code>.</td><td>Off</td></tr><tr><td><code>OXYLABS_EXTRACT_APPROVAL</code></td><td>Set to <code>0</code> to skip the approval prompt for structured extraction.</td><td>1</td></tr><tr><td><code>OXYLABS_MAX_INLINE_TOKENS</code></td><td>Pages above this size are saved to disk (local) or truncated (<code>HTTP</code>).</td><td>10000</td></tr><tr><td><code>OXYLABS_TIMEOUT</code></td><td>Request timeout, in seconds.</td><td>120</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></tbody></table>

## 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 all three 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": "WEB_API_KEY"
      }
    },
    "oxylabs_headless_browser": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://HB_USERNAME:HB_PASSWORD@hb.oxylabs.io"
      ]
    }
  }
}

```

</details>

## Verify the setup

1. Check that your servers appear as enabled in your client's MCP list (in Claude Code, run `/mcp`).
2. Send a test prompt for each product you set up, and approve the tool call if prompted.

## 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.</td></tr><tr><td>Tools appear, but calls fail</td><td>Check for placeholder credentials, an incorrect Base64 value, or credentials from the wrong product.</td></tr><tr><td>Hosted server won't connect</td><td>Your client may not support custom headers. Use the local method.</td></tr><tr><td><code>uvx</code>, <code>npx</code>, or <code>oxylabs-web-api-mcp</code>: command not found</td><td>Install <code>uv</code> or Node.js 18.0.0+ (and the Web API server, if needed) and make sure it's 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.