# browserbase/mcp-server-browserbase architecture

> Architecture diagram of the GitHub repository browserbase/mcp-server-browserbase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/browserbase/mcp-server-browserbase
- Repository: https://github.com/browserbase/mcp-server-browserbase

## Overview

Browserbase MCP Server is a self-hostable MCP interface for cloud browser automation using Browserbase and Stagehand. An MCP client invokes a registered tool; Context executes its handler, which manages a session or uses Stagehand to navigate, act, observe, or extract page information, then returns tool content. Configuration selects session and model options, while CLI wiring exposes stdio or HTTP transport. The README documents six tools and both transports; sampled excerpts show the registration and some tool/session flows, but not every tool implementation or the transport internals.

Main entry points: [`src/context.ts`](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts) (Tool context), [`src/index.ts`](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts) (MCP server), [`src/tools/index.ts`](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts) (Tool registry), [`src/program.ts`](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts) (CLI startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_cli["CLI startup<br/>[program.ts]"]
  node_mcpserver["MCP server<br/>[index.ts]"]
  node_context["Tool context<br/>[context.ts]"]
  node_resources["MCP resources<br/>[resources.ts]"]
  node_sampling["MCP sampling<br/>[sampling.ts]"]
end

subgraph group_tools["Browser tools"]
  node_toolregistry["Tool registry<br/>[index.ts]"]
  node_toolrunner["Tool contract<br/>[tool.ts]"]
  node_sessiontools["Session tools<br/>[session.ts]"]
  node_navigate["Navigate<br/>[navigate.ts]"]
  node_act["Act<br/>[act.ts]"]
  node_observe["Observe<br/>[observe.ts]"]
  node_extract["Extract<br/>[extract.ts]"]
end

subgraph group_sessions["Session runtime"]
  node_sessionmanager["Session manager<br/>[sessionManager.ts]"]
  node_stagehand["Stagehand runtime<br/>[sessionManager.ts]"]
end

subgraph group_transport["Configuration and transport"]
  node_config["Configuration<br/>[config.ts]"]
  node_transport["MCP transports<br/>[transport.ts]"]
  node_serverlist["Server lifecycle<br/>[server.ts]"]
end

node_client(("MCP client"))
node_browserbase(("Browserbase"))
node_webpage["Web page"]

node_client -.->|"invokes tools"| node_mcpserver
node_cli -->|"resolves config"| node_config
node_cli -->|"creates server"| node_mcpserver
node_cli -->|"starts transport"| node_transport
node_cli -->|"creates lifecycle"| node_serverlist
node_mcpserver -->|"creates context"| node_context
node_mcpserver -->|"registers tools"| node_toolregistry
node_mcpserver -->|"registers handlers"| node_resources
node_mcpserver -->|"dispatches tools"| node_context
node_context -->|"executes handlers"| node_toolrunner
node_toolregistry -->|"exports tool"| node_navigate
node_toolregistry -->|"exports tool"| node_act
node_toolregistry -->|"exports tool"| node_observe
node_toolregistry -->|"exports tool"| node_extract
node_toolregistry -->|"exports tools"| node_sessiontools
node_navigate -->|"gets Stagehand"| node_context
node_act -->|"uses session"| node_context
node_observe -->|"uses session"| node_context
node_extract -->|"uses session"| node_context
node_sessiontools -->|"manages session"| node_sessionmanager
node_context -->|"owns sessions"| node_sessionmanager
node_sessionmanager -->|"creates and closes"| node_stagehand
node_stagehand -.->|"connects session"| node_browserbase
node_navigate -->|"navigates"| node_webpage
node_stagehand -.->|"controls browser"| node_webpage
node_config -.->|"configures sessions"| node_sessionmanager
node_transport -.->|"serves MCP"| node_mcpserver
node_context -->|"lists and reads"| node_resources
node_sampling -.->|"sampling integration"| node_mcpserver

click node_cli "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts"
click node_mcpserver "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts"
click node_context "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts"
click node_toolregistry "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts"
click node_toolrunner "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts"
click node_sessiontools "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts"
click node_navigate "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts"
click node_act "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts"
click node_observe "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts"
click node_extract "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts"
click node_sessionmanager "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts"
click node_stagehand "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts"
click node_config "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts"
click node_transport "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts"
click node_serverlist "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts"
click node_resources "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts"
click node_sampling "https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/sampling.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcpserver,node_context,node_resources,node_sampling,node_client,node_browserbase toneBlue
class node_toolregistry,node_toolrunner,node_sessiontools,node_navigate,node_act,node_observe,node_extract toneAmber
class node_sessionmanager,node_stagehand toneMint
class node_config,node_transport,node_serverlist toneRose
class node_webpage toneIndigo
```

## Components

### MCP entry

- [CLI startup](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts): `src/program.ts`
- [MCP server](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts): `src/index.ts`
- [Tool context](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts): `src/context.ts`
- [MCP resources](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts): `src/mcp/resources.ts`
- [MCP sampling](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/sampling.ts): `src/mcp/sampling.ts`

### Browser tools

- [Tool registry](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Tool contract](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts): `src/tools/tool.ts`
- [Session tools](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts): `src/tools/session.ts`
- [Navigate](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts): `src/tools/navigate.ts`
- [Act](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts): `src/tools/act.ts`
- [Observe](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts): `src/tools/observe.ts`
- [Extract](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts): `src/tools/extract.ts`

### Session runtime

- [Session manager](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts): `src/sessionManager.ts`
- [Stagehand runtime](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts): `src/sessionManager.ts`

### Configuration and transport

- [Configuration](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts): `src/config.ts`
- [MCP transports](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts): `src/transport.ts`
- [Server lifecycle](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts): `src/server.ts`

### Other components

- **MCP client**
- **Browserbase**
- **Web page**

## Connections

- MCP client → MCP server: invokes tools (evidence: `README.md`)
- CLI startup → Configuration: resolves config (evidence: `src/program.ts`)
- CLI startup → MCP server: creates server (evidence: `src/program.ts`)
- CLI startup → MCP transports: starts transport (evidence: `src/program.ts`)
- CLI startup → Server lifecycle: creates lifecycle (evidence: `src/program.ts`)
- MCP server → Tool context: creates context (evidence: `src/index.ts`)
- MCP server → Tool registry: registers tools (evidence: `src/index.ts`)
- MCP server → MCP resources: registers handlers (evidence: `src/index.ts`)
- MCP server → Tool context: dispatches tools (evidence: `src/index.ts`)
- Tool context → Tool contract: executes handlers (evidence: `src/context.ts`)
- Tool registry → Navigate: exports tool (evidence: `src/tools/index.ts`)
- Tool registry → Act: exports tool (evidence: `src/tools/index.ts`)
- Tool registry → Observe: exports tool (evidence: `src/tools/index.ts`)
- Tool registry → Extract: exports tool (evidence: `src/tools/index.ts`)
- Tool registry → Session tools: exports tools (evidence: `src/tools/index.ts`)
- Navigate → Tool context: gets Stagehand (evidence: `src/tools/navigate.ts`)
- Act → Tool context: uses session (evidence: `src/tools/act.ts`)
- Observe → Tool context: uses session (evidence: `src/tools/observe.ts`)
- Extract → Tool context: uses session (evidence: `src/tools/extract.ts`)
- Session tools → Session manager: manages session (evidence: `src/tools/session.ts`)
- Tool context → Session manager: owns sessions (evidence: `src/context.ts`)
- Session manager → Stagehand runtime: creates and closes (evidence: `src/sessionManager.ts`)
- Stagehand runtime → Browserbase: connects session (evidence: `README.md`)
- Navigate → Web page: navigates (evidence: `src/tools/navigate.ts`)
- Stagehand runtime → Web page: controls browser (evidence: `README.md`)
- Configuration → Session manager: configures sessions
- MCP transports → MCP server: serves MCP
- Tool context → MCP resources: lists and reads (evidence: `src/context.ts`)
- MCP sampling → MCP server: sampling integration