# Browserbase MCP

> Browserbase lets your AI agent interact with websites like a real user. It provides cloud infrastructure to spin up isolated Chromium sessions on demand, giving your agent direct WebSocket access (via CDP) for tasks ranging from complex logins to scraping dynamic content. You manage the entire process—creation, monitoring, and termination of these virtual browsers—all through an easy-to-use MCP connection.

## Overview
- **Category:** friends-mcp
- **Price:** Free
- **Tags:** headless-browser, chromium, cdp, serverless, web-interaction, automation-infrastructure

## Description

You need more than just static data; you need a browser. This MCP connects your AI agent directly to live web infrastructure. It lets your agent launch controlled, temporary Chromium sessions in the cloud, giving it the full capabilities of Playwright or Puppeteer. The process is simple: your agent can initiate a session, interact with any modern website—clicking buttons, filling complex forms, navigating single-page applications (SPAs)—and then you can monitor exactly what happened. If the task is done, you stop the session and grab the data. This capability means you don't have to worry about infrastructure or scaling; just connect your preferred AI client through Vinkius and let your agent treat websites like they're sitting right in front of it.

## Tools

### create_browser_session
Starts a new browser instance and returns a WebSocket URL needed for your automation framework.

### get_browser_session
Retrieves specific details about a given session ID, useful for monitoring its current status.

### list_browser_sessions
Lists all browser sessions in your account, letting you filter by status (running, completed, or error).

### stop_browser_session
Immediately terminates a running browser session using its ID, ensuring resources are freed up.

## Prompt Examples

**Prompt:** 
```
Create a new browser session so I can automate a login flow.
```

**Response:** 
```
Browser session created!

| Session ID | Status | Region | Info |
|---|---|---|---|
| `sess_abc123` | created | us-west-2 | Browser: chromium |

**Connect URL:** `wss://connect.browserbase.com/sess_abc123`

Use this WebSocket URL with Playwright or Puppeteer to control the browser.
```

**Prompt:** 
```
Show me all my running browser sessions.
```

**Response:** 
```
Found 2 active sessions:

| Session ID | Status | Region | Info |
|---|---|---|---|
| `sess_abc123` | running | us-west-2 | Pages: 3, Duration: 2min |
| `sess_def456` | running | us-east-1 | Pages: 1, Duration: 30s |
```

**Prompt:** 
```
Stop browser session sess_abc123.
```

**Response:** 
```
Session stopped!

| Session ID | Status | Info |
|---|---|---|
| `sess_abc123` | stopped | Session terminated — resources released |
```

## Capabilities

### Start a new web session
Creates an isolated cloud browser instance, giving you the necessary connection URL to control it programmatically.

### Monitor active sessions
Retrieves detailed status information about any running or completed browser instances by ID.

### View all session records
Lists every browser session, letting you filter results by whether they are currently running, finished, or failed.

### End a web session
Terminates an active browser connection immediately, freeing up cloud resources and preventing unnecessary costs.

## Use Cases

### Need to process form submissions from multiple user roles.
A security team needs their agent to test login flows for admin, basic user, and guest accounts. They use `create_browser_session` repeatedly to spin up isolated instances for each role, ensuring credentials don't cross-contaminate or interfere with one another.

### Scraping data from an e-commerce site that requires session persistence.
A research analyst needs pricing data across 50 different product pages. Instead of failing due to anti-bot measures, they use the MCP to maintain a single, long-running session, simulating continuous browsing and extracting all required information.

### Debugging why an agent fails mid-task.
A developer suspects their agent is losing state. They first run `list_browser_sessions` to confirm the connection status, then use `get_browser_session` on a specific ID to check the precise pages visited and duration right before the failure point.

### Automating bulk content extraction from multiple vendor sites.
A competitor intelligence firm needs to pull product descriptions from 10 different websites. They use the MCP to systematically create, interact with, and then stop a session for each site, ensuring clean resource management across all targets.

## Benefits

- Instead of writing complex, brittle code to mimic user clicks, you simply use `create_browser_session` to give your agent a real browser. It handles the connection and session setup for you.
- You can monitor everything with `list_browser_sessions`. This lets developers quickly see if sessions are stuck in an error state or finished successfully, making debugging much faster.
- If your job requires accessing content behind JavaScript-heavy logins or complex single-page applications (SPAs), this MCP provides the necessary environment. Your agent gets a full browser context.
- Prevent resource leaks and unexpected bills by using `stop_browser_session`. You can programmatically guarantee that every session is terminated when the task is complete, no matter what.
- The combination of tools lets your agent execute multi-stage workflows—for example, logging in with one tool and scraping data with another. It’s a full automation cycle.

## How It Works

The bottom line is that this MCP turns your AI agent into an autonomous browser automation system without needing any dedicated hosting infrastructure.

1. First, you call the tool to create a new browser instance. This returns a unique WebSocket URL required for your automation framework.
2. Next, your AI agent uses that connection URL with tools like Playwright or Puppeteer to perform actions on the live website, filling forms and navigating pages.
3. When done, you use another tool to stop the session. You then check the details using a third tool to gather logs, pages visited, or duration.

## Frequently Asked Questions

**How do I start using the create_browser_session tool?**
You initiate it by calling `create_browser_session`. This returns a unique connection URL that your automation framework must use to take control of the new, isolated browser session.

**Can I check if my agent successfully completed a task using get_browser_session?**
Yes. You can call `get_browser_session` with the unique ID to view the current status and detailed history of pages visited, confirming whether the intended action finished correctly.

**What is the difference between list_browser_sessions and get_browser_session?**
The `list_browser_sessions` tool shows you a high-level overview—a roster of all sessions (running, completed, or error). The `get_browser_session` tool drills down to give specific details about one single session ID.

**Should I always use stop_browser_session after my script finishes?**
Absolutely. You must call `stop_browser_session` when your task is done or if an error occurs. This releases the cloud resources and prevents unexpected costs from 'zombie sessions.'

**How do I check for failed or errored sessions using list_browser_sessions?**
You can filter the results by status. Use `list_browser_sessions` and specify 'ERROR' to pull a list of sessions that crashed or encountered issues during execution, which helps you troubleshoot script failures.

**What specific data points does get_browser_session provide about a running session?**
It gives you deep context on the session. You retrieve status details, connection URLs, total pages visited, and the overall duration of the browser activity.

**Are there limits to how many sessions I can run with create_browser_session?**
Your capacity is managed by your subscription tier. The service handles scaling for high-volume requests, allowing you to launch multiple isolated instances simultaneously without manual infrastructure setup.

**What protocols work with the connectUrl generated by create_browser_session?**
The returned WebSocket URL supports major industry standards. You can connect it directly using frameworks like Playwright, Puppeteer, or Selenium for programmatic control.

**How is Browserbase different from Firecrawl?**
Firecrawl is optimized for content extraction — it scrapes pages and returns clean data. Browserbase provides a full browser environment for interactive automation — your agent can click buttons, fill forms, log into websites, scroll, and navigate complex single-page applications (SPAs). Browserbase gives you a real browser, Firecrawl gives you the text from a page.

**Which automation frameworks are supported?**
Browserbase sessions expose a CDP (Chrome DevTools Protocol) WebSocket URL, which is compatible with all major browser automation frameworks: Playwright, Puppeteer, Selenium WebDriver, and any tool that supports CDP connections. Simply point your framework at the connectUrl returned when creating a session.

**What does the free tier include?**
The free tier includes 1 browser hour, 1 concurrent browser session, and 7 days of data retention. No credit card required. For production workloads, paid plans start at $20/month (Developer) with more browser hours and concurrent sessions.