How to Use Browser Use MCP

Browser Use Cloud MCP connects an MCP client to a hosted browser through https://api.browser-use.com/v3/mcp. You authenticate with a Browser Use API key in the x-browser-use-api-key header, add the server using the configuration format required by your client, and then use session tools such as run_session, get_session, and send_task.

Browser Use Cloud MCP is separate from Microsoft Playwright MCP and the browsermcp.dev project. Use the hosted Browser Use endpoint and its API-key setup described here; do not substitute another project’s installation instructions.

What you need before starting

• An account with Browser Use and an API key from its account settings.
• An MCP client that supports remote HTTP MCP connections, such as Claude Code, Claude Desktop, Cursor, or Windsurf.
• A secure place to store the key. Never commit it to a repository or paste it into a shared configuration file.

The official setup guide is the source of truth for current endpoint, authentication, and client syntax: Browser Use Cloud MCP guide.

1. Get your Browser Use API key

1. Sign in to Browser Use.
2. Open account settings.
3. Create or copy an API key.
4. Keep the value available as a secret for your MCP client.

The key is sent in a header named x-browser-use-api-key. The endpoint is:

https://api.browser-use.com/v3/mcp

2. Configure your MCP client

Claude Desktop or Cursor

These clients use an mcpServers object with url and headers. Add a server entry to the configuration file documented by your client:

{
  "mcpServers": {
    "browser-use": {
      "url": "https://api.browser-use.com/v3/mcp",
      "headers": {
        "x-browser-use-api-key": "YOUR_API_KEY"
      }
    }
  }
}

This is an example matching the official Claude Desktop and Cursor format. It is not a universal configuration schema. Replace YOUR_API_KEY through your secret-management process, then restart or reload the client if required.

Claude Code

Claude Code’s example uses an HTTP MCP connection and passes the API key as the x-browser-use-api-key header. Use the add-server command shown in the current Claude Code and Browser Use documentation, substituting your key:

claude mcp add --transport http browser-use https://api.browser-use.com/v3/mcp \
  --header "x-browser-use-api-key: YOUR_API_KEY"

Command-line flags can change between Claude Code releases. If this command is rejected, open Claude Code’s current MCP configuration help and apply the same endpoint and header values using its documented syntax.

Windsurf

Windsurf’s example uses serverUrl rather than the url field shown above:

{
  "mcpServers": {
    "browser-use": {
      "serverUrl": "https://api.browser-use.com/v3/mcp",
      "headers": {
        "x-browser-use-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Follow Windsurf’s documented configuration location and schema. Do not paste the Claude Desktop or Cursor object into Windsurf if its version expects a different wrapper.

3. Confirm that the server connected

1. Restart or reload the MCP client after saving its configuration.
2. Open the client’s MCP or tools view.
3. Check that a Browser Use server appears and that its tools are listed.
4. Run a small, non-sensitive task before attempting an authenticated workflow.

If the server is listed but no tools appear, inspect the client logs and verify the URL, header spelling, and JSON structure. Client configuration syntax is not interchangeable.

Browser Use MCP tools

The guide lists session-oriented tools. Availability and parameters can change, so inspect the tool schema exposed by your client before constructing a call.

Tool	Purpose	Typical use
run_session	Create a session and run a task.	Start a new browser task. Listed options include keep_alive, model selection, an output schema, and a browser profile ID.
get_session	Poll session status and output.	Read status, step count, cost breakdown, and live URL while a session runs.
send_task	Send a follow-up task to an idle keep-alive session.	Continue work without creating a new session.
stop_session	Stop a task or destroy the sandbox, depending on the selected strategy.	End work and release the session.
get_session_messages	Retrieve agent messages.	Inspect browser actions, reasoning, and results.
list_sessions	List recent sessions.	Review session status and cost information.
list_browser_profiles	List browser profiles.	Choose a profile for authenticated tasks when your account has profiles configured.

Running a first session

After the tools appear, ask your assistant to call run_session with a narrowly scoped task, such as opening a public page and extracting its title. Let the client generate the tool call from the schema it received. A useful task specifies the URL, the desired action, and the expected output:

Open https://example.com, report the page title, and return only JSON with a title field.

For a long workflow, request keep_alive when supported. Poll the returned session with get_session, send additional work with send_task once it is idle, and use stop_session when the workflow is complete.

Authenticated tasks and browser profiles

Use list_browser_profiles to discover profiles available to your account, then select the appropriate profile in run_session when the tool schema exposes a browser profile ID. Keep authentication data out of prompts and source control. Test with a least-privilege account and stop sessions that no longer need access.

Common errors and fixes

Symptom	Likely cause	Fix
Connection refused or server unavailable	Wrong endpoint, network policy, or a temporary service issue.	Verify the exact https://api.browser-use.com/v3/mcp URL, check outbound HTTPS access, and retry from the client.
Unauthorized or authentication error	The key is missing, expired, mistyped, or sent under the wrong header.	Set x-browser-use-api-key exactly, generate a replacement key in account settings if needed, and remove whitespace around the value.
JSON configuration parse error	Trailing commas, wrong nesting, or an unescaped key.	Validate the JSON and compare the structure with the client-specific example.
Server connects but tools are absent	The client did not reload, or the server entry uses an unsupported schema.	Restart the client, inspect MCP logs, and use the configuration convention documented for that client.
Windsurf rejects url	Windsurf’s example expects serverUrl.	Use the Windsurf variant with serverUrl.
Follow-up task fails	send_task was called while the session is still busy or it was not kept alive.	Poll with get_session, wait for an idle state, and ensure keep_alive was requested when needed.
Unexpected session cost information	The tool reports a cost breakdown, but the setup page does not publish a price schedule or quota.	Use the account’s current billing information and do not infer prices from the tool output.

Reliability, performance, and cost considerations

• Reuse an idle keep-alive session for related steps when appropriate instead of starting a separate session for every follow-up.
• Poll session state with get_session and stop abandoned sessions with stop_session.
• Keep tasks specific and define the expected output schema to reduce unnecessary browser actions and parsing.
• Use browser profiles deliberately for authenticated work and avoid sharing a profile across unrelated workflows.
• The reviewed Browser Use setup page lists cost breakdowns in session output but does not state current pricing, quotas, eligibility rules, retention policy, or privacy guarantees. Check current account documentation before estimating spend or making a data-handling promise.

Do not confuse Browser Use MCP with similarly named projects

Project	Connection model	Documented setup
Browser Use Cloud MCP	Hosted remote MCP endpoint.	https://api.browser-use.com/v3/mcp with an x-browser-use-api-key header; session-management tools.
Microsoft Playwright MCP	Locally launched server.	The official repository documents npx @playwright/mcp@latest and structured accessibility snapshots, plus browser and profile options.
Browser MCP	Extension-backed setup.	The installation guide documents a Chrome extension and a VS Code configuration using @agent360/browser-mcp@latest.

These products have different endpoints, authentication, and operation models. Follow the documentation for the project you actually selected.

Or skip the browser setup

If your goal is a clean website screenshot rather than interactive browser automation, ScreenshotNeo provides a single HTTP request for PNG, JPEG, WebP, or PDF output. Its capture pipeline accepts cookie and consent banners, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each cleanup step off.

Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response reports the result in X-Page-Verdict and X-Billed headers. ScreenshotNeo also includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options. This is the smallest working request:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Features include full-page capture with lazy images loaded, CSS-element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page options, custom CSS and JavaScript, clicks, selector waits, delays, network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work to ease migration.

There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Is Browser Use MCP the same as Microsoft Playwright MCP?

No. Browser Use Cloud MCP is a hosted endpoint authenticated with a Browser Use API key. Microsoft Playwright MCP is a separate server with its own local installation and browser interaction model.

Where do I put the API key?

Send it in the x-browser-use-api-key header. The exact configuration wrapper depends on the MCP client.

Does the guide publish Browser Use pricing?

The listed tools can expose a session cost breakdown, but the reviewed setup page does not publish a price schedule or quotas.

Can I use a follow-up task without creating a new session?

Yes, when the session is idle and was kept alive. Use send_task for the follow-up and get_session to check state.

Which client configuration should I copy?

Use the example for your client. Claude Desktop and Cursor use url; Windsurf’s example uses serverUrl; Claude Code uses its HTTP MCP command form.