# 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).
## Getting started
Before setting up the integration, ensure you have:
1. **Oxylabs account**: get your username and password for the Oxylabs Headless Browser.
{% 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 `` and `` with your actual Oxylabs credentials:
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://:@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://:@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.
{% 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://:@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://:@ubc.oxylabs.io/?bargs=force-color-profile:srgb&bargs=window-position:100,100"
]
}
```
Supported arguments include:
* `force-color-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:,,`: 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developers.oxylabs.io/scraping-solutions/headless-browser/integration-with-mcp.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
