# Integration with MCP

This guide explains how to integrate [**Oxylabs Headless Browser**](https://oxylabs.io/products/headless-browser) with MCP (Model Context Protocol) to enable AI systems to interact with and control remote browsers.

{% hint style="success" %}
Visit the Oxylabs GitHub repository for a complete working example of [**MCP integration with the Oxylabs Headless Browser**](https://github.com/oxylabs/oxylabs-hb-mcp)**.**
{% endhint %}

## Overview

Model Control Protocol (MCP) allows AI systems like Claude to interact with browsers and perform web-based tasks. By integrating [**Oxylabs Headless Browser**](https://oxylabs.io/products/unblocking-browser) with MCP, you can leverage AI systems to perform **web navigation, data retrieval, and automation** tasks using remote browsers with advanced stealth capabilities and [**Residential Proxy**](https://oxylabs.io/products/residential-proxy-pool) integration.

The MCP host (such as [**Claude Desktop**](https://claude.ai/download) or [**Cursor**](https://www.cursor.com/)) comes with a built-in MCP client. Playwright-MCP acts as an MCP server, and instead of using a local browser, it connects to Headless Browser via a secure WebSocket connection (WSS).

<figure><img src="https://63892162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FzUoGJVOHkxw5QSB9VvQF%2FMCP%20and%20UB%20integration%20scheme.png?alt=media&#x26;token=20fa95e8-0fd7-4ad3-8b3f-becc97bac3d5" alt=""><figcaption></figcaption></figure>

## Getting started

Before setting up the integration, ensure you have:

1. **Oxylabs account**: get your username and password for the Oxylabs Headless Browser.&#x20;

{% hint style="info" %}
For now, you can get the Headless Browser via our sales at [**hello@oxylabs.io**](mailto:hello@oxylabs.io)**.**
{% endhint %}

2. **Node.js**: version 18.0.0 or higher (includes npm/npx)

* **Windows**: download and install from [**nodejs.org**](https://nodejs.org/)
* **macOS**: use Homebrew (`brew install node`) or download from [**nodejs.org**](https://nodejs.org/)
* **Linux**:
  * Ubuntu/Debian: `sudo apt update && sudo apt install nodejs npm`
  * Fedora: `sudo dnf install nodejs npm`
  * Or download from [**nodejs.org**](https://nodejs.org/)

3. **MCP Host**: either Claude Desktop or Cursor installed.

## Configure MCP server

Create an MCP server configuration block with your Oxylabs credentials. Replace `<username>` and `<password>` with your actual Oxylabs credentials:

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs.oxylabs.io"
  ]
}
```

### Option 1: integration with Cursor

1. Open Cursor
2. Open Cursor settings
3. Select MCP
4. Add the prepared MCP server configuration
5. Restart Cursor

### Option 2: integration with Claude Desktop

1. Open Claude Desktop
2. Open Claude Desktop settings
3. Navigate to Developer
4. Press Edit Config
5. Edit the `claude_desktop_config.json` file
6. Add the prepared MCP server configuration
7. Restart Claude Desktop

## Advanced configuration options

### Country selection

You can specify a country for your browser session by adding the `?p_cc` parameter to your connection URL:

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs.oxylabs.io?p_cc=US"
  ]
}
```

Replace `US` with your desired SO-3166 country code. If no country is specified, the system will automatically assign one based on availability.&#x20;

{% hint style="success" %}
You can find the list of **ISO-3166 country codes** [**here**](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
{% endhint %}

### US-based infrastructure

For users primarily operating in the US, you can connect directly to US-based infrastructure for faster loading times:

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs-us.oxylabs.io"
  ]
}
```

{% hint style="warning" %}
This solution primarily shortens the response time for US-based users and should not be confused with proxy geo-location selection.
{% endhint %}

### Browser arguments (Chrome only)

For Chrome-based Headless Browser, you can specify additional browser arguments using the `bargs` parameter:

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc.oxylabs.io/?bargs=force-color-profile:srgb&bargs=window-position:100,100"
  ]
}
```

Supported arguments include:

* `force-color-profile:<profile>`: Force all monitors to be treated as though they have the specified color profile
* `window-position:X,Y`: Specifies the initial window position
* `hide-scrollbars`: Prevents creating scrollbars for web content
* `enable-features:<feature1>,<feature2>,<feature3>`: Comma-separated list of feature names to enable
* `disable-notifications`: Disables the Web Notification and the Push APIs

## Troubleshooting

If you encounter issues with the integration:

1. **Connection problems**:
   * Verify your Oxylabs credentials
   * Check your network connection
   * Ensure firewalls are not blocking WebSocket connections
2. **Performance issues**:
   * For US-based users, try the US-specific endpoints
   * Increase timeouts in your configuration if needed
3. **Browser not loading**:
   * Check Node.js version (must be 18.0.0 or higher)
   * Verify that npx is properly installed
   * Restart the MCP host application