Integration with MCP

Headless Browser can be used with MCP, enabling AI systems to control remote browsers. Learn more about this integration.

This guide explains how to integrate Oxylabs Headless Browser with MCP (Model Context Protocol) to enable AI systems to interact with and control remote browsers.

Visit the Oxylabs GitHub repository for a complete working example of MCP integration with the Oxylabs Headless Browser.

Overview

Model Control Protocol (MCP) allows AI systems like Claude to interact with browsers and perform web-based tasks. By integrating Oxylabs Headless Browser with MCP, you can implement AI systems to perform web navigation, data retrieval, and automation tasks using remote browsers with advanced autonomous navigation capabilities and Residential Proxy integration.

The MCP host (such as Claude Desktop or Cursor) 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.

For now, you can get the Headless Browser via our sales at [e-mail].

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

• Windows: download and install from nodejs.org
• macOS: use Homebrew (brew install node) or download from nodejs.org
• Linux:

  • Ubuntu/Debian: sudo apt update && sudo apt install nodejs npm
  • Fedora: sudo dnf install nodejs npm
  • Or download from nodejs.org

1. MCP Host: either Claude Desktop or Cursor installed.

Configure MCP server

Create an MCP server configuration section with your Oxylabs credentials. Replace USERNAME and PASSWORD with your actual Oxylabs credentials:

"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://USERNAME:[e-mail]"
  ]
}

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:

"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://USERNAME:[e-mail]?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.

You can find the list of ISO-3166 country codes here.

You can also use p_state or p_city for state (US) or city-level targeting or use sticky residential proxies for finer exit IP control. Learn more here.

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