Related Pages

Related topics: System Architecture Overview, Quick Start Guide

Introduction

The Browserbase MCP Server (@browserbasehq/mcp) is an open-source Model Context Protocol (MCP) server that enables AI web browser automation through Browserbase's infrastructure and Stagehand's AI-powered browser control capabilities. Source: README.md

Project Overview

This MCP server bridges AI assistants with real web browser automation, allowing Large Language Models (LLMs) to interact with web pages through a standardized protocol. The server leverages Browserbase's cloud browser infrastructure for reliable, scalable web automation while using Stagehand for AI-driven element detection and action execution. Source: README.md

Source: package.json

Architecture Overview

The MCP server follows a modular architecture with clear separation of concerns:

graph TD
    A[MCP Client] -->|MCP Protocol| B[MCP Server Entry]
    B --> C[Context Manager]
    C --> D[Session Manager]
    C --> E[Tools Registry]
    D --> F[Stagehand Instances]
    F --> G[Browserbase Cloud]
    E --> H[start]
    E --> I[navigate]
    E --> J[act]
    E --> K[observe]
    E --> L[extract]
    E --> M[end]

Core Components

Source: src/index.ts, src/context.ts, src/sessionManager.ts, src/types/types.ts

Available Tools

The MCP server exposes six primary tools for browser automation:

Source: README.md, CHANGELOG.md

Configuration Options

Command-Line Flags

The server accepts the following configuration flags:

Source: README.md

Configuration Schema

The server validates configuration using Zod with the following schema:

export const configSchema = z.object({
  browserbaseApiKey: z.string().describe("The Browserbase API Key to use"),
  browserbaseProjectId: z.string().describe("The Browserbase Project ID to use"),
  proxies: z.boolean().optional().describe("Whether to use Browserbase proxies"),
  verified: z.boolean().optional().describe("Browserbase Verified Identity"),
  advancedStealth: z.boolean().optional().describe("Deprecated alias for verified"),
  keepAlive: z.boolean().optional().describe("Keep session alive"),
  context: z.object({
    contextId: z.string().optional().describe("Context ID")
  }).optional()
});

Source: src/index.ts

Required Environment Variables

Source: README.md, server.json

Transport Types

The MCP server supports two transport mechanisms for communication:

graph LR
    A[MCP Client] --> B[SHTTP Transport]
    A --> C[STDIO Transport]
    B -->|HTTP| D[Hosted Server<br/>mcp.browserbase.com]
    C -->|stdin/stdout| E[Local Server]
    E --> F[Direct Installation]
    E --> G[Docker Container]

SHTTP (Hosted)

The hosted solution runs at https://mcp.browserbase.com/mcp and is the recommended approach for most users. Source: README.md

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

STDIO (Self-Hosted)

Self-hosted deployment supports both direct npm installation and Docker containers. Source: README.md

Via NPM:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Via Docker:

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "BROWSERBASE_API_KEY", "-e", "BROWSERBASE_PROJECT_ID", "-e", "GEMINI_API_KEY", "mcp-browserbase"]
    }
  }
}

Session Management

The SessionManager handles browser session lifecycle with automatic validation and recreation:

stateDiagram-v2
    [*] --> Idle: No sessions
    Idle --> Creating: start tool called
    Creating --> Active: Session created
    Active --> Validating: Periodic check
    Validating --> Active: Session valid
    Validating --> Recreating: Session stale
    Recreating --> Creating: Retry
    Active --> Closing: end tool called
    Closing --> Idle: Cleanup complete

Session Validation

Sessions are validated by checking if the Stagehand context has available pages. If validation fails, the session is marked as stale and recreated automatically. Source: src/sessionManager.ts

Model Configuration

Stagehand defaults to Google's Gemini 2.5 Flash Lite model, which has been shown to perform best in evaluations. However, the server supports custom models from various providers including Anthropic Claude and OpenAI GPT-4o. Source: README.md

Supported Models

The model must be supported by Stagehand. For a full list of supported models, see the Stagehand documentation.

Custom Model Setup

When using a custom model, provide both the model name and API key:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName",
        "anthropic/claude-sonnet-4.5",
        "--modelApiKey",
        "your-anthropic-api-key"
      ]
    }
  }
}

Source: README.md

Version History

v3.0.0 (Breaking Changes)

The latest major version introduced significant changes to align with the hosted MCP server:

• Tool names renamed (e.g., browserbase_session_create → start)
• Removed tools: browserbase_screenshot, browserbase_stagehand_get_url, browserbase_stagehand_agent
• Default model changed from gemini-2.0-flash to google/gemini-2.5-flash-lite
• Removed Smithery references and dependencies

Source: CHANGELOG.md

Dependencies

Source: package.json

Resources and Sampling

The server implements MCP's optional capabilities for completeness:

• Resources: Currently returns empty (no custom resources defined)
• Sampling: Capability declared but depends on client support

Source: src/mcp/resources.ts, src/mcp/sampling.ts

See Also

• Browserbase MCP Documentation
• Model Context Protocol Specification
• Stagehand Documentation
• Stagehand Evals

Related Pages

Related topics: Introduction, Deployment Methods

Quick Start Guide

The MCP Server for Browserbase is an implementation of the Model Context Protocol (MCP) that enables AI assistants to control web browsers through natural language commands. This guide covers all supported deployment methods, from the simplest hosted option to fully self-hosted deployments using Docker or direct Node.js execution.

Overview

The server provides browser automation capabilities powered by Browserbase and Stagehand. It exposes MCP tools that allow LLMs to navigate websites, interact with page elements, extract data, and capture screenshots using natural language instructions.

Key Capabilities

Source: README.md

Architecture

graph TD
    A[MCP Client] -->|HTTP or STDIO| B[MCP Server]
    B -->|Tool Calls| C[Context Handler]
    C -->|Session Mgmt| D[Stagehand Instance]
    D -->|Browser Automation| E[Browserbase Cloud]
    E -->|CDP| F[Remote Browser]
    
    G[BROWSERBASE_API_KEY] --> B
    H[BROWSERBASE_PROJECT_ID] --> B
    I[GEMINI_API_KEY] --> B

The server is built on the @modelcontextprotocol/sdk and registers capabilities for tools and resources. The Context class manages the lifecycle of Stagehand instances and routes tool requests to appropriate handlers.

Source: src/index.ts Source: src/context.ts

Available Tools

The server exposes the following MCP tools that can be called by any compatible MCP client:

Source: src/tools/index.ts Source: README.md

Deployment Methods

The server supports multiple transport mechanisms and deployment options depending on your requirements.

graph LR
    A[Deployment Options] --> B[SHTTP Hosted]
    A --> C[NPM Package]
    A --> D[Direct Installation]
    A --> E[Docker]
    
    B --> F[Easiest Setup]
    C --> G[Managed Runtime]
    D --> H[Full Control]
    E --> I[Containerized]

Method 1: SHTTP (Hosted MCP)

The recommended approach uses the Browserbase hosted MCP server. This provides the simplest setup and includes LLM costs for Gemini, which is the best performing model in Stagehand according to their evaluations.

Source: README.md

#### Configuration for SHTTP-Clients

If your MCP client supports HTTP transport:

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

#### Configuration for Non-SHTTP Clients

If your client only supports STDIO but can invoke external processes:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

Source: README.md

Method 2: NPM Package (Recommended for Self-Hosted)

This method runs the server locally while still using Browserbase's cloud infrastructure for browser sessions.

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

The package is published as @browserbasehq/mcp with version tracking available on npm.

Source: README.md Source: package.json

Method 3: Direct Installation

For full control over the runtime environment, clone and build the repository locally.

#### Prerequisites

• Node.js 18+
• npm or pnpm
• Git

#### Installation Steps

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

The build script compiles TypeScript and sets executable permissions on the output files:

"build": "tsc && shx chmod +x dist/*.js"

Source: README.md Source: package.json

#### Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Method 4: Docker

Containerized deployment provides isolation and consistency across environments.

#### Build the Image

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .

#### Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BROWSERBASE_API_KEY",
        "-e",
        "BROWSERBASE_PROJECT_ID",
        "-e",
        "GEMINI_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md

Configuration Options

The server accepts configuration through environment variables and command-line arguments.

Environment Variables

Source: server.json

Command-Line Flags

Source: README.md Source: src/config.ts

Default Configuration

The server uses sensible defaults that can be overridden:

Source: src/config.ts

Custom Model Configuration

To use a different LLM model, you must use a self-hosted deployment (not the hosted MCP server) and specify the model name:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp", "--modelName", "anthropic/claude-sonnet-4-20250514"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "ANTHROPIC_API_KEY": ""
      }
    }
  }
}

The model must be supported in Stagehand. Check the supported models documentation at docs.stagehand.dev.

Source: README.md

Session Workflow

Browser sessions follow a specific lifecycle managed by the MCP server:

sequenceDiagram
    participant Client
    participant Server
    participant Browserbase
    participant Browser
    
    Client->>Server: start session
    Server->>Browserbase: Create Browserbase Session
    Browserbase->>Browser: Launch Remote Browser
    Browser->>Server: Session Established
    Server->>Client: sessionId returned
    
    Client->>Server: navigate { url }
    Server->>Browser: Load URL
    Browser->>Server: Page Loaded
    Server->>Client: Navigation Complete
    
    Client->>Server: act { action }
    Server->>Browser: Execute Action
    Browser->>Server: Action Result
    Server->>Client: Action Complete
    
    Client->>Server: extract { instruction }
    Server->>Browser: Extract Data
    Browser->>Server: Extracted Data
    Server->>Client: Data Returned
    
    Client->>Server: end session
    Server->>Browserbase: Close Session
    Browserbase->>Browser: Terminate
    Server->>Client: Session Closed

Session Creation Parameters

When starting a session, the following parameters are available:

type CreateSessionParams = {
  apiKey?: string;                    // Override default API key
  projectId?: string;                // Override default project ID
  modelName?: string;                // Use custom model
  modelApiKey?: string;              // API key for custom model
  browserbaseSessionID?: string;     // Resume existing session
  browserbaseSessionCreateParams?: any;  // Browserbase-specific options
  meta?: Record<string, any>;        // Session metadata
};

Source: src/types/types.ts

Verifying Installation

After configuring your MCP client, verify the connection by checking that the server responds to tool list requests. The server should advertise the following tools:

1. start - Session management
2. end - Session cleanup
3. navigate - URL navigation
4. act - Page interactions
5. observe - Element detection
6. extract - Data extraction

You can use the MCP inspector for debugging:

npx @modelcontextprotocol/inspector build/index.js

Source: package.json

Troubleshooting

Common Issues

Source: src/index.ts

Development

For local development and testing:

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Watch mode for development
pnpm watch

# Lint code
pnpm lint

# Format code
pnpm format

Source: package.json

Next Steps

• Review the Browserbase MCP Documentation for advanced usage
• Explore the MCP Specification for protocol details
• Check the Stagehand Documentation for browser automation capabilities
• Report issues at GitHub Issues

Related Pages

Related topics: Transport Layer, MCP Tools Reference, Session Management

System Architecture Overview

The mcp-server-browserbase is an MCP (Model Context Protocol) server that enables AI web browser automation by integrating Browserbase's infrastructure with Stagehand's AI-powered browser control capabilities. The server acts as a bridge between MCP-compliant AI clients and browser automation, providing tools for session management, navigation, interaction, and data extraction.

Architecture Layers

The system follows a layered architecture pattern that separates concerns between transport, protocol, execution, and browser automation.

graph TD
    subgraph "Transport Layer"
        STDIO[STDIO Transport]
        SHTTP[SHTTP Transport]
    end
    
    subgraph "MCP Protocol Layer"
        MCP_SDK[MCP SDK Server]
        Tools[MCP Tools]
        Resources[Resources]
        Sampling[Sampling]
    end
    
    subgraph "Application Layer"
        Context[Context Controller]
        Config[Configuration Resolver]
        SessionMgr[Session Manager]
    end
    
    subgraph "Browser Automation Layer"
        Stagehand[Stagehand Instance]
        Browserbase[Browserbase SDK]
    end
    
    STDIO --> MCP_SDK
    SHTTP --> MCP_SDK
    MCP_SDK --> Tools
    MCP_SDK --> Resources
    MCP_SDK --> Sampling
    Context --> SessionMgr
    SessionMgr --> Stagehand
    Stagehand --> Browserbase

Source: src/index.ts:1-50 | src/context.ts:1-30

Core Components

1. Entry Point and CLI (program.ts)

The application entry point uses Commander.js to parse command-line arguments and initialize the server.

graph LR
    CLI[CLI Arguments] --> Program[program.ts]
    Program --> Config[resolveConfig]
    Config --> CreateServer[createServer]
    CreateServer --> Transport[Start Transport]

Source: src/program.ts:1-80

Command-line options supported:

Source: src/config.ts:15-28

2. Configuration System

The configuration system uses Zod for schema validation and implements a merge strategy: Defaults < File Config < CLI Options.

graph TD
    Default[Default Config] --> Merge[mergeConfig]
    File[File Config] --> Merge
    CLI[CLI Options] --> Merge
    Merge --> Normalize[normalizeVerifiedConfig]
    Normalize --> FinalConfig[Resolved Config]
    FinalConfig --> AddEnvVars[Add Env Vars]
    AddEnvVars --> Validate[Validation]

Source: src/config.ts:50-75

Configuration schema (Zod):

export const configSchema = z.object({
  browserbaseApiKey: z.string().describe("The Browserbase API Key to use"),
  browserbaseProjectId: z.string().describe("The Browserbase Project ID to use"),
  proxies: z.boolean().optional().describe("Whether to use Browserbase proxies"),
  verified: z.boolean().optional().describe("Use Browserbase Verified Identity"),
  keepAlive: z.boolean().optional().describe("Keep session alive"),
  context: z.object({
    contextId: z.string().optional()
  }).optional()
});

Source: src/index.ts:30-50

3. MCP Server (server.ts + index.ts)

The MCP server is built on the @modelcontextprotocol/sdk and handles tool registration, request routing, and protocol compliance.

Source: src/server.ts | src/index.ts:80-130

MCP Server capabilities:

4. Context Controller (context.ts)

The Context class serves as the central orchestrator, maintaining references to the MCP server instance, configuration, and SessionManager.

classDiagram
    class Context {
        +Server server
        +Config config
        -SessionManager sessionManager
        +getServer() Server
        +getSessionManager() SessionManager
        +getStagehand(sessionId?) Promise~Stagehand~
        +run(tool, params) CallToolResult
    }
    
    class SessionManager {
        -Map sessions
        -string activeSessionId
        +createSession(config) Promise~Session~
        +getSession(id) Promise~Session~
        +closeSession(id) Promise~void~
        +getActiveSessionId() string
    }
    
    Context --> SessionManager

Source: src/context.ts:15-50

5. Session Manager (sessionManager.ts)

The SessionManager handles lifecycle management of browser sessions, creating and caching Stagehand instances per session.

Source: src/sessionManager.ts

Session lifecycle:

stateDiagram-v2
    [*] --> NoSession: Initial State
    NoSession --> Creating: start tool called
    Creating --> Active: Stagehand initialized
    Active --> Active: navigate/act/observe/extract
    Active --> Closing: end tool called
    Closing --> NoSession: Session closed
    Closing --> Active: Error, retry

6. Tool System

Tools are the primary interface for MCP clients to interact with browser automation capabilities.

Source: src/tools/index.ts:1-25

Available tools:

Source: src/tools/index.ts:10-20

Tool registration flow:

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Context as Context
    participant SessionMgr as SessionManager
    participant Stagehand as Stagehand
    
    Client->>Server: Call Tool
    Server->>Context: run(tool, params)
    Context->>SessionMgr: getSession(id)
    SessionMgr->>Stagehand: Get/Create Instance
    Stagehand->>Stagehand: Execute operation
    Stagehand-->>Context: Result
    Context-->>Server: CallToolResult
    Server-->>Client: JSON-RPC Response

Transport Layer

The server supports two transport mechanisms for MCP communication.

Source: src/transport.ts

STDIO Configuration (Docker):

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md:1-50

Data Flow

Tool Execution Pipeline

graph TD
    Request[Tool Request] --> Validate[Zod Validation]
    Validate --> Authenticate[Auth Check]
    Authenticate --> GetSession[Get Session]
    GetSession --> GetStagehand[Get Stagehand]
    GetStagehand --> Execute[Execute Tool]
    Execute --> Transform[Transform Result]
    Transform --> Response[JSON-RPC Response]
    
    Execute -->|Error| ErrorHandler[Error Handler]
    ErrorHandler --> Response

Source: src/index.ts:110-145

Configuration Merging Strategy

graph LR
    A[Defaults] -->|Low Priority| M[Merge Config]
    B[Environment Vars] -->|Medium Priority| M
    C[CLI Arguments] -->|High Priority| M
    M --> R[Resolved Config]

Source: src/config.ts:40-65

Type System

Source: src/types/types.ts

Key Types

Configuration Interface (config.d.ts)

interface Config {
  browserbaseApiKey: string;
  browserbaseProjectId: string;
  proxies: boolean;
  verified?: boolean;
  modelName: string;
  modelApiKey?: string;
  keepAlive?: boolean;
  viewPort?: {
    browserWidth: number;
    browserHeight: number;
  };
  server?: {
    port?: number;
    host?: string;
  };
}

Source: config.d.ts:1-50

Dependencies Architecture

Source: package.json:20-45

graph BT
    MCP["@modelcontextprotocol/sdk"]
    Stagehand["@browserbasehq/stagehand"]
    BrowserbaseSDK["@browserbasehq/sdk"]
    Zod["zod"]
    Commander["commander"]
    
    mcp-server-browserbase --> MCP
    mcp-server-browserbase --> Stagehand
    mcp-server-browserbase --> BrowserbaseSDK
    mcp-server-browserbase --> Zod
    mcp-server-browserbase --> Commander

Core Dependencies

Error Handling

The server implements structured error handling at multiple levels:

Source: src/index.ts:125-140

graph TD
    Error[Error Thrown] --> Log[Log to stderr]
    Log --> Format[Format error message]
    Format --> Throw[Throw MCP Error]
    Throw --> Response[JSON-RPC Error Response]
    
    Response --> Client[Client receives error]

Error message format:

[MCP Error] {ISO timestamp} Error running tool {tool_name}: {error_message}

Module Structure Summary

mcp-server-browserbase/
├── src/
│   ├── index.ts          # Server factory, tool registration
│   ├── server.ts         # MCP server initialization
│   ├── program.ts        # CLI entry point
│   ├── context.ts        # Central controller
│   ├── config.ts         # Configuration resolver
│   ├── sessionManager.ts # Session lifecycle
│   ├── transport.ts      # STDIO/SHTTP transport
│   ├── types/
│   │   └── types.ts      # TypeScript definitions
│   ├── mcp/
│   │   ├── resources.ts # MCP resources
│   │   └── sampling.ts  # MCP sampling
│   └── tools/
│       ├── index.ts      # Tool exports
│       ├── session.ts    # start/end tools
│       ├── navigate.ts   # navigate tool
│       ├── act.ts        # act tool
│       ├── observe.ts   # observe tool
│       └── extract.ts   # extract tool
├── config.d.ts           # Config interface definition
├── package.json          # Dependencies and scripts
└── README.md             # Documentation

Deployment Modes

NPM Package (npx)

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Docker Container

docker build -t mcp-browserbase .

Hosted MCP Server

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

Source: README.md:50-100

Related Pages

Related topics: System Architecture Overview, Deployment Methods

Transport Layer

Overview

The Transport Layer in the Browserbase MCP Server handles the communication between the MCP client and the server. It abstracts the underlying transport mechanism, allowing the server to support multiple transport protocols while maintaining a consistent interface for tool execution and resource management.

The transport layer is responsible for:

• Accepting incoming connections from MCP clients
• Managing server sessions for stateful communication
• Routing requests to appropriate handlers
• Handling the serialization and deserialization of MCP protocol messages

Source: src/transport.ts:1-50

Supported Transport Protocols

The MCP server supports two transport protocols:

Source: README.md

STDIO Transport

The STDIO transport uses standard input and output streams for communication. This is the default transport when no server configuration is provided.

graph LR
    A[MCP Client] -->|stdin| B[MCP Server]
    B -->|stdout| A

The STDIO transport is initialized when both port and host are undefined in the server configuration. Source: config.d.ts:45-55

SHTTP (Streamable HTTP) Transport

The SHTTP transport uses HTTP with session management for stateful communication. It supports multiple concurrent sessions through a session ID mechanism.

graph TD
    A[HTTP Request] --> B{Session ID Present?}
    B -->|Yes| C[Existing Session]
    B -->|No| D[Create New Session]
    C --> E[StreamableHTTPServerTransport]
    D --> F[Generate UUID Session ID]
    F --> E
    E --> G[Server Instance]
    G --> H[Tool Execution]

Source: src/transport.ts:30-55

Architecture

Server Initialization Flow

sequenceDiagram
    participant Client
    participant Transport
    participant Server
    participant SessionManager
    participant Stagehand

    Client->>Transport: HTTP Request
    Transport->>Transport: Check Session ID
    alt No Session
        Transport->>Transport: Generate UUID
        Transport->>Server: Create Instance
        Server->>SessionManager: Initialize Session
        Server->>Stagehand: Create Browser Context
    else Has Session
        Transport->>Server: Route to Existing Session
    end
    Server->>Transport: Process Request
    Transport->>Client: Response

Component Responsibilities

Session Management

The SHTTP transport implements a session-based model to maintain state across multiple requests.

Session Lifecycle

stateDiagram-v2
    [*] --> NoSession: No Session ID Header
    NoSession --> Active: POST /mcp
    Active --> Active: Subsequent Requests
    Active --> Closed: Transport Close Event
    Closed --> [*]

Session Storage

Sessions are stored in an in-memory Map structure:

const streamableSessions = new Map<string, StreamableHTTPServerTransport>();

Source: src/transport.ts:20-45

Configuration

Server Transport Options

The transport layer is configured through the server configuration object:

Source: config.d.ts:40-55

Configuration Resolution

The configuration is resolved in order of precedence:

1. Default values - Built-in defaults for all options
2. Environment variables - BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, etc.
3. CLI options - Command-line arguments passed at runtime

graph LR
    A[CLI Options] --> B[mergeConfig]
    C[Default Config] --> B
    B --> D[normalizeVerifiedConfig]
    D --> E[Final Config]

Source: src/config.ts:30-55

Environment Variables

Source: src/config.ts:55-60

Request Handling

HTTP Request Flow

┌─────────────────────────────────────────────────────────────┐
│                    Incoming HTTP Request                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    URL Validation                            │
│  Check: url.pathname.startsWith("/mcp")                     │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              │                               │
              ▼                               ▼
        [Invalid URL]                    [Valid /mcp]
        Return 400                       Continue
              │                               │
              ▼                               ▼
        ┌─────────┐              ┌─────────────────────────┐
        │  End    │              │ Session Check           │
        └─────────┘              │ mcp-session-id header?  │
                                 └─────────────────────────┘
                                              │
                              ┌───────────────┴───────────────┐
                              │                               │
                              ▼                               ▼
                    [Session Found]                  [No Session]
                    Route to transport               Create new transport
                    from Map                         Generate UUID
                              │                               │
                              │                      ┌────────┴────────┐
                              │                      │ Create Server  │
                              │                      │ Connect        │
                              │                      └────────────────┘
                              ▼                               │
                    ┌─────────────────┐                       │
                    │ Handle Request  │◄──────────────────────┘
                    │ via Transport   │
                    └─────────────────┘

Source: src/transport.ts:35-55

Security Considerations

The transport layer implements several security measures:

Source: config.d.ts:47-55

Security Recommendations

1. Development: Use default localhost binding
2. Production: If external access required:

• Use firewall rules to restrict access
• Consider VPN or reverse proxy
• Implement authentication at the application layer

1. Hosted Service: Use Browserbase hosted MCP at https://mcp.browserbase.com/mcp for managed security

Source: README.md

Usage Examples

STDIO Configuration (Self-Hosted)

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key",
        "BROWSERBASE_PROJECT_ID": "your-project-id",
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}

SHTTP Configuration (Hosted)

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

Docker with SHTTP

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BROWSERBASE_API_KEY",
        "-e",
        "BROWSERBASE_PROJECT_ID",
        "-e",
        "GEMINI_API_KEY",
        "mcp-browserbase"
      ]
    }
  }
}

Source: README.md

CLI Options

The transport layer can be configured via command-line arguments:

Source: src/config.ts:15-30

Error Handling

The transport layer implements robust error handling:

Source: src/transport.ts:20-35

Error responses are logged with ISO timestamps for debugging:

process.stderr.write(
  `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`,
);

Source: src/index.ts:120-125

Dependencies

The transport layer relies on the following key dependencies:

Source: package.json

Related Pages

Related topics: Session Management, System Architecture Overview

MCP Tools Reference

This page documents all available MCP (Model Context Protocol) tools provided by the Browserbase MCP Server for AI-powered web browser automation.

Overview

The Browserbase MCP Server exposes a set of tools that enable Large Language Models to interact with web pages through natural language commands. These tools wrap the Stagehand browser automation library and provide capabilities for session management, navigation, interaction, observation, and data extraction.

Source: src/tools/index.ts:1-18

Architecture

The tools module follows a modular architecture where each tool is defined as an independent module with a consistent schema and handler structure.

graph TD
    A[MCP Server] --> B[TOOLS Array]
    B --> C[Session Tools]
    B --> D[navigateTool]
    B --> E[actTool]
    B --> F[observeTool]
    B --> G[extractTool]
    
    C --> H[start]
    C --> I[end]
    
    J[Context] --> K[SessionManager]
    K --> L[Stagehand Instances]

All tools are exported as a unified array that matches the hosted MCP server at mcp.browserbase.com. Source: src/tools/index.ts:13-17

Tool Registration

Tools are registered with the MCP server using the SDK's server.tool() method. Each tool requires a schema defining its name, description, and input schema, along with an async handler function.

Source: src/index.ts:42-63

sequenceDiagram
    participant MCP as MCP Server
    participant Tool as Tool Handler
    participant Context as Context
    participant Stagehand as Stagehand
    
    MCP->>Tool: Execute Tool with params
    Tool->>Context: context.run(tool, params)
    Context->>Stagehand: Invoke Stagehand method
    Stagehand-->>Context: Return result
    Context-->>MCP: CallToolResult

Tool Schema Structure

All tools implement a common interface defined in the MCPTool type. Each tool consists of a schema and a handler function.

Source: src/tools/tool.ts

Available Tools

Tool Categories

Complete Tool List

Source: src/tools/index.ts:13-17

export const TOOLS = [
  ...sessionTools,    // start, end
  navigateTool,       // navigate
  actTool,            // act
  observeTool,        // observe
  extractTool,        // extract
];

Session Management Tools

Session tools manage the lifecycle of Browserbase browser sessions. Each session maintains its own Stagehand instance for isolated browser automation.

Source: src/tools/session.ts

graph LR
    A[start] -->|Creates| B[SessionManager]
    B -->|Manages| C[Stagehand Instance]
    C --> D[Browser Tab]
    E[end] -->|Closes| B

`start` Tool

Creates a new browser session and initializes a Stagehand instance. A session must be started before any other tools can be used.

Renamed in v3.0.0 - Previously named browserbase_session_create.

Source: src/tools/session.ts

`end` Tool

Closes the current browser session and releases all associated resources.

Renamed in v3.0.0 - Previously named browserbase_session_close.

Source: src/tools/session.ts

Navigation Tool

`navigate` Tool

Navigates the browser to a specified URL. The tool uses Stagehand's navigation capabilities for reliable page loading.

Renamed in v3.0.0 - Previously named browserbase_stagehand_navigate.

Source: src/tools/navigate.ts

Example usage:

{
  "name": "navigate",
  "arguments": {
    "url": "https://example.com"
  }
}

Interaction Tool

`act` Tool

Performs an action on the current page using AI-powered element identification. The model analyzes the page and determines the appropriate element and action to execute.

Renamed in v3.0.0 - Previously named browserbase_stagehand_act.

Breaking change in v3.0.0 - The variables parameter has been removed.

Source: src/tools/act.ts

Supported action types:

• Click on elements (buttons, links, etc.)
• Fill form fields (text inputs, textareas)
• Select dropdown options
• Check/uncheck checkboxes
• Submit forms

Example usage:

{
  "name": "act",
  "arguments": {
    "action": "Click the 'Sign In' button"
  }
}

Observation Tool

`observe` Tool

Observes the current page and identifies all actionable elements. Returns a list of elements that can be interacted with, categorized by type.

Renamed in v3.0.0 - Previously named browserbase_stagehand_observe.

Source: src/tools/observe.ts

Example usage:

{
  "name": "observe",
  "arguments": {
    "instruction": "Find all clickable buttons on the page"
  }
}

Return value structure:

The tool returns an array of observed elements with their properties:

interface ObservedElement {
  type: "button" | "link" | "input" | "select" | ...;
  description: string;
  selector?: string;
  attributes?: Record<string, string>;
}

Data Extraction Tool

`extract` Tool

Extracts structured data from the current page based on natural language instructions. Uses AI to understand the page content and return relevant information.

Renamed in v3.0.0 - Previously named browserbase_stagehand_extract.

Breaking change in v3.0.0 - The instruction parameter is now optional.

Source: src/tools/extract.ts

When instruction is omitted, the tool extracts all meaningful content from the page.

Example usage:

{
  "name": "extract",
  "arguments": {
    "instruction": "Extract all product names and prices"
  }
}

Tool Handler Implementation

Each tool follows a consistent implementation pattern using the tool factory function.

Source: src/tools/tool.ts

export interface MCPTool {
  schema: {
    name: string;
    description: string;
    inputSchema: z.ZodObject<any>;
  };
  handler: (params: any, context: Context) => Promise<CallToolResult>;
}

Handler Parameters

Error Handling

All tool handlers are wrapped in try-catch blocks at the MCP server level. Errors are logged with timestamps and re-thrown with descriptive messages.

Source: src/index.ts:47-59

try {
  const result = await context.run(tool, params);
  return result;
} catch (error) {
  const errorMessage = error instanceof Error ? error.message : String(error);
  process.stderr.write(
    `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`,
  );
  throw new Error(
    `Failed to run tool '${tool.schema.name}': ${errorMessage}`,
  );
}

Session Management Integration

Tools interact with the SessionManager through the Context class, which provides synchronized access to session state.

Source: src/context.ts

graph TD
    A[Tool Handler] --> B[Context.run]
    B --> C[currentSessionId getter]
    C --> D[SessionManager.getActiveSessionId]
    D --> E[Returns active session]
    B --> F[SessionManager.getSession]
    F --> G[Stagehand instance]

The currentSessionId property is a getter that delegates to SessionManager to ensure synchronization between Context and SessionManager session tracking.

Source: src/context.ts:18-20

Configuration Options

The following configuration options affect tool behavior:

Tool Execution Flow

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Handler as Tool Handler
    participant Context as Context
    participant Session as SessionManager
    participant Stagehand as Stagehand
    
    Client->>Server: tool/CallRequest
    Server->>Handler: Execute with params
    Handler->>Context: context.run(tool, params)
    Context->>Session: getSession(currentSessionId)
    Session->>Stagehand: Get/initialize instance
    Stagehand-->>Context: Stagehand ready
    Context->>Stagehand: Execute operation
    Stagehand-->>Handler: Result
    Handler-->>Server: CallToolResult
    Server-->>Client: Response

Changelog

v3.0.0 Breaking Changes

Source: CHANGELOG.md

Removed Tools

The following tools were removed in v3.0.0:

• browserbase_screenshot - Screenshot functionality consolidated elsewhere
• browserbase_stagehand_get_url - URL accessible via session state
• browserbase_stagehand_agent - Agent capabilities restructured

See Also

• Browserbase MCP Documentation
• Stagehand Documentation
• MCP Specification

Related Pages

Related topics: MCP Tools Reference, Configuration Options

Session Management

Overview

Session Management in the MCP Server for Browserbase is the core system responsible for creating, tracking, maintaining, and disposing of browser automation sessions. Each session represents an isolated browser instance powered by Stagehand, enabling AI-driven web automation operations.

The session management system serves as the backbone for all browser-based operations, providing:

• Isolation: Multiple concurrent browser sessions with independent state
• Lifecycle Management: Automated creation, validation, cleanup, and recovery
• Concurrency Control: Mutex patterns to prevent race conditions during session creation
• Resource Optimization: Session reuse and graceful cleanup to minimize resource consumption

Source: src/sessionManager.ts:1-50

Architecture

High-Level Components

The session management architecture consists of three primary layers working in coordination:

graph TD
    subgraph "MCP Layer"
        MCP["MCP Server"]
        Tools["Session Tools<br/>(start, end)"]
    end
    
    subgraph "Context Layer"
        Context["Context<br/>(src/context.ts)"]
        SessionId["currentSessionId<br/>(getter)"]
    end
    
    subgraph "Session Management Layer"
        SM["SessionManager<br/>(src/sessionManager.ts)"]
        Browsers["Map&lt;string, BrowserSession&gt;"]
        Active["activeSessionId"]
        Default["defaultBrowserSession"]
        Mutex["defaultSessionCreationPromise"]
        Cleanup["cleaningUpSessions"]
    end
    
    subgraph "Stagehand Layer"
        Stagehand["Stagehand Instance"]
        Browser["Browser Context"]
        Page["Page"]
    end
    
    MCP --> Tools
    Tools --> Context
    Context --> SM
    SM --> Stagehand
    Stagehand --> Browser
    Browser --> Page
    
    Context -.-> SessionId
    SM -.-> Browsers
    SM -.-> Active
    SM -.-> Default
    SM -.-> Mutex
    SM -.-> Cleanup

Class Hierarchy

Source: src/context.ts:1-30

Data Model

BrowserSession Interface

interface BrowserSession {
  page: Page;                    // Playwright Page instance
  sessionId: string;             // Browserbase session identifier
  stagehand: Stagehand;         // Stagehand automation instance
}

Source: src/sessionManager.ts:120-125

SessionManager State

The SessionManager class maintains the following internal state:

Source: src/sessionManager.ts:56-73

Session Lifecycle

Lifecycle States

stateDiagram-v2
    [*] --> Created: createNewBrowserSession()
    Created --> Active: setActiveSessionId()
    Active --> Validating: getSession()
    Validating --> Active: Session valid
    Validating --> Recreating: Session stale
    Recreating --> Active: Recreated successfully
    Recreating --> Error: Creation failed
    Active --> CleaningUp: cleanupSession()
    CleaningUp --> [*]: Cleanup complete
    Active --> [*]: closeAllSessions()

Session Creation Flow

graph TD
    Start["Request Session"] --> CheckDefault{"Is Default<br/>Session?"}
    
    CheckDefault -->|Yes| CheckInProgress{"Creation<br/>In Progress?"}
    CheckDefault -->|No| GetFromMap["Get from<br/>browsers Map"]
    
    CheckInProgress -->|Yes| Wait["Wait for<br/>existing promise"]
    CheckInProgress -->|No| CheckExists{"Session<br/>Exists?"}
    
    Wait --> ReturnExisting["Return Promise"]
    CheckExists -->|No| Create["createNewBrowserSession()"]
    CheckExists -->|Yes| Validate["Validate<br/>Session"]
    
    Create --> Stagehand["Create Stagehand<br/>Instance"]
    Stagehand --> Extract["Extract Page &<br/>Session ID"]
    Extract --> Store["Store in Map"]
    Store --> SetActive["Set Active"]
    
    Validate -->|Valid| Return["Return Session"]
    Validate -->|Stale| Remove["Close & Remove"]
    Remove --> Create

Source: src/sessionManager.ts:130-200

Session Validation

Sessions are validated before use by checking page availability:

try {
  const pages = sessionObj.stagehand.context.pages();
  if (!pages || pages.length === 0) {
    throw new Error("No pages available");
  }
} catch {
  needsReCreation = true;
}

Source: src/sessionManager.ts:83-91

Core Methods

Creating Sessions

#### createNewBrowserSession()

Process:

1. Validate API key and project ID exist in config
2. Create Stagehand instance with optional resume capability
3. Extract page and Browserbase session ID
4. Store session in browsers Map
5. Update active session ID

const stagehand = await createStagehandInstance(
  config,
  {
    ...(resumeSessionId && { browserbaseSessionID: resumeSessionId }),
  },
  newSessionId,
);

Source: src/sessionManager.ts:140-195

Retrieving Sessions

#### getSession()

Returns: BrowserSession | null

async getSession(
  sessionId: string,
  config: Config,
  createIfMissing: boolean = true,
): Promise<BrowserSession | null>

Source: src/sessionManager.ts:240-280

#### ensureDefaultSessionInternal()

Ensures the default session exists and is valid. Uses a mutex pattern to prevent race conditions when multiple concurrent requests attempt to create the default session simultaneously.

if (this.defaultSessionCreationPromise) {
  process.stderr.write(
    `[SessionManager] Default session creation already in progress, waiting...\n`,
  );
  return await this.defaultSessionCreationPromise;
}

Source: src/sessionManager.ts:200-220

Cleanup Operations

#### closeBrowserGracefully()

Safely closes a single session with concurrent cleanup protection:

Features:

• Tracks sessions being cleaned in cleaningUpSessions Set
• Prevents double-cleanup of the same session
• Always removes from cleanup tracking in finally block

if (this.cleaningUpSessions.has(sessionIdToLog)) {
  process.stderr.write(
    `[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\n`,
  );
  return;
}
this.cleaningUpSessions.add(sessionIdToLog);

Source: src/sessionManager.ts:145-180

#### cleanupSession()

Removes a session and resets state:

async cleanupSession(sessionId: string): Promise<void> {
  const session = this.browsers.get(sessionId);
  if (session) {
    await this.closeBrowserGracefully(session, sessionId);
  }
  this.browsers.delete(sessionId);
  
  if (sessionId === this.defaultSessionId) {
    this.defaultBrowserSession = null;
  }
  if (this.activeSessionId === sessionId) {
    this.setActiveSessionId(this.defaultSessionId);
  }
}

Source: src/sessionManager.ts:110-145

#### closeAllSessions()

Closes all managed sessions in parallel:

async closeAllSessions(): Promise<void> {
  const closePromises: Promise<void>[] = [];
  for (const [id, session] of this.browsers.entries()) {
    closePromises.push(this.closeBrowserGracefully(session, id));
  }
  await Promise.all(closePromises);
  this.browsers.clear();
  this.defaultBrowserSession = null;
  this.setActiveSessionId(this.defaultSessionId);
}

Source: src/sessionManager.ts:155-175

Session Tools (MCP Interface)

Session management is exposed to MCP clients through tools defined in src/tools/session.ts and registered in the TOOLS array:

Source: src/tools/index.ts:1-20

Tool Exports

export const TOOLS = [
  ...sessionTools,
  navigateTool,
  actTool,
  observeTool,
  extractTool,
];

export const sessionManagementTools = sessionTools;

Source: src/tools/index.ts:16-18

Integration with Context

The Context class provides the bridge between MCP infrastructure and session management:

export class Context {
  public readonly config: Config;
  private server: Server;
  private sessionManager: SessionManager;

  public get currentSessionId(): string {
    return this.sessionManager.getActiveSessionId();
  }

  public async getStagehand(
    sessionId: string = this.currentSessionId,
  ): Promise<Stagehand> {
    const session = await this.sessionManager.getSession(
      sessionId,
      this.config,
    );
    if (!session) {
      throw new Error("Session not found");
    }
    return session.stagehand;
  }
}

Source: src/context.ts:15-45

Concurrency Handling

Mutex Pattern for Default Session

The default session creation uses a mutex pattern to prevent race conditions:

graph LR
    A["Request 1"] --> M{"In Progress?"}
    B["Request 2"] --> M
    C["Request 3"] --> M
    
    M -->|No| Create["Create Session"]
    M -->|Yes| Wait["Wait on Promise"]
    
    Create --> Store["Store Promise"]
    Store --> Return["Return to Request 1"]
    Wait --> Return

Implementation:

private defaultSessionCreationPromise: Promise<BrowserSession> | null = null;

async ensureDefaultSessionInternal(config: Config): Promise<BrowserSession> {
  if (this.defaultSessionCreationPromise) {
    return await this.defaultSessionCreationPromise;
  }
  
  this.defaultSessionCreationPromise = (async () => {
    try {
      this.defaultBrowserSession = await this.createNewBrowserSession(...);
      return this.defaultBrowserSession;
    } finally {
      this.defaultSessionCreationPromise = null;
    }
  })();
  
  return await this.defaultSessionCreationPromise;
}

Source: src/sessionManager.ts:200-240

Cleanup Tracking

The cleaningUpSessions Set prevents concurrent cleanup operations:

private cleaningUpSessions: Set<string> = new Set();

async closeBrowserGracefully(...): Promise<void> {
  if (this.cleaningUpSessions.has(sessionIdToLog)) {
    return; // Skip if already being cleaned
  }
  
  this.cleaningUpSessions.add(sessionIdToLog);
  try {
    // Perform cleanup
  } finally {
    this.cleaningUpSessions.delete(sessionIdToLog);
  }
}

Source: src/sessionManager.ts:145-175

Error Handling

Session Creation Errors

Errors during session creation trigger automatic retry:

try {
  this.defaultBrowserSession = await this.createNewBrowserSession(...);
  return this.defaultBrowserSession;
} catch (creationError) {
  process.stderr.write(`[SessionManager] Initial attempt failed...\n`);
  
  // Retry once
  try {
    this.defaultBrowserSession = await this.createNewBrowserSession(...);
    return this.defaultBrowserSession;
  } catch (retryError) {
    throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);
  }
} finally {
  this.defaultSessionCreationPromise = null;
}

Source: src/sessionManager.ts:225-260

Graceful Degradation

The system logs warnings and continues operation on non-fatal errors:

} catch (closeError) {
  process.stderr.write(
    `[SessionManager] WARN - Error closing Stagehand for session ${sessionIdToLog}: ${
      closeError instanceof Error
        ? closeError.message
        : String(closeError)
    }\n`,
  );
}

Source: src/sessionManager.ts:160-170

Session Identification

ID Generation

Default session IDs follow a structured format:

const uniqueId = randomUUID();
this.defaultSessionId = `browserbase_session_${contextId || "default"}_${Date.now()}_${uniqueId}`;

Format: browserbase_session_{contextId}_{timestamp}_{uuid}

Example: browserbase_session_default_1699123456789_a1b2c3d4-e5f6-7890-abcd-ef1234567890

Source: src/sessionManager.ts:66-70

Active Session Management

The active session can be changed but only to existing sessions (or the default):

setActiveSessionId(id: string): void {
  if (this.browsers.has(id)) {
    this.activeSessionId = id;
  } else if (id === this.defaultSessionId) {
    this.activeSessionId = id; // Allow even if not created yet
  } else {
    process.stderr.write(`[SessionManager] WARN - Set active session failed for non-existent ID: ${id}\n`);
  }
}

Source: src/sessionManager.ts:75-90

Summary

The Session Management system provides a robust foundation for browser automation within the MCP server:

• Isolation: Each session maintains independent browser state via Stagehand
• Reliability: Automatic validation, recreation, and retry mechanisms
• Concurrency Safety: Mutex patterns and cleanup tracking prevent race conditions
• Resource Management: Graceful cleanup ensures proper resource disposal
• Integration: Seamless connection through the Context layer to MCP tools

Related Pages

Related topics: Model Configuration, Quick Start Guide

Configuration Options

The MCP Server Browserbase provides a flexible configuration system that allows operators to customize server behavior through environment variables, command-line arguments, and programmatic configuration. This page documents all available configuration options, their types, default values, and how they are processed at runtime.

Overview

The configuration system follows a hierarchical merge strategy where defaults are progressively overridden by file-based configuration and finally by CLI options. This approach ensures sensible defaults while maintaining maximum flexibility for different deployment scenarios.

The configuration system is built on three pillars:

• Zod Schema Validation: All configuration options are validated using Zod schemas defined in src/index.ts
• Environment Variable Support: Sensitive values and deployment-specific settings can be injected via environment variables
• Command-Line Arguments: Runtime behavior can be modified through CLI flags defined in src/program.ts

Source: src/config.ts:1-15

Configuration Schema

The root configuration interface Config defines the complete structure of valid configuration options. All options are type-safe and validated at server startup.

Core Configuration Interface

interface Config {
  browserbaseApiKey: string;
  browserbaseProjectId: string;
  proxies: boolean;
  server: {
    port?: number;
    host?: string;
  };
  viewPort: {
    browserWidth: number;
    browserHeight: number;
  };
  modelName: string;
  modelApiKey?: string;
  verified?: boolean;
  keepAlive?: boolean;
}

Source: config.d.ts

Zod Schema Definition

The configuration schema provides runtime validation and documentation for MCP clients:

export const configSchema = z.object({
  browserbaseApiKey: z.string().describe("The Browserbase API Key to use"),
  browserbaseProjectId: z.string().describe("The Browserbase Project ID to use"),
  proxies: z.boolean().optional().describe("Whether or not to use Browserbase proxies"),
  verified: z.boolean().optional().describe("Use Browserbase Verified Identity"),
  advancedStealth: z.boolean().optional().describe("Deprecated alias for verified"),
  keepAlive: z.boolean().optional().describe("Whether or not to keep the Browserbase session alive"),
  // Additional fields...
});

Source: src/index.ts:18-45

Command-Line Options

The server accepts the following command-line flags when run directly via Node.js or the CLI entry point:

Source: src/program.ts:28-46

Source: src/config.ts:7-22

Environment Variables

The configuration system automatically loads values from environment variables when CLI options are not provided:

Environment variables are loaded using the dotenv package at application startup:

import * as dotenv from "dotenv";
dotenv.config();

Source: src/index.ts:1-2

Environment Variable Resolution Priority

When resolving the model API key, the system checks environment variables in the following order:

1. process.env.GEMINI_API_KEY
2. process.env.GOOGLE_API_KEY

if (!mergedConfig.modelApiKey) {
  mergedConfig.modelApiKey =
    process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}

Source: src/config.ts:50-53

Default Configuration Values

The server ships with sensible defaults for all optional parameters:

Source: src/config.ts:25-34

Configuration Resolution Flow

The configuration passes through several transformation stages before being used by the server:

graph TD
    A[Default Config] --> B[CLI Options]
    B --> C[configFromCLIOptions]
    C --> D[mergeConfig]
    D --> E[normalizeVerifiedConfig]
    E --> F[normalizeVerifiedConfig with Env Vars]
    F --> G[Internal Config]
    G --> H[Server Initialization]
    
    I[process.env.GEMINI_API_KEY] -.-> F
    J[process.env.GOOGLE_API_KEY] -.-> F

Configuration Processing Pipeline

The resolveConfig function orchestrates the complete configuration workflow:

export async function resolveConfig(cliOptions: CLIOptions): Promise<Config> {
  const cliConfig = await configFromCLIOptions(cliOptions);
  // Order: Defaults < File Config < CLI Overrides
  const mergedConfig = normalizeVerifiedConfig(
    mergeConfig(defaultConfig, cliConfig),
  );

  // --- Add Browserbase Env Vars ---
  if (!mergedConfig.modelApiKey) {
    mergedConfig.modelApiKey =
      process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
  }
  // ...
}

Source: src/config.ts:37-56

Verified Identity Configuration

The verified option enables Browserbase Verified Identity features, which are only available to users on the Browserbase Scale Plan. The system also supports a legacy advancedStealth alias for backward compatibility.

Legacy Alias Handling

it("maps the legacy CLI advancedStealth alias to verified", async () => {
  const config = await configFromCLIOptions({ advancedStealth: true });
  expect(config.verified).toBe(true);
});

it("prefers verified when both verified and advancedStealth are set", () => {
  const config = normalizeVerifiedConfig({
    browserbaseApiKey: "test-key",
    browserbaseProjectId: "test-project",
    verified: false,
    advancedStealth: true,
  });
  expect(config.verified).toBe(false);
});

Source: src/config.test.ts:7-22

CLI Options Type Definition

The CLIOptions type represents all valid command-line input options:

export type CLIOptions = {
  proxies?: boolean;
  verified?: boolean;
  advancedStealth?: boolean;
  contextId?: string;
  persist?: boolean;
  port?: number;
  host?: string;
  browserWidth?: number;
  browserHeight?: number;
  modelName?: string;
  modelApiKey?: string;
  keepAlive?: boolean;
  experimental?: boolean;
};

Source: src/config.ts:7-22

Required Configuration

Certain configuration values must be provided for the server to function:

Mandatory Fields

The validation is performed in src/index.ts before the MCP server is initialized:

if (!config.browserbaseApiKey) {
  throw new Error("browserbaseApiKey is required");
}
if (!config.browserbaseProjectId) {
  throw new Error("browserbaseProjectId is required");
}

Source: src/index.ts:93-99

Tool Capability Configuration

Configuration options can be tagged with capability levels for feature gating:

export type ToolCapability = "core" | string;

This allows future extension of the configuration system to support optional tool sets based on subscription tier or feature flags.

Source: src/config.ts:3-5

Configuration in MCP Client Setup

When integrating with MCP clients, configuration is passed through the env property of the server definition:

NPM Package Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Direct Node.js Installation

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Docker Container Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BROWSERBASE_API_KEY",
        "-e",
        "BROWSERBASE_PROJECT_ID",
        "-e",
        "GEMINI_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md

Transport Configuration

The server supports multiple transport mechanisms, each with its own configuration requirements:

Source: src/transport.ts

Related Pages

Related topics: Configuration Options, System Architecture Overview

Model Configuration

The Model Configuration system in mcp-server-browserbase enables users to customize the AI model used for browser automation tasks powered by Stagehand. This flexibility allows integration with different LLM providers while maintaining a consistent interface for the MCP server.

Overview

The MCP server leverages Stagehand for AI-powered web browser automation. Stagehand uses a default model of google/gemini-2.5-flash-lite, which provides optimal performance for web interaction tasks. The Model Configuration system allows users to override this default with supported alternative models from providers like Anthropic, OpenAI, or other compatible LLM services.

Source: src/config.ts:26-27

Configuration Architecture

Configuration Resolution Order

The system employs a layered configuration strategy where settings are merged in a specific priority order:

graph TD
    A[Default Configuration] --> B[File Configuration]
    B --> C[CLI Options]
    C --> D[Environment Variables]
    D --> E[Final Merged Config]
    
    F[modelApiKey Override] --> |"if not set"| D
    G[GEMINI_API_KEY or GOOGLE_API_KEY] --> F

The resolution order from lowest to highest priority is:

1. Default Configuration - Hardcoded defaults in src/config.ts
2. CLI Options - Command-line arguments provided at runtime
3. Environment Variables - Used as fallback for modelApiKey

Source: src/config.ts:29-43

Configuration Schema

The server uses Zod for runtime validation of the configuration object:

export const configSchema = z.object({
  browserbaseApiKey: z.string().describe("The Browserbase API Key to use"),
  browserbaseProjectId: z.string().describe("The Browserbase Project ID to use"),
  modelName: z.string().optional(),
  modelApiKey: z.string().optional(),
  // ... other options
});

Source: src/index.ts:28-49

CLI Options

Available Flags

The --modelName and --modelApiKey flags are exposed through Commander.js:

.option("--modelName <modelName>", "The model to use for Stagehand")
.option("--modelApiKey <modelApiKey>", "API key for the model provider")

Source: src/program.ts:45-46

CLI Options Type Definition

export type CLIOptions = {
  modelName?: string;
  modelApiKey?: string;
  // ... other options
};

Source: src/config.ts:13-24

Environment Variable Handling

The modelApiKey can be automatically populated from environment variables when not explicitly provided:

if (!mergedConfig.modelApiKey) {
  mergedConfig.modelApiKey =
    process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}

This allows users to set credentials once in their environment rather than repeatedly on the command line.

Source: src/config.ts:38-41

Supported Models

The server uses Stagehand for browser automation, and the model must be supported by Stagehand. Refer to the Stagehand documentation for the complete list of supported models.

Default Model

The default model is google/gemini-2.5-flash-lite, chosen for its performance in web interaction tasks:

const defaultConfig: Config = {
  // ...
  modelName: "google/gemini-2.5-flash-lite", // Default Model — matches hosted MCP
};

Source: src/config.ts:26

Popular Alternative Models

Configuration Examples

Using Default Model

When using the default Gemini model, provide the API key via environment variable:

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key",
        "BROWSERBASE_PROJECT_ID": "your-project-id",
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}

Source: README.md

Using Custom Model

To use a custom model like Claude:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName",
        "anthropic/claude-sonnet-4.5",
        "--modelApiKey",
        "your-anthropic-api-key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": ""
      }
    }
  }
}

Source: README.md

NPM Installation with Custom Model

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName",
        "anthropic/claude-sonnet-4.5",
        "--modelApiKey",
        "sk-ant-..."
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb-...",
        "BROWSERBASE_PROJECT_ID": "..."
      }
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BROWSERBASE_API_KEY",
        "-e",
        "BROWSERBASE_PROJECT_ID",
        "-e",
        "MODEL_NAME",
        "-e",
        "MODEL_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "MODEL_NAME": "anthropic/claude-sonnet-4.5",
        "MODEL_API_KEY": ""
      }
    }
  }
}

Requirements for Custom Models

When using a custom model (non-default), you must provide your own API key for that model provider using the --modelApiKey flag. This ensures authentication with the external LLM service.

Configuration Flow Diagram

sequenceDiagram
    participant User
    participant CLI as Command Line
    participant Config as Config Module
    participant Stagehand
    
    User->>CLI: Start server with options
    CLI->>Config: Parse CLI options
    Config->>Config: Load default config
    Config->>Config: Merge CLI options
    Config->>Config: Check env vars for modelApiKey
    Config->>Config: Return resolved config
    CLI->>Stagehand: Initialize with config
    Stagehand->>User: Server ready with model

Related Dependencies

The model configuration system depends on the following key packages:

Source: package.json:40-45

Best Practices

1. Environment Variables for Secrets: Store API keys in environment variables rather than command-line arguments to avoid exposing sensitive data in process listings.

1. Model Selection: Choose models based on your use case—gemini-2.5-flash-lite for cost efficiency, larger models like Claude Opus for complex reasoning tasks.

1. Validation: The Zod schema validates configuration at runtime, ensuring required fields are present before the server starts.

1. Compatibility: Always verify your chosen model is supported by Stagehand before configuration.

Related Pages

Related topics: Quick Start Guide, Transport Layer

Deployment Methods

The Browserbase MCP Server supports multiple deployment approaches to accommodate different infrastructure requirements and use cases. This document covers all supported methods for deploying the MCP server, including local installations, containerized deployments, and hosted alternatives.

Overview

The MCP server can be deployed in three primary ways:

1. Direct Installation - Clone the repository and run locally with Node.js
2. Docker Container - Run the server in an isolated container
3. NPM Package - Use the pre-built @browserbasehq/mcp package via npx

Additionally, the server supports two transport mechanisms for communication:

• STDIO - Standard input/output communication for local CLI integrations
• SHTTP - HTTP-based transport for networked or hosted deployments

Source: README.md:1-50

Deployment Architecture

graph TD
    A[Client MCP Config] --> B{Transport Type}
    B -->|STDIO| C[Direct Installation / NPM]
    B -->|SHTTP| D[Hosted Server / Self-Hosted HTTP]
    
    C --> E[Node.js Runtime]
    D --> F[mcp.browserbase.com]
    D --> G[Self-Hosted Docker/Node]
    
    E --> H[Browserbase Cloud]
    F --> H
    G --> H
    
    H --> I[Stagehand]
    I --> J[Browser Automation]

Method 1: Direct Installation

Direct installation provides full control over the server and is suitable for development environments or custom deployments.

Prerequisites

• Node.js 18+ (LTS recommended)
• npm or pnpm package manager
• Valid Browserbase API credentials

Installation Steps

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

Source: README.md:1-10

Project Structure

The built artifacts are generated in the dist/ directory with the following structure:

Source: package.json:11-17

Available Build Scripts

Source: package.json:22-30

Method 2: Docker Deployment

Docker deployment provides an isolated, reproducible environment that includes all dependencies.

Building the Docker Image

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .

Running the Container

The Docker image exposes the server with environment variable support for configuration:

docker run --rm -i \
  -e BROWSERBASE_API_KEY \
  -e BROWSERBASE_PROJECT_ID \
  -e GEMINI_API_KEY \
  mcp-browserbase

Source: README.md:10-25

Docker Configuration Benefits

• Isolation: Runs independently of host system dependencies
• Consistency: Identical behavior across different environments
• Security: Sandboxed execution environment
• Portability: Easy to deploy to any container runtime

Method 3: NPM Package (npx)

The pre-built package provides the fastest path to deployment without manual cloning or building.

Quick Start

npx @browserbasehq/mcp

Configuration in MCP Client

Add the following to your MCP configuration file:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md:60-75

Package Metadata

Source: package.json:1-12

Transport Methods

The MCP server supports two transport protocols for client communication.

STDIO Transport

STDIO is the default transport when no HTTP configuration is specified. It uses standard input/output streams for communication.

graph LR
    A[MCP Client] -->|stdio| B[Browserbase MCP Server]
    B -->|stdout| A

#### Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md:60-72

SHTTP Transport

SHTTP (Secure HTTP) enables networked deployments and is the recommended transport for hosted deployments.

#### Hosted Server (Recommended)

Use the Browserbase hosted MCP server for the simplest setup:

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

#### Self-Hosted HTTP

For self-hosted HTTP transport, specify port and host in the CLI:

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

Source: README.md:30-55

#### Remote Access via mcp-remote

Clients without native SHTTP support can use the mcp-remote tool:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

Command-Line Options

The server accepts the following CLI flags for configuration:

Source: README.md:85-100

CLI Option Definitions

The CLI options are parsed using the commander package:

program
  .option("--browserbaseApiKey <key>", "The Browserbase API Key to use")
  .option("--browserbaseProjectId <id>", "The Browserbase Project ID to use")
  .option("--proxies", "Use Browserbase proxies.")
  .option("--verified", "Use Browserbase Verified Identity. Only available to Browserbase Scale Plan users.")
  .option("--advancedStealth", "Deprecated alias for --verified.")
  .option("--contextId <contextId>", "Browserbase Context ID to use");

Source: src/program.ts:30-40

Environment Variables

Required Variables

Optional Variables

Configuration Resolution Order

The server resolves configuration using this precedence (highest to lowest):

1. CLI arguments
2. Environment variables
3. Default values

graph TD
    A[Config Resolution] --> B[Load Defaults]
    B --> C[Merge Env Variables]
    C --> D[Apply CLI Overrides]
    D --> E[Validate Configuration]
    E --> F[Start Server]

Source: src/config.ts:40-60

Configuration Type Definition

interface Config {
  browserbaseApiKey: string;
  browserbaseProjectId: string;
  proxies?: boolean;
  verified?: boolean;
  advancedStealth?: boolean;
  keepAlive?: boolean;
  context?: {
    contextId?: string;
    persist?: boolean;
  };
  server?: {
    port?: number;
    host?: string;
  };
  viewPort?: {
    browserWidth?: number;
    browserHeight?: number;
  };
  modelName?: string;
  modelApiKey?: string;
  experimental?: boolean;
}

Source: config.d.ts

Model Configuration

The server defaults to Google's Gemini 2.5 Flash Lite model but supports custom models.

Default Configuration

Custom Model Setup

To use a custom model, provide both --modelName and --modelApiKey:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName",
        "anthropic/claude-sonnet-4.5",
        "--modelApiKey",
        "your-anthropic-api-key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": ""
      }
    }
  }
}

Note: The model must be supported by Stagehand. See Stagehand Custom LLM docs.

Source: README.md:110-130

Deployment Decision Matrix

Security Considerations

Host Binding

Warning: Use 0.0.0.0 only when you need external access and have proper security measures in place.

API Key Management

• Store credentials in environment variables, never in config files committed to version control
• Use secret management solutions in production environments
• Rotate API keys regularly

Source: config.d.ts:25-35

Quick Reference

Minimal STDIO Setup

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "your-key",
        "BROWSERBASE_PROJECT_ID": "your-project",
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}

Full-Featured Docker Setup

docker run --rm -i \
  -e BROWSERBASE_API_KEY \
  -e BROWSERBASE_PROJECT_ID \
  -e GEMINI_API_KEY \
  mcp-browserbase \
  --proxies \
  --verified \
  --browserWidth 1920 \
  --browserHeight 1080

Related Documentation

• Browserbase MCP Documentation
• MCP Specification
• Stagehand Documentation

Overview

The mcp-server-browserbase project implements a comprehensive testing infrastructure using Vitest as the primary testing framework. The testing setup is designed to validate configuration handling, ensure type safety, and maintain code quality through integration with ESLint and Prettier. Testing focuses primarily on the configuration subsystem and verification compatibility, leveraging modern TypeScript testing practices with Zod schema validation testing.

Testing Stack

Core Testing Framework

The project uses Vitest (version 4.1.2), a Vite-native unit testing framework that provides fast test execution and excellent TypeScript support. Vitest is configured through vitest.config.ts to discover and run tests across the codebase.

Supporting Tools

Source: package.json:39-60

Test Configuration

Vitest Configuration

The Vitest configuration defines the scope and boundaries of test discovery within the project:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
    exclude: ["node_modules", "dist"],
  },
});

Configuration Parameters:

Source: vitest.config.ts:1-9

Test Execution

Tests are executed through npm/pnpm scripts defined in package.json:

Source: package.json:32-34

Test Structure

Directory Organization

Tests follow a co-located pattern within the source directory:

graph TD
    A[Project Root] --> B[src/]
    A --> C[tests/]
    B --> D[config.test.ts]
    B --> E[index.ts]
    B --> F[config.ts]
    
    D -. tests .-> F
    D -. validates .-> E

Configuration Tests

The config.test.ts file contains comprehensive tests for configuration handling, verifying the behavior of configuration normalization and schema validation:

#### Test Suite: Verified Config Compatibility

The test suite validates configuration alias handling and priority resolution between different configuration sources:

Test 1: Legacy CLI AdvancedStealth Alias Mapping

it("maps the legacy CLI advancedStealth alias to verified", async () => {
  const config = await configFromCLIOptions({ advancedStealth: true });
  expect(config.verified).toBe(true);
});

This test verifies that the deprecated advancedStealth option correctly maps to the verified configuration property, maintaining backward compatibility.

Source: src/config.test.ts:9-13

Test 2: Verified/AdvancedStealth Priority Resolution

it("prefers verified when both verified and advancedStealth are set", () => {
  const config = normalizeVerifiedConfig({
    browserbaseApiKey: "test-key",
    browserbaseProjectId: "test-project",
    verified: false,
    advancedStealth: true,
  });
  expect(config.verified).toBe(false);
});

This test ensures that when both verified and advancedStealth are provided, the explicit verified value takes precedence, following the principle that explicit configuration overrides deprecated aliases.

Source: src/config.test.ts:15-23

Test 3: Smithery Config Schema Compatibility

it("accepts advancedStealth in the Smithery config schema", () => {
  const config = configSchema.parse({
    browserbaseApiKey: "test-key",
    browserbaseProjectId: "test-project",
    advancedStealth: true,
  });
  expect(config.advancedStealth).toBe(true);
});

This test validates compatibility with external configuration schemas like Smithery, ensuring the advancedStealth property is correctly parsed and preserved.

Source: src/config.test.ts:25-32

Code Quality Integration

ESLint Configuration

The project uses ESLint with TypeScript support to maintain code quality across test files and source code:

export default defineConfig([
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
    plugins: { js },
    extends: ["js/recommended"],
    ignores: ["dist/**/*"],
  },
  {
    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
    languageOptions: { globals: { ...globals.browser, ...globals.node } },
    ignores: ["dist/**/*"],
  },
  ...tseslint.configs.recommended,
  {
    files: ["src/types/**/*.ts", "src/mcp/**/*.ts"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-unused-vars": "off",
      "@typescript-eslint/ban-ts-comment": "off",
    },
  },
  {
    ignores: ["dist/**/*", "node_modules/**/*"],
  },
]);

ESLint Rule Configuration:

Source: eslint.config.js:1-34

Lint-Staged Configuration

The project uses lint-staged to run automated linting and formatting on staged files before commits:

"lint-staged": {
  "*.{js,jsx,ts,tsx,json,css,scss,md}": [
    "prettier --write .",
    "eslint --fix"
  ]
}

This configuration ensures all staged files are formatted with Prettier and fixed with ESLint before being committed, maintaining consistent code style.

Source: package.json:26-31

Configuration Resolution Flow

The testing infrastructure validates the configuration resolution process, which follows a cascading merge strategy:

graph LR
    A[Default Config] --> B[CLI Options]
    B --> C[mergeConfig]
    C --> D[normalizeVerifiedConfig]
    D --> E[Final Config]
    
    F[Env: GEMINI_API_KEY] -.-> E
    F -.-> G[modelApiKey]
    G --> E

Configuration Priority Order (Lowest to Highest):

1. Default configuration values
2. Environment variables
3. CLI options
4. Explicit verified flag (overrides deprecated advancedStealth)

Source: src/config.ts:18-32

Default Configuration Values

The test suite validates against the following default configuration structure:

Source: src/config.ts:18-28

Test Coverage Areas

Currently Covered

Evals System

The project includes an evaluation system for testing MCP server behavior:

"evals": "tsx evals/run-evals.ts run --config evals/mcp-eval-basic.config.json && tsx evals/run-evals.ts run --config evals/mcp-eval-minimal.config.json && tsx evals/run-evals.ts run --config evals/mcp-eval.config.json"

The evals system runs multiple evaluation configurations to validate the MCP server's functionality against expected behavior patterns.

Source: package.json:30

Running Tests

Standard Test Execution

# Run all tests once
pnpm test

# Run tests in watch mode during development
npx vitest

With Evals

# Run comprehensive evaluation suite
pnpm evals

Code Quality Checks

# Run ESLint
pnpm lint

# Format code with Prettier
pnpm format

# Run all pre-commit checks
pnpm pre-commit

Best Practices Demonstrated

The testing infrastructure demonstrates several best practices:

1. Co-located tests: Test files are placed alongside source files with .test.ts suffix
2. Descriptive test names: Tests use clear, descriptive names explaining the scenario being validated
3. Configuration validation: Zod schemas are tested for backward compatibility
4. Code quality automation: Pre-commit hooks ensure consistent formatting and linting
5. Multiple test configurations: The eval system provides tiered testing with basic, minimal, and full configurations

Doramagic Pitfall Log

Doramagic extracted 11 source-linked risk signals. Review them before installing or handing real data to the project.

1. Security or permission risk: Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/browserbase/mcp-server-browserbase/issues/127

2. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp

3. Installation risk: Your MCP server is now indexed on Joy Trust Network

• Severity: medium
• Finding: Installation risk is backed by a source signal: Your MCP server is now indexed on Joy Trust Network. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/browserbase/mcp-server-browserbase/issues/174

4. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.

5. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium

7. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium

8. Security or permission risk: Add MCPpedia security badge to README

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Add MCPpedia security badge to README. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/browserbase/mcp-server-browserbase/issues/175

9. Security or permission risk: Add policy enforcement for cloud browser sessions

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Add policy enforcement for cloud browser sessions. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/browserbase/mcp-server-browserbase/issues/176

10. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown

11. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mcp-server-browserbase with real data or production workflows.

• Add policy enforcement for cloud browser sessions - github / github_issue
• Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alte - github / github_issue
• Add MCPpedia security badge to README - github / github_issue
• Your MCP server is now indexed on Joy Trust Network - github / github_issue
• v3.0.0 - github / github_release
• Project risk needs validation - GitHub / issue