> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browserbase MCP server setup

> Add the Browserbase MCP Server to your MCP client

## Quick installation

> [card] [Install with Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=browserbase\&config=eyJ1cmwiOiJodHRwczovL21jcC5icm93c2VyYmFzZS5jb20vbWNwP2Jyb3dzZXJiYXNlQXBpS2V5PVlPVVJfQlJPV1NFUkJBU0VfQVBJX0tFWSJ9)
>
> One-click installation directly in Cursor

You can also add Browserbase MCP to Claude Code with a single command:

```bash theme={null}
claude mcp add --transport http browserbase "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
```

Connect to Browserbase using the hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) endpoint.

## Endpoint

Hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) endpoint (served on Browserbase infrastructure):

```text theme={null}
https://mcp.browserbase.com/mcp
```

## Prerequisites

**1. Get your Browserbase credentials**

Get your Browserbase API key from the [Browserbase Dashboard](https://www.browserbase.com/overview).

![Browserbase API Key settings](https://mintcdn.com/browserbase/giE_cpy18f2mWHqr/images/quickstart/api_key.png?fit=max\&auto=format\&n=giE_cpy18f2mWHqr\&q=85\&s=4ac94a8f69cec20bd17b2a8788169062)

Then copy your API Key directly from the input.

## Query parameters (hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http))

### Required for tool calls

> [card] browserbaseApiKey
>
> Browserbase API key.

### Optional

| Query Param | Type | Behavior |
| - | - | - |
| `modelName` | string | Defaults to `google/gemini-2.5-flash-lite` |
| `modelApiKey` | string | Required when `modelName` is non-default |
| `keepAlive` | boolean string | `"true"` or `"false"` |
| `proxies` | boolean string | `"true"` or `"false"` |
| `verified` | boolean string | `"true"` or `"false"` |

> [!WARNING]
>
> Boolean query values must be exact strings: `"true"` or `"false"`.

## Available tools

Every tool below accepts an optional `sessionId` parameter. Pass the `sessionId` returned by `start` to target or reattach to that specific Browserbase session; if omitted, the tool uses the transport's current active session. This matters for MCP clients (e.g. ChatGPT) that don't carry the same `Mcp-Session-Id` across requests: pass `sessionId` explicitly on every call to reliably target the right browser session. See [Session reattachment](#session-reattachment) below.

> [accordion] navigate
>
> Navigate to any URL in the browser
>
> **url** `string` *required*
>
> The URL to navigate to
>
> **sessionId** `string`
>
> Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

> [accordion] act
>
> Perform an action on the web page using natural language
>
> **action** `string` *required*
>
> The action to perform (e.g., "click the login button", "fill form field")
>
> **sessionId** `string`
>
> Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

> [accordion] observe
>
> Observe and find actionable elements on the page.
>
> **instruction** `string` *required*
>
> Specific instruction for observation (e.g., "find the login button", "locate search form")
>
> **sessionId** `string`
>
> Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

> [accordion] extract
>
> Extract data from the current page.
>
> **instruction** `string`
>
> Optional extraction instruction.
>
> **sessionId** `string`
>
> Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

> [accordion] start
>
> Create or reuse a Browserbase session and set it as active for the current MCP transport session.
>
> **Inputs**
>
> **sessionId** `string`
>
> Optional existing Browserbase session ID to reuse instead of creating a new session.
>
> **Output**
>
> **sessionId** `string`
>
> Browserbase session ID.

> [accordion] end
>
> Close a Browserbase session.
>
> **sessionId** `string`
>
> Optional Browserbase session ID to close. Defaults to the current active session. Closing a session by explicit ID only clears the transport's active-session state when that ID is the current session.

### Session reattachment

The hosted endpoint (`mcp.browserbase.com`) keeps track of an active Browserbase session per MCP transport (`Mcp-Session-Id`). Some MCP clients open a new transport on every tool call instead of reusing one, which means the server has no active session to fall back to and calls fail with `No active session`.

To work reliably with these clients, pass the `sessionId` returned by `start` on every subsequent tool call. An explicit `sessionId` always takes priority over the transport's current session. The hosted endpoint adopts a session as the transport's active session only after confirming that session still exists, so a stale or incorrect `sessionId` surfaces an error instead of silently redirecting a later call.

## Connect to the hosted server

Use your MCP client config:

```json theme={null}
{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
    }
  }
}
```

For custom models, include `modelName` and `modelApiKey`:

```json theme={null}
{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY&modelName=openai/gpt-4.1&modelApiKey=YOUR_MODEL_API_KEY"
    }
  }
}
```

## Verify installation

**1. Restart your MCP client**

Restart/refresh your MCP client app and verify tools are available.

**2. Test the integration**

Get started by asking your MCP client to navigate to any page and see your Browserbase browser in action on the [dashboard](https://www.browserbase.com/sessions).

> [!TIP]
>
> Try: "Navigate to example.com and extract the main heading"

## Further reading

> [card] [Model Context Protocol (MCP) docs](https://modelcontextprotocol.io/introduction)
>
> Learn more about the MCP protocol

> [card] [Browse CLI](https://docs.browserbase.com/integrations/skills/browse-cli.md)
>
> Control a browser session from your terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.