{
"canonical_name": "browserbase/mcp-server-browserbase",
"compilation_id": "pack_f39b6f797a0f4aec942b0614db2399c2",
"created_at": "2026-05-21T16:47:59.905397+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx @browserbasehq/mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx @browserbasehq/mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_fc81feab2afc465b8303c6dd5895b62d"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_52dd13b0d2d9fc25009c68f4f6fbccaf",
"canonical_name": "browserbase/mcp-server-browserbase",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/browserbase/mcp-server-browserbase",
"slug": "mcp-server-browserbase",
"source_packet_id": "phit_91d1008fa4d04fab89c5b128a82bd7a8",
"source_validation_id": "dval_c54342a96f3141908b3d3ae8102ada57"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 358,
"github_stars": 3343,
"one_liner_en": "Allow LLMs to control a browser with Browserbase and Stagehand",
"one_liner_zh": "Allow LLMs to control a browser with Browserbase and Stagehand",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "mcp-server-browserbase",
"title_zh": "mcp-server-browserbase 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_91d1008fa4d04fab89c5b128a82bd7a8",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-server-browserbase",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx @browserbasehq/mcp",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/browserbase/mcp-server-browserbase#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Allow LLMs to control a browser with Browserbase and Stagehand"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Your MCP server is now indexed on Joy Trust Network",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add MCPpedia security badge to README",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add policy enforcement for cloud browser sessions",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 16,
"forks": 358,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3343
},
"source_url": "https://github.com/browserbase/mcp-server-browserbase",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Allow LLMs to control a browser with Browserbase and Stagehand",
"title": "mcp-server-browserbase 能力包",
"trial_prompt": "# mcp-server-browserbase - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for browserbase/mcp-server-browserbase.\n\nProject:\n- Name: mcp-server-browserbase\n- Repository: https://github.com/browserbase/mcp-server-browserbase\n- Summary: Allow LLMs to control a browser with Browserbase and Stagehand\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Allow LLMs to control a browser with Browserbase and Stagehand\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Allow LLMs to control a browser with Browserbase and Stagehand\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. architecture-overview: System Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-tools: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n5. session-management: Session Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/browserbase/mcp-server-browserbase\n- https://github.com/browserbase/mcp-server-browserbase#readme\n- README.md\n- package.json\n- src/index.ts\n- cli.js\n- Dockerfile\n- src/server.ts\n- src/program.ts\n- src/types/types.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Add policy enforcement for cloud browser sessions（https://github.com/browserbase/mcp-server-browserbase/issues/176）；github/github_issue: Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alte（https://github.com/browserbase/mcp-server-browserbase/issues/127）；github/github_issue: Add MCPpedia security badge to README（https://github.com/browserbase/mcp-server-browserbase/issues/175）；github/github_issue: Your MCP server is now indexed on Joy Trust Network（https://github.com/browserbase/mcp-server-browserbase/issues/174）；github/github_release: v3.0.0（https://github.com/browserbase/mcp-server-browserbase/releases/tag/v3.0.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Add policy enforcement for cloud browser sessions",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/176"
},
{
"kind": "github_issue",
"source": "github",
"title": "Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alte",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/127"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add MCPpedia security badge to README",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/175"
},
{
"kind": "github_issue",
"source": "github",
"title": "Your MCP server is now indexed on Joy Trust Network",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/174"
},
{
"kind": "github_release",
"source": "github",
"title": "v3.0.0",
"url": "https://github.com/browserbase/mcp-server-browserbase/releases/tag/v3.0.0"
}
],
"status": "已收录 5 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Allow LLMs to control a browser with Browserbase and Stagehand",
"effort": "安装已验证",
"forks": 358,
"icon": "link",
"name": "mcp-server-browserbase 能力包",
"risk": "可发布",
"slug": "mcp-server-browserbase",
"stars": 3343,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/browserbase/mcp-server-browserbase Project Manual\n\nGenerated on: 2026-05-21 16:46:07 UTC\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Quick Start Guide](#quickstart)\n- [System Architecture Overview](#architecture-overview)\n- [Transport Layer](#transport-layer)\n- [MCP Tools Reference](#mcp-tools)\n- [Session Management](#session-management)\n- [Configuration Options](#configuration-options)\n- [Model Configuration](#model-configuration)\n- [Deployment Methods](#deployment-methods)\n- [Testing](#testing)\n\n\n\n## Introduction\n\n### Related Pages\n\nRelated topics: [System Architecture Overview](#architecture-overview), [Quick Start Guide](#quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n \n\n# Introduction\n\nThe **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]()\n\n## Project Overview\n\nThis 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]()\n\n| Attribute | Value |\n|-----------|-------|\n| **Package Name** | `@browserbasehq/mcp` |\n| **Current Version** | `3.0.0` |\n| **License** | Apache 2.0 |\n| **Repository** | `browserbase/mcp-server-browserbase` |\n| **Package Manager** | pnpm 10.12.4 |\n\nSource: [package.json]()\n\n## Architecture Overview\n\nThe MCP server follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[MCP Client] -->|MCP Protocol| B[MCP Server Entry]\n B --> C[Context Manager]\n C --> D[Session Manager]\n C --> E[Tools Registry]\n D --> F[Stagehand Instances]\n F --> G[Browserbase Cloud]\n E --> H[start]\n E --> I[navigate]\n E --> J[act]\n E --> K[observe]\n E --> L[extract]\n E --> M[end]\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|---------------|---------|\n| **Server Entry** | `src/index.ts` | MCP server initialization, tool registration, and request handling |\n| **Context Manager** | `src/context.ts` | Executes tools and manages tool lifecycle |\n| **Session Manager** | `src/sessionManager.ts` | Manages Stagehand browser sessions with lifecycle handling |\n| **Tools Registry** | `src/tools/index.ts` | Defines available MCP tools |\n| **Type Definitions** | `src/types/types.ts` | TypeScript interfaces for sessions, tools, and configurations |\n\nSource: [src/index.ts](), [src/context.ts](), [src/sessionManager.ts](), [src/types/types.ts]()\n\n## Available Tools\n\nThe MCP server exposes six primary tools for browser automation:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `start` | Create a new browser session | `{ apiKey?, projectId?, modelName?, modelApiKey?, browserbaseSessionID?, meta? }` |\n| `navigate` | Navigate to a URL | `{ url: string }` |\n| `act` | Perform an action on the page | `{ action: string }` |\n| `observe` | Observe actionable elements on the page | `{ instruction: string }` |\n| `extract` | Extract data from the page | `{ instruction?: string }` |\n| `end` | Close the browser session | _(none)_ |\n\nSource: [README.md](), [CHANGELOG.md]()\n\n## Configuration Options\n\n### Command-Line Flags\n\nThe server accepts the following configuration flags:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--proxies` | Enable proxy support for sessions | `false` |\n| `--viewportWidth` | Browser viewport width in pixels | `1280` |\n| `--viewportHeight` | Browser viewport height in pixels | `768` |\n| `--modelName` | Stagehand model identifier | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey` | API key for custom model provider | _(none)_ |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [README.md]()\n\n### Configuration Schema\n\nThe server validates configuration using Zod with the following schema:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Browserbase Verified Identity\"),\n advancedStealth: z.boolean().optional().describe(\"Deprecated alias for verified\"),\n keepAlive: z.boolean().optional().describe(\"Keep session alive\"),\n context: z.object({\n contextId: z.string().optional().describe(\"Context ID\")\n }).optional()\n});\n```\n\nSource: [src/index.ts]()\n\n### Required Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `BROWSERBASE_API_KEY` | Your Browserbase API key | Yes |\n| `BROWSERBASE_PROJECT_ID` | Your Browserbase Project ID | Yes |\n| `GEMINI_API_KEY` | Gemini API key (for default model) | Yes |\n\nSource: [README.md](), [server.json]()\n\n## Transport Types\n\nThe MCP server supports two transport mechanisms for communication:\n\n```mermaid\ngraph LR\n A[MCP Client] --> B[SHTTP Transport]\n A --> C[STDIO Transport]\n B -->|HTTP| D[Hosted Server
mcp.browserbase.com]\n C -->|stdin/stdout| E[Local Server]\n E --> F[Direct Installation]\n E --> G[Docker Container]\n```\n\n### SHTTP (Hosted)\n\nThe hosted solution runs at `https://mcp.browserbase.com/mcp` and is the recommended approach for most users. Source: [README.md]()\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n### STDIO (Self-Hosted)\n\nSelf-hosted deployment supports both direct npm installation and Docker containers. Source: [README.md]()\n\n**Via NPM:**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**Via Docker:**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"BROWSERBASE_API_KEY\", \"-e\", \"BROWSERBASE_PROJECT_ID\", \"-e\", \"GEMINI_API_KEY\", \"mcp-browserbase\"]\n }\n }\n}\n```\n\n## Session Management\n\nThe SessionManager handles browser session lifecycle with automatic validation and recreation:\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: No sessions\n Idle --> Creating: start tool called\n Creating --> Active: Session created\n Active --> Validating: Periodic check\n Validating --> Active: Session valid\n Validating --> Recreating: Session stale\n Recreating --> Creating: Retry\n Active --> Closing: end tool called\n Closing --> Idle: Cleanup complete\n```\n\n### Session Validation\n\nSessions 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]()\n\n## Model Configuration\n\nStagehand 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]()\n\n### Supported Models\n\nThe model must be supported by Stagehand. For a full list of supported models, see the [Stagehand documentation](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\n### Custom Model Setup\n\nWhen using a custom model, provide both the model name and API key:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ]\n }\n }\n}\n```\n\nSource: [README.md]()\n\n## Version History\n\n### v3.0.0 (Breaking Changes)\n\nThe latest major version introduced significant changes to align with the hosted MCP server:\n\n- Tool names renamed (e.g., `browserbase_session_create` → `start`)\n- Removed tools: `browserbase_screenshot`, `browserbase_stagehand_get_url`, `browserbase_stagehand_agent`\n- Default model changed from `gemini-2.0-flash` to `google/gemini-2.5-flash-lite`\n- Removed Smithery references and dependencies\n\nSource: [CHANGELOG.md]()\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@browserbasehq/sdk` | `^2.6.0` | Browserbase API client |\n| `@browserbasehq/stagehand` | `^3.3.0` | AI browser automation |\n| `@modelcontextprotocol/sdk` | `^1.13.1` | MCP protocol implementation |\n| `zod` | `^3.25.67` | Schema validation |\n| `commander` | `^14.0.0` | CLI argument parsing |\n\nSource: [package.json]()\n\n## Resources and Sampling\n\nThe server implements MCP's optional capabilities for completeness:\n\n- **Resources**: Currently returns empty (no custom resources defined)\n- **Sampling**: Capability declared but depends on client support\n\nSource: [src/mcp/resources.ts](), [src/mcp/sampling.ts]()\n\n## See Also\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n- [Stagehand Evals](https://www.stagehand.dev/evals)\n\n---\n\n\n\n## Quick Start Guide\n\n### Related Pages\n\nRelated topics: [Introduction](#introduction), [Deployment Methods](#deployment-methods)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# Quick Start Guide\n\nThe 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.\n\n## Overview\n\nThe 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.\n\n### Key Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| **Browser Navigation** | Navigate to URLs and interact with web pages |\n| **Element Interaction** | Click, type, and perform actions on page elements |\n| **Data Extraction** | Extract structured data from web pages |\n| **Session Management** | Create and manage persistent browser sessions |\n| **Proxy Support** | Route traffic through Browserbase proxies |\n| **Stealth Mode** | Use Browserbase Verified Identity for undetected automation |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Architecture\n\n```mermaid\ngraph TD\n A[MCP Client] -->|HTTP or STDIO| B[MCP Server]\n B -->|Tool Calls| C[Context Handler]\n C -->|Session Mgmt| D[Stagehand Instance]\n D -->|Browser Automation| E[Browserbase Cloud]\n E -->|CDP| F[Remote Browser]\n \n G[BROWSERBASE_API_KEY] --> B\n H[BROWSERBASE_PROJECT_ID] --> B\n I[GEMINI_API_KEY] --> B\n```\n\nThe 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.\n\nSource: [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts:32-48)\nSource: [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Available Tools\n\nThe server exposes the following MCP tools that can be called by any compatible MCP client:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `start` | Create a new browser session | `{ apiKey?, projectId?, modelName?, modelApiKey? }` |\n| `end` | Close an existing browser session | `{ sessionId: string }` |\n| `navigate` | Navigate to a URL | `{ url: string }` |\n| `act` | Perform an action on the page | `{ action: string }` |\n| `observe` | Observe actionable elements on the page | `{ instruction: string }` |\n| `extract` | Extract data from the page | `{ instruction?: string }` |\n\nSource: [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Methods\n\nThe server supports multiple transport mechanisms and deployment options depending on your requirements.\n\n```mermaid\ngraph LR\n A[Deployment Options] --> B[SHTTP Hosted]\n A --> C[NPM Package]\n A --> D[Direct Installation]\n A --> E[Docker]\n \n B --> F[Easiest Setup]\n C --> G[Managed Runtime]\n D --> H[Full Control]\n E --> I[Containerized]\n```\n\n### Method 1: SHTTP (Hosted MCP)\n\nThe 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.\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:42-44)\n\n#### Configuration for SHTTP-Clients\n\nIf your MCP client supports HTTP transport:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### Configuration for Non-SHTTP Clients\n\nIf your client only supports STDIO but can invoke external processes:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:46-61)\n\n### Method 2: NPM Package (Recommended for Self-Hosted)\n\nThis method runs the server locally while still using Browserbase's cloud infrastructure for browser sessions.\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nThe package is published as `@browserbasehq/mcp` with version tracking available on npm.\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:82-96)\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:2-6)\n\n### Method 3: Direct Installation\n\nFor full control over the runtime environment, clone and build the repository locally.\n\n#### Prerequisites\n\n- Node.js 18+ \n- npm or pnpm\n- Git\n\n#### Installation Steps\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\nThe build script compiles TypeScript and sets executable permissions on the output files:\n\n```bash\n\"build\": \"tsc && shx chmod +x dist/*.js\"\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:103-115)\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:21)\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Method 4: Docker\n\nContainerized deployment provides isolation and consistency across environments.\n\n#### Build the Image\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:116-143)\n\n## Configuration Options\n\nThe server accepts configuration through environment variables and command-line arguments.\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BROWSERBASE_API_KEY` | Yes | Your Browserbase API key for session management |\n| `BROWSERBASE_PROJECT_ID` | Yes | Your Browserbase Project ID |\n| `GEMINI_API_KEY` | Yes | Gemini API key for LLM inference (default model) |\n\nSource: [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json:17-34)\n\n### Command-Line Flags\n\n| Flag | Description |\n|------|-------------|\n| `--proxies` | Enable Browserbase proxy sessions |\n| `--modelName` | Specify a different model to use (must be supported by Stagehand) |\n| `--modelApiKey` | API key for the custom model |\n| `--keepAlive` | Keep the browser session alive after tool execution |\n| `--verified` | Use Browserbase Verified Identity (Scale Plan only) |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:78-80)\nSource: [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts:15-35)\n\n### Default Configuration\n\nThe server uses sensible defaults that can be overridden:\n\n| Setting | Default Value |\n|---------|---------------|\n| Default Model | `google/gemini-2.5-flash-lite` |\n| Browser Width | 1024px |\n| Browser Height | 768px |\n| Proxies | Disabled |\n| Keep Alive | Disabled |\n\nSource: [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts:37-48)\n\n## Custom Model Configuration\n\nTo use a different LLM model, you must use a self-hosted deployment (not the hosted MCP server) and specify the model name:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\", \"--modelName\", \"anthropic/claude-sonnet-4-20250514\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"ANTHROPIC_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nThe model must be supported in Stagehand. Check the supported models documentation at [docs.stagehand.dev](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:154-167)\n\n## Session Workflow\n\nBrowser sessions follow a specific lifecycle managed by the MCP server:\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Browserbase\n participant Browser\n \n Client->>Server: start session\n Server->>Browserbase: Create Browserbase Session\n Browserbase->>Browser: Launch Remote Browser\n Browser->>Server: Session Established\n Server->>Client: sessionId returned\n \n Client->>Server: navigate { url }\n Server->>Browser: Load URL\n Browser->>Server: Page Loaded\n Server->>Client: Navigation Complete\n \n Client->>Server: act { action }\n Server->>Browser: Execute Action\n Browser->>Server: Action Result\n Server->>Client: Action Complete\n \n Client->>Server: extract { instruction }\n Server->>Browser: Extract Data\n Browser->>Server: Extracted Data\n Server->>Client: Data Returned\n \n Client->>Server: end session\n Server->>Browserbase: Close Session\n Browserbase->>Browser: Terminate\n Server->>Client: Session Closed\n```\n\n### Session Creation Parameters\n\nWhen starting a session, the following parameters are available:\n\n```typescript\ntype CreateSessionParams = {\n apiKey?: string; // Override default API key\n projectId?: string; // Override default project ID\n modelName?: string; // Use custom model\n modelApiKey?: string; // API key for custom model\n browserbaseSessionID?: string; // Resume existing session\n browserbaseSessionCreateParams?: any; // Browserbase-specific options\n meta?: Record; // Session metadata\n};\n```\n\nSource: [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts:10-20)\n\n## Verifying Installation\n\nAfter configuring your MCP client, verify the connection by checking that the server responds to tool list requests. The server should advertise the following tools:\n\n1. `start` - Session management\n2. `end` - Session cleanup\n3. `navigate` - URL navigation\n4. `act` - Page interactions\n5. `observe` - Element detection\n6. `extract` - Data extraction\n\nYou can use the MCP inspector for debugging:\n\n```bash\nnpx @modelcontextprotocol/inspector build/index.js\n```\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:24)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"browserbaseApiKey is required\" | Set the `BROWSERBASE_API_KEY` environment variable |\n| \"browserbaseProjectId is required\" | Set the `BROWSERBASE_PROJECT_ID` environment variable |\n| Model not supported | Check [Stagehand supported models](https://docs.stagehand.dev/examples/custom_llms#supported-llms) |\n| Docker connection issues | Ensure environment variables are passed with `-e` flags |\n\nSource: [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts:8-14)\n\n## Development\n\nFor local development and testing:\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the project\npnpm build\n\n# Run tests\npnpm test\n\n# Watch mode for development\npnpm watch\n\n# Lint code\npnpm lint\n\n# Format code\npnpm format\n```\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:21-31)\n\n## Next Steps\n\n- Review the [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction) for advanced usage\n- Explore the [MCP Specification](https://spec.modelcontextprotocol.io/) for protocol details\n- Check the [Stagehand Documentation](https://docs.stagehand.dev/) for browser automation capabilities\n- Report issues at [GitHub Issues](https://github.com/browserbase/mcp-server-browserbase/issues)\n\n---\n\n\n\n## System Architecture Overview\n\n### Related Pages\n\nRelated topics: [Transport Layer](#transport-layer), [MCP Tools Reference](#mcp-tools), [Session Management](#session-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# System Architecture Overview\n\nThe 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.\n\n## Architecture Layers\n\nThe system follows a layered architecture pattern that separates concerns between transport, protocol, execution, and browser automation.\n\n```mermaid\ngraph TD\n subgraph \"Transport Layer\"\n STDIO[STDIO Transport]\n SHTTP[SHTTP Transport]\n end\n \n subgraph \"MCP Protocol Layer\"\n MCP_SDK[MCP SDK Server]\n Tools[MCP Tools]\n Resources[Resources]\n Sampling[Sampling]\n end\n \n subgraph \"Application Layer\"\n Context[Context Controller]\n Config[Configuration Resolver]\n SessionMgr[Session Manager]\n end\n \n subgraph \"Browser Automation Layer\"\n Stagehand[Stagehand Instance]\n Browserbase[Browserbase SDK]\n end\n \n STDIO --> MCP_SDK\n SHTTP --> MCP_SDK\n MCP_SDK --> Tools\n MCP_SDK --> Resources\n MCP_SDK --> Sampling\n Context --> SessionMgr\n SessionMgr --> Stagehand\n Stagehand --> Browserbase\n```\n\n**Source:** [src/index.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts) | [src/context.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Core Components\n\n### 1. Entry Point and CLI (program.ts)\n\nThe application entry point uses Commander.js to parse command-line arguments and initialize the server.\n\n```mermaid\ngraph LR\n CLI[CLI Arguments] --> Program[program.ts]\n Program --> Config[resolveConfig]\n Config --> CreateServer[createServer]\n CreateServer --> Transport[Start Transport]\n```\n\n**Source:** [src/program.ts:1-80](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n\n**Command-line options supported:**\n\n| Flag | Type | Description | Default |\n|------|------|-------------|---------|\n| `--browserbaseApiKey` | string | Browserbase API Key | env.BROWSERBASE_API_KEY |\n| `--browserbaseProjectId` | string | Browserbase Project ID | env.BROWSERBASE_PROJECT_ID |\n| `--proxies` | boolean | Enable Browserbase proxies | false |\n| `--verified` | boolean | Use Verified Identity (Scale Plan) | false |\n| `--advancedStealth` | boolean | Deprecated alias for verified | false |\n| `--contextId` | string | Browserbase Context ID | undefined |\n| `--persist` | boolean | Keep session alive | false |\n| `--port` | number | SHTTP transport port | undefined (uses STDIO) |\n| `--host` | string | SHTTP bind host | undefined |\n| `--browserWidth` | number | Viewport width | 1024 |\n| `--browserHeight` | number | Viewport height | 768 |\n| `--modelName` | string | Stagehand model | google/gemini-2.5-flash-lite |\n| `--modelApiKey` | string | Custom model API key | env.GEMINI_API_KEY |\n| `--experimental` | boolean | Enable experimental features | false |\n\n**Source:** [src/config.ts:15-28](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 2. Configuration System\n\nThe configuration system uses Zod for schema validation and implements a merge strategy: Defaults < File Config < CLI Options.\n\n```mermaid\ngraph TD\n Default[Default Config] --> Merge[mergeConfig]\n File[File Config] --> Merge\n CLI[CLI Options] --> Merge\n Merge --> Normalize[normalizeVerifiedConfig]\n Normalize --> FinalConfig[Resolved Config]\n FinalConfig --> AddEnvVars[Add Env Vars]\n AddEnvVars --> Validate[Validation]\n```\n\n**Source:** [src/config.ts:50-75](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n**Configuration schema (Zod):**\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Use Browserbase Verified Identity\"),\n keepAlive: z.boolean().optional().describe(\"Keep session alive\"),\n context: z.object({\n contextId: z.string().optional()\n }).optional()\n});\n```\n\n**Source:** [src/index.ts:30-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### 3. MCP Server (server.ts + index.ts)\n\nThe MCP server is built on the @modelcontextprotocol/sdk and handles tool registration, request routing, and protocol compliance.\n\n**Source:** [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts) | [src/index.ts:80-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n**MCP Server capabilities:**\n\n| Capability | Implementation | Description |\n|------------|----------------|-------------|\n| Tools | TOOLS array | Browser automation operations |\n| Resources | RESOURCE_TEMPLATES | URI-based resource access |\n| Sampling | SAMPLING_CAPABILITY | Server-initiated LLM completions |\n\n### 4. Context Controller (context.ts)\n\nThe Context class serves as the central orchestrator, maintaining references to the MCP server instance, configuration, and SessionManager.\n\n```mermaid\nclassDiagram\n class Context {\n +Server server\n +Config config\n -SessionManager sessionManager\n +getServer() Server\n +getSessionManager() SessionManager\n +getStagehand(sessionId?) Promise~Stagehand~\n +run(tool, params) CallToolResult\n }\n \n class SessionManager {\n -Map sessions\n -string activeSessionId\n +createSession(config) Promise~Session~\n +getSession(id) Promise~Session~\n +closeSession(id) Promise~void~\n +getActiveSessionId() string\n }\n \n Context --> SessionManager\n```\n\n**Source:** [src/context.ts:15-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n### 5. Session Manager (sessionManager.ts)\n\nThe SessionManager handles lifecycle management of browser sessions, creating and caching Stagehand instances per session.\n\n**Source:** [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n**Session lifecycle:**\n\n```mermaid\nstateDiagram-v2\n [*] --> NoSession: Initial State\n NoSession --> Creating: start tool called\n Creating --> Active: Stagehand initialized\n Active --> Active: navigate/act/observe/extract\n Active --> Closing: end tool called\n Closing --> NoSession: Session closed\n Closing --> Active: Error, retry\n```\n\n### 6. Tool System\n\nTools are the primary interface for MCP clients to interact with browser automation capabilities.\n\n**Source:** [src/tools/index.ts:1-25](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n**Available tools:**\n\n| Tool | Description | Input Schema |\n|------|-------------|--------------|\n| `start` | Create new browser session | `{ contextId?: string, proxies?: boolean, verified?: boolean }` |\n| `end` | Close browser session | `{}` |\n| `navigate` | Navigate to URL | `{ url: string }` |\n| `act` | Perform action on page | `{ action: string }` |\n| `observe` | Observe actionable elements | `{ instruction: string }` |\n| `extract` | Extract data from page | `{ instruction?: string }` |\n\n**Source:** [src/tools/index.ts:10-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n**Tool registration flow:**\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Context as Context\n participant SessionMgr as SessionManager\n participant Stagehand as Stagehand\n \n Client->>Server: Call Tool\n Server->>Context: run(tool, params)\n Context->>SessionMgr: getSession(id)\n SessionMgr->>Stagehand: Get/Create Instance\n Stagehand->>Stagehand: Execute operation\n Stagehand-->>Context: Result\n Context-->>Server: CallToolResult\n Server-->>Client: JSON-RPC Response\n```\n\n## Transport Layer\n\nThe server supports two transport mechanisms for MCP communication.\n\n**Source:** [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n| Transport | Use Case | Configuration |\n|-----------|----------|---------------|\n| STDIO | Local CLI tools, Claude Desktop | Default when no port specified |\n| SHTTP | HTTP clients, Remote servers | `--port` flag required |\n\n**STDIO Configuration (Docker):**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"mcp-browserbase\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Data Flow\n\n### Tool Execution Pipeline\n\n```mermaid\ngraph TD\n Request[Tool Request] --> Validate[Zod Validation]\n Validate --> Authenticate[Auth Check]\n Authenticate --> GetSession[Get Session]\n GetSession --> GetStagehand[Get Stagehand]\n GetStagehand --> Execute[Execute Tool]\n Execute --> Transform[Transform Result]\n Transform --> Response[JSON-RPC Response]\n \n Execute -->|Error| ErrorHandler[Error Handler]\n ErrorHandler --> Response\n```\n\n**Source:** [src/index.ts:110-145](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### Configuration Merging Strategy\n\n```mermaid\ngraph LR\n A[Defaults] -->|Low Priority| M[Merge Config]\n B[Environment Vars] -->|Medium Priority| M\n C[CLI Arguments] -->|High Priority| M\n M --> R[Resolved Config]\n```\n\n**Source:** [src/config.ts:40-65](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Type System\n\n**Source:** [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n\n### Key Types\n\n| Type | Definition | Usage |\n|------|------------|-------|\n| `MCPTool` | Tool definition with schema | Tool registration |\n| `MCPToolsArray` | Array of MCPTool | Tool collection |\n| `Config` | Server configuration interface | All config operations |\n| `CLIOptions` | Command-line options | CLI parsing |\n\n### Configuration Interface (config.d.ts)\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies: boolean;\n verified?: boolean;\n modelName: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n viewPort?: {\n browserWidth: number;\n browserHeight: number;\n };\n server?: {\n port?: number;\n host?: string;\n };\n}\n```\n\n**Source:** [config.d.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Dependencies Architecture\n\n**Source:** [package.json:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n```mermaid\ngraph BT\n MCP[\"@modelcontextprotocol/sdk\"]\n Stagehand[\"@browserbasehq/stagehand\"]\n BrowserbaseSDK[\"@browserbasehq/sdk\"]\n Zod[\"zod\"]\n Commander[\"commander\"]\n \n mcp-server-browserbase --> MCP\n mcp-server-browserbase --> Stagehand\n mcp-server-browserbase --> BrowserbaseSDK\n mcp-server-browserbase --> Zod\n mcp-server-browserbase --> Commander\n```\n\n### Core Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP protocol implementation |\n| `@browserbasehq/stagehand` | ^3.3.0 | AI browser automation |\n| `@browserbasehq/sdk` | ^2.6.0 | Browserbase API client |\n| `zod` | ^3.25.67 | Schema validation |\n| `commander` | ^14.0.0 | CLI framework |\n\n## Error Handling\n\nThe server implements structured error handling at multiple levels:\n\n**Source:** [src/index.ts:125-140](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```mermaid\ngraph TD\n Error[Error Thrown] --> Log[Log to stderr]\n Log --> Format[Format error message]\n Format --> Throw[Throw MCP Error]\n Throw --> Response[JSON-RPC Error Response]\n \n Response --> Client[Client receives error]\n```\n\n**Error message format:**\n```\n[MCP Error] {ISO timestamp} Error running tool {tool_name}: {error_message}\n```\n\n## Module Structure Summary\n\n```\nmcp-server-browserbase/\n├── src/\n│ ├── index.ts # Server factory, tool registration\n│ ├── server.ts # MCP server initialization\n│ ├── program.ts # CLI entry point\n│ ├── context.ts # Central controller\n│ ├── config.ts # Configuration resolver\n│ ├── sessionManager.ts # Session lifecycle\n│ ├── transport.ts # STDIO/SHTTP transport\n│ ├── types/\n│ │ └── types.ts # TypeScript definitions\n│ ├── mcp/\n│ │ ├── resources.ts # MCP resources\n│ │ └── sampling.ts # MCP sampling\n│ └── tools/\n│ ├── index.ts # Tool exports\n│ ├── session.ts # start/end tools\n│ ├── navigate.ts # navigate tool\n│ ├── act.ts # act tool\n│ ├── observe.ts # observe tool\n│ └── extract.ts # extract tool\n├── config.d.ts # Config interface definition\n├── package.json # Dependencies and scripts\n└── README.md # Documentation\n```\n\n## Deployment Modes\n\n### NPM Package (npx)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Docker Container\n\n```bash\ndocker build -t mcp-browserbase .\n```\n\n### Hosted MCP Server\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n**Source:** [README.md:50-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n---\n\n\n\n## Transport Layer\n\n### Related Pages\n\nRelated topics: [System Architecture Overview](#architecture-overview), [Deployment Methods](#deployment-methods)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# Transport Layer\n\n## Overview\n\nThe 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.\n\nThe transport layer is responsible for:\n\n- Accepting incoming connections from MCP clients\n- Managing server sessions for stateful communication\n- Routing requests to appropriate handlers\n- Handling the serialization and deserialization of MCP protocol messages\n\nSource: [src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Supported Transport Protocols\n\nThe MCP server supports two transport protocols:\n\n| Transport Type | Description | Use Case |\n|----------------|-------------|----------|\n| **STDIO** | Standard Input/Output communication via process streams | Local development, CLI tools, direct execution |\n| **SHTTP** | Streamable HTTP transport using the MCP HTTP extension | Hosted deployments, production environments, remote access |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### STDIO Transport\n\nThe STDIO transport uses standard input and output streams for communication. This is the default transport when no server configuration is provided.\n\n```mermaid\ngraph LR\n A[MCP Client] -->|stdin| B[MCP Server]\n B -->|stdout| A\n```\n\nThe STDIO transport is initialized when both `port` and `host` are undefined in the server configuration. Source: [config.d.ts:45-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### SHTTP (Streamable HTTP) Transport\n\nThe SHTTP transport uses HTTP with session management for stateful communication. It supports multiple concurrent sessions through a session ID mechanism.\n\n```mermaid\ngraph TD\n A[HTTP Request] --> B{Session ID Present?}\n B -->|Yes| C[Existing Session]\n B -->|No| D[Create New Session]\n C --> E[StreamableHTTPServerTransport]\n D --> F[Generate UUID Session ID]\n F --> E\n E --> G[Server Instance]\n G --> H[Tool Execution]\n```\n\nSource: [src/transport.ts:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Architecture\n\n### Server Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transport\n participant Server\n participant SessionManager\n participant Stagehand\n\n Client->>Transport: HTTP Request\n Transport->>Transport: Check Session ID\n alt No Session\n Transport->>Transport: Generate UUID\n Transport->>Server: Create Instance\n Server->>SessionManager: Initialize Session\n Server->>Stagehand: Create Browser Context\n else Has Session\n Transport->>Server: Route to Existing Session\n end\n Server->>Transport: Process Request\n Transport->>Client: Response\n```\n\n### Component Responsibilities\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `startStdioTransport` | [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts) | Initializes STDIO transport with the MCP SDK |\n| `startHttpTransport` | [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts) | Creates HTTP server with session management |\n| `ServerList` | [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts) | Manages server instance lifecycle |\n| `Context` | [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts) | Holds server state and session information |\n\n## Session Management\n\nThe SHTTP transport implements a session-based model to maintain state across multiple requests.\n\n### Session Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> NoSession: No Session ID Header\n NoSession --> Active: POST /mcp\n Active --> Active: Subsequent Requests\n Active --> Closed: Transport Close Event\n Closed --> [*]\n```\n\n### Session Storage\n\nSessions are stored in an in-memory `Map` structure:\n\n```typescript\nconst streamableSessions = new Map();\n```\n\n| Operation | Method | Description |\n|-----------|--------|-------------|\n| Create | POST without session ID | Generates new UUID, creates transport |\n| Retrieve | Request with session ID | Looks up existing transport from Map |\n| Delete | Transport close event | Removes session from Map on `onclose` |\n\nSource: [src/transport.ts:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Configuration\n\n### Server Transport Options\n\nThe transport layer is configured through the `server` configuration object:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `port` | `number` | `undefined` | Port for SHTTP transport. When `undefined`, uses STDIO |\n| `host` | `string` | `\"localhost\"` | Host interface to bind. Use `\"0.0.0.0\"` for external access |\n\nSource: [config.d.ts:40-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Configuration Resolution\n\nThe configuration is resolved in order of precedence:\n\n1. **Default values** - Built-in defaults for all options\n2. **Environment variables** - `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, etc.\n3. **CLI options** - Command-line arguments passed at runtime\n\n```mermaid\ngraph LR\n A[CLI Options] --> B[mergeConfig]\n C[Default Config] --> B\n B --> D[normalizeVerifiedConfig]\n D --> E[Final Config]\n```\n\nSource: [src/config.ts:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BROWSERBASE_API_KEY` | Yes | Browserbase authentication key |\n| `BROWSERBASE_PROJECT_ID` | Yes | Browserbase project identifier |\n| `GEMINI_API_KEY` | For default model | Google AI API key (falls back to `GOOGLE_API_KEY`) |\n\nSource: [src/config.ts:55-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Request Handling\n\n### HTTP Request Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Incoming HTTP Request │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ URL Validation │\n│ Check: url.pathname.startsWith(\"/mcp\") │\n└─────────────────────────────────────────────────────────────┘\n │\n ┌───────────────┴───────────────┐\n │ │\n ▼ ▼\n [Invalid URL] [Valid /mcp]\n Return 400 Continue\n │ │\n ▼ ▼\n ┌─────────┐ ┌─────────────────────────┐\n │ End │ │ Session Check │\n └─────────┘ │ mcp-session-id header? │\n └─────────────────────────┘\n │\n ┌───────────────┴───────────────┐\n │ │\n ▼ ▼\n [Session Found] [No Session]\n Route to transport Create new transport\n from Map Generate UUID\n │ │\n │ ┌────────┴────────┐\n │ │ Create Server │\n │ │ Connect │\n │ └────────────────┘\n ▼ │\n ┌─────────────────┐ │\n │ Handle Request │◄──────────────────────┘\n │ via Transport │\n └─────────────────┘\n```\n\nSource: [src/transport.ts:35-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Security Considerations\n\nThe transport layer implements several security measures:\n\n| Aspect | Implementation | Notes |\n|--------|---------------|-------|\n| **Default Binding** | `localhost` | Only accepts local connections by default |\n| **External Access** | Explicit `host: \"0.0.0.0\"` | Requires deliberate configuration |\n| **Session Isolation** | Session ID validation | Requests without valid session ID rejected |\n| **Session Cleanup** | `onclose` handler | Automatic removal of closed sessions |\n\nSource: [config.d.ts:47-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Security Recommendations\n\n1. **Development**: Use default `localhost` binding\n2. **Production**: If external access required:\n - Use firewall rules to restrict access\n - Consider VPN or reverse proxy\n - Implement authentication at the application layer\n3. **Hosted Service**: Use Browserbase hosted MCP at `https://mcp.browserbase.com/mcp` for managed security\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Usage Examples\n\n### STDIO Configuration (Self-Hosted)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### SHTTP Configuration (Hosted)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n### Docker with SHTTP\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ]\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## CLI Options\n\nThe transport layer can be configured via command-line arguments:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--browserbaseApiKey ` | Browserbase API Key | Environment variable |\n| `--browserbaseProjectId ` | Browserbase Project ID | Environment variable |\n| `--proxies` | Enable Browserbase proxies | `false` |\n| `--verified` | Use Verified Identity | `false` |\n| `--port ` | SHTTP server port | STDIO if unset |\n| `--host ` | SHTTP bind address | `localhost` |\n| `--browserWidth ` | Viewport width | `1024` |\n| `--browserHeight ` | Viewport height | `768` |\n| `--modelName ` | Stagehand model | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey ` | Custom model API key | Required for custom models |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [src/config.ts:15-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Error Handling\n\nThe transport layer implements robust error handling:\n\n| Error Scenario | Handling | Response |\n|----------------|----------|----------|\n| Missing URL | Return 400 | `\"Bad request: missing URL\"` |\n| Session not found | Return 404 | `\"Session not found\"` |\n| Invalid request method | Return 400 | `\"Invalid request\"` |\n| Tool execution failure | Log to stderr, throw MCP error | Formatted error message |\n\nSource: [src/transport.ts:20-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\nError responses are logged with ISO timestamps for debugging:\n\n```typescript\nprocess.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n);\n```\n\nSource: [src/index.ts:120-125](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n## Dependencies\n\nThe transport layer relies on the following key dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | `^1.13.1` | MCP protocol implementation, transport abstractions |\n| `@browserbasehq/stagehand` | `^3.3.0` | Browser automation capabilities |\n| `http` | Node.js built-in | HTTP server for SHTTP transport |\n| `crypto` | Node.js built-in | UUID generation for session IDs |\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n---\n\n\n\n## MCP Tools Reference\n\n### Related Pages\n\nRelated topics: [Session Management](#session-management), [System Architecture Overview](#architecture-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n- [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n- [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n \n\n# MCP Tools Reference\n\nThis page documents all available MCP (Model Context Protocol) tools provided by the Browserbase MCP Server for AI-powered web browser automation.\n\n## Overview\n\nThe 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.\n\nSource: [src/tools/index.ts:1-18](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Architecture\n\nThe tools module follows a modular architecture where each tool is defined as an independent module with a consistent schema and handler structure.\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[TOOLS Array]\n B --> C[Session Tools]\n B --> D[navigateTool]\n B --> E[actTool]\n B --> F[observeTool]\n B --> G[extractTool]\n \n C --> H[start]\n C --> I[end]\n \n J[Context] --> K[SessionManager]\n K --> L[Stagehand Instances]\n```\n\nAll tools are exported as a unified array that matches the hosted MCP server at `mcp.browserbase.com`. Source: [src/tools/index.ts:13-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Tool Registration\n\nTools 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.\n\nSource: [src/index.ts:42-63](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Tool as Tool Handler\n participant Context as Context\n participant Stagehand as Stagehand\n \n MCP->>Tool: Execute Tool with params\n Tool->>Context: context.run(tool, params)\n Context->>Stagehand: Invoke Stagehand method\n Stagehand-->>Context: Return result\n Context-->>MCP: CallToolResult\n```\n\n## Tool Schema Structure\n\nAll tools implement a common interface defined in the `MCPTool` type. Each tool consists of a schema and a handler function.\n\nSource: [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `schema.name` | `string` | Unique identifier for the tool |\n| `schema.description` | `string` | Human-readable description of tool functionality |\n| `schema.inputSchema` | `ZodObject` | Validation schema for tool parameters |\n\n## Available Tools\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Session Management | `start`, `end` | Create and terminate browser sessions |\n| Navigation | `navigate` | Navigate to URLs |\n| Interaction | `act` | Perform actions on page elements |\n| Observation | `observe` | Identify actionable elements |\n| Extraction | `extract` | Extract data from pages |\n\n### Complete Tool List\n\nSource: [src/tools/index.ts:13-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n```typescript\nexport const TOOLS = [\n ...sessionTools, // start, end\n navigateTool, // navigate\n actTool, // act\n observeTool, // observe\n extractTool, // extract\n];\n```\n\n## Session Management Tools\n\nSession tools manage the lifecycle of Browserbase browser sessions. Each session maintains its own Stagehand instance for isolated browser automation.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n```mermaid\ngraph LR\n A[start] -->|Creates| B[SessionManager]\n B -->|Manages| C[Stagehand Instance]\n C --> D[Browser Tab]\n E[end] -->|Closes| B\n```\n\n### `start` Tool\n\nCreates a new browser session and initializes a Stagehand instance. A session must be started before any other tools can be used.\n\n**Renamed in v3.0.0** - Previously named `browserbase_session_create`.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `proxy` | `boolean` | No | Enable Browserbase proxies |\n| `verified` | `boolean` | No | Use Browserbase Verified Identity (Scale Plan only) |\n| `modelName` | `string` | No | Custom LLM model name |\n| `modelApiKey` | `string` | No | API key for custom model |\n| `keepAlive` | `boolean` | No | Keep session alive after operations |\n| `contextId` | `string` | No | Optional context identifier |\n\n### `end` Tool\n\nCloses the current browser session and releases all associated resources.\n\n**Renamed in v3.0.0** - Previously named `browserbase_session_close`.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| No parameters | - | - | Closes the active session |\n\n## Navigation Tool\n\n### `navigate` Tool\n\nNavigates the browser to a specified URL. The tool uses Stagehand's navigation capabilities for reliable page loading.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_navigate`.\n\nSource: [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | `string` | Yes | The target URL to navigate to |\n\n**Example usage:**\n\n```json\n{\n \"name\": \"navigate\",\n \"arguments\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n## Interaction Tool\n\n### `act` Tool\n\nPerforms 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.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_act`.\n\n**Breaking change in v3.0.0** - The `variables` parameter has been removed.\n\nSource: [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | `string` | Yes | Natural language description of the action to perform |\n\n**Supported action types:**\n\n- Click on elements (buttons, links, etc.)\n- Fill form fields (text inputs, textareas)\n- Select dropdown options\n- Check/uncheck checkboxes\n- Submit forms\n\n**Example usage:**\n\n```json\n{\n \"name\": \"act\",\n \"arguments\": {\n \"action\": \"Click the 'Sign In' button\"\n }\n}\n```\n\n## Observation Tool\n\n### `observe` Tool\n\nObserves the current page and identifies all actionable elements. Returns a list of elements that can be interacted with, categorized by type.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_observe`.\n\nSource: [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `instruction` | `string` | Yes | Description of what elements to look for |\n\n**Example usage:**\n\n```json\n{\n \"name\": \"observe\",\n \"arguments\": {\n \"instruction\": \"Find all clickable buttons on the page\"\n }\n}\n```\n\n**Return value structure:**\n\nThe tool returns an array of observed elements with their properties:\n\n```typescript\ninterface ObservedElement {\n type: \"button\" | \"link\" | \"input\" | \"select\" | ...;\n description: string;\n selector?: string;\n attributes?: Record;\n}\n```\n\n## Data Extraction Tool\n\n### `extract` Tool\n\nExtracts structured data from the current page based on natural language instructions. Uses AI to understand the page content and return relevant information.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_extract`.\n\n**Breaking change in v3.0.0** - The `instruction` parameter is now optional.\n\nSource: [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `instruction` | `string` | No | Natural language description of what data to extract |\n\nWhen `instruction` is omitted, the tool extracts all meaningful content from the page.\n\n**Example usage:**\n\n```json\n{\n \"name\": \"extract\",\n \"arguments\": {\n \"instruction\": \"Extract all product names and prices\"\n }\n}\n```\n\n## Tool Handler Implementation\n\nEach tool follows a consistent implementation pattern using the tool factory function.\n\nSource: [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n```typescript\nexport interface MCPTool {\n schema: {\n name: string;\n description: string;\n inputSchema: z.ZodObject;\n };\n handler: (params: any, context: Context) => Promise;\n}\n```\n\n### Handler Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `params` | `object` | Validated input parameters matching the tool's inputSchema |\n| `context` | `Context` | Server context providing access to SessionManager and Stagehand instances |\n\n## Error Handling\n\nAll tool handlers are wrapped in try-catch blocks at the MCP server level. Errors are logged with timestamps and re-thrown with descriptive messages.\n\nSource: [src/index.ts:47-59](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n );\n throw new Error(\n `Failed to run tool '${tool.schema.name}': ${errorMessage}`,\n );\n}\n```\n\n## Session Management Integration\n\nTools interact with the SessionManager through the Context class, which provides synchronized access to session state.\n\nSource: [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n```mermaid\ngraph TD\n A[Tool Handler] --> B[Context.run]\n B --> C[currentSessionId getter]\n C --> D[SessionManager.getActiveSessionId]\n D --> E[Returns active session]\n B --> F[SessionManager.getSession]\n F --> G[Stagehand instance]\n```\n\nThe `currentSessionId` property is a getter that delegates to SessionManager to ensure synchronization between Context and SessionManager session tracking.\n\nSource: [src/context.ts:18-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Configuration Options\n\nThe following configuration options affect tool behavior:\n\n| Option | Tool Affected | Description |\n|--------|---------------|-------------|\n| `proxies` | `start` | Enable Browserbase proxies for the session |\n| `verified` | `start` | Enable Verified Identity (Scale Plan) |\n| `modelName` | `start` | Specify custom LLM model |\n| `modelApiKey` | `start` | API key for custom model |\n| `keepAlive` | `start` | Prevent session timeout |\n| `browserWidth` | `start` | Browser viewport width (default: 1024) |\n| `browserHeight` | `start` | Browser viewport height (default: 768) |\n\n## Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Handler as Tool Handler\n participant Context as Context\n participant Session as SessionManager\n participant Stagehand as Stagehand\n \n Client->>Server: tool/CallRequest\n Server->>Handler: Execute with params\n Handler->>Context: context.run(tool, params)\n Context->>Session: getSession(currentSessionId)\n Session->>Stagehand: Get/initialize instance\n Stagehand-->>Context: Stagehand ready\n Context->>Stagehand: Execute operation\n Stagehand-->>Handler: Result\n Handler-->>Server: CallToolResult\n Server-->>Client: Response\n```\n\n## Changelog\n\n### v3.0.0 Breaking Changes\n\nSource: [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n\n| Change | Previous | Current |\n|--------|----------|---------|\n| `browserbase_session_create` | `start` | Tool renamed |\n| `browserbase_session_close` | `end` | Tool renamed |\n| `browserbase_stagehand_navigate` | `navigate` | Tool renamed |\n| `browserbase_stagehand_act` | `act` | Tool renamed |\n| `browserbase_stagehand_observe` | `observe` | Tool renamed |\n| `browserbase_stagehand_extract` | `extract` | Tool renamed |\n| `act` parameters | `variables` accepted | Removed |\n| `extract` parameters | `instruction` required | Now optional |\n| Default model | `gemini-2.0-flash` | `google/gemini-2.5-flash-lite` |\n\n### Removed Tools\n\nThe following tools were removed in v3.0.0:\n\n- `browserbase_screenshot` - Screenshot functionality consolidated elsewhere\n- `browserbase_stagehand_get_url` - URL accessible via session state\n- `browserbase_stagehand_agent` - Agent capabilities restructured\n\n## See Also\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n\n---\n\n\n\n## Session Management\n\n### Related Pages\n\nRelated topics: [MCP Tools Reference](#mcp-tools), [Configuration Options](#configuration-options)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# Session Management\n\n## Overview\n\nSession 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.\n\nThe session management system serves as the backbone for all browser-based operations, providing:\n\n- **Isolation**: Multiple concurrent browser sessions with independent state\n- **Lifecycle Management**: Automated creation, validation, cleanup, and recovery\n- **Concurrency Control**: Mutex patterns to prevent race conditions during session creation\n- **Resource Optimization**: Session reuse and graceful cleanup to minimize resource consumption\n\nSource: [src/sessionManager.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Architecture\n\n### High-Level Components\n\nThe session management architecture consists of three primary layers working in coordination:\n\n```mermaid\ngraph TD\n subgraph \"MCP Layer\"\n MCP[\"MCP Server\"]\n Tools[\"Session Tools
(start, end)\"]\n end\n \n subgraph \"Context Layer\"\n Context[\"Context
(src/context.ts)\"]\n SessionId[\"currentSessionId
(getter)\"]\n end\n \n subgraph \"Session Management Layer\"\n SM[\"SessionManager
(src/sessionManager.ts)\"]\n Browsers[\"Map<string, BrowserSession>\"]\n Active[\"activeSessionId\"]\n Default[\"defaultBrowserSession\"]\n Mutex[\"defaultSessionCreationPromise\"]\n Cleanup[\"cleaningUpSessions\"]\n end\n \n subgraph \"Stagehand Layer\"\n Stagehand[\"Stagehand Instance\"]\n Browser[\"Browser Context\"]\n Page[\"Page\"]\n end\n \n MCP --> Tools\n Tools --> Context\n Context --> SM\n SM --> Stagehand\n Stagehand --> Browser\n Browser --> Page\n \n Context -.-> SessionId\n SM -.-> Browsers\n SM -.-> Active\n SM -.-> Default\n SM -.-> Mutex\n SM -.-> Cleanup\n```\n\n### Class Hierarchy\n\n| Layer | Class/Module | Responsibility |\n|-------|--------------|----------------|\n| MCP | `TOOLS` array | Exposes session tools via MCP protocol |\n| Context | `Context` | Central controller, holds SessionManager reference |\n| Session | `SessionManager` | Core session lifecycle management |\n| Stagehand | `createStagehandInstance()` | Browser automation driver |\n\nSource: [src/context.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Data Model\n\n### BrowserSession Interface\n\n```typescript\ninterface BrowserSession {\n page: Page; // Playwright Page instance\n sessionId: string; // Browserbase session identifier\n stagehand: Stagehand; // Stagehand automation instance\n}\n```\n\nSource: [src/sessionManager.ts:120-125](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### SessionManager State\n\nThe `SessionManager` class maintains the following internal state:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `browsers` | `Map` | Stores all active browser sessions |\n| `defaultBrowserSession` | `BrowserSession \\| null` | Reference to the default session |\n| `defaultSessionId` | `string` | Unique identifier for the default session |\n| `activeSessionId` | `string` | Currently active session ID |\n| `defaultSessionCreationPromise` | `Promise \\| null` | Mutex for concurrent creation attempts |\n| `cleaningUpSessions` | `Set` | Tracks sessions currently being cleaned |\n\nSource: [src/sessionManager.ts:56-73](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Lifecycle\n\n### Lifecycle States\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: createNewBrowserSession()\n Created --> Active: setActiveSessionId()\n Active --> Validating: getSession()\n Validating --> Active: Session valid\n Validating --> Recreating: Session stale\n Recreating --> Active: Recreated successfully\n Recreating --> Error: Creation failed\n Active --> CleaningUp: cleanupSession()\n CleaningUp --> [*]: Cleanup complete\n Active --> [*]: closeAllSessions()\n```\n\n### Session Creation Flow\n\n```mermaid\ngraph TD\n Start[\"Request Session\"] --> CheckDefault{\"Is Default
Session?\"}\n \n CheckDefault -->|Yes| CheckInProgress{\"Creation
In Progress?\"}\n CheckDefault -->|No| GetFromMap[\"Get from
browsers Map\"]\n \n CheckInProgress -->|Yes| Wait[\"Wait for
existing promise\"]\n CheckInProgress -->|No| CheckExists{\"Session
Exists?\"}\n \n Wait --> ReturnExisting[\"Return Promise\"]\n CheckExists -->|No| Create[\"createNewBrowserSession()\"]\n CheckExists -->|Yes| Validate[\"Validate
Session\"]\n \n Create --> Stagehand[\"Create Stagehand
Instance\"]\n Stagehand --> Extract[\"Extract Page &
Session ID\"]\n Extract --> Store[\"Store in Map\"]\n Store --> SetActive[\"Set Active\"]\n \n Validate -->|Valid| Return[\"Return Session\"]\n Validate -->|Stale| Remove[\"Close & Remove\"]\n Remove --> Create\n```\n\nSource: [src/sessionManager.ts:130-200](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Session Validation\n\nSessions are validated before use by checking page availability:\n\n```typescript\ntry {\n const pages = sessionObj.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n needsReCreation = true;\n}\n```\n\nSource: [src/sessionManager.ts:83-91](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Core Methods\n\n### Creating Sessions\n\n#### `createNewBrowserSession()`\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `newSessionId` | `string` | Yes | Internal tracking ID |\n| `config` | `Config` | Yes | Browserbase configuration |\n| `resumeSessionId` | `string` | No | Browserbase session to resume |\n\n**Process:**\n\n1. Validate API key and project ID exist in config\n2. Create Stagehand instance with optional resume capability\n3. Extract page and Browserbase session ID\n4. Store session in browsers Map\n5. Update active session ID\n\n```typescript\nconst stagehand = await createStagehandInstance(\n config,\n {\n ...(resumeSessionId && { browserbaseSessionID: resumeSessionId }),\n },\n newSessionId,\n);\n```\n\nSource: [src/sessionManager.ts:140-195](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Retrieving Sessions\n\n#### `getSession()`\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `sessionId` | `string` | Required | Session identifier to retrieve |\n| `config` | `Config` | Required | Configuration object |\n| `createIfMissing` | `boolean` | `true` | Auto-create default session if missing |\n\n**Returns:** `BrowserSession | null`\n\n```typescript\nasync getSession(\n sessionId: string,\n config: Config,\n createIfMissing: boolean = true,\n): Promise\n```\n\nSource: [src/sessionManager.ts:240-280](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `ensureDefaultSessionInternal()`\n\nEnsures 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.\n\n```typescript\nif (this.defaultSessionCreationPromise) {\n process.stderr.write(\n `[SessionManager] Default session creation already in progress, waiting...\\n`,\n );\n return await this.defaultSessionCreationPromise;\n}\n```\n\nSource: [src/sessionManager.ts:200-220](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Cleanup Operations\n\n#### `closeBrowserGracefully()`\n\nSafely closes a single session with concurrent cleanup protection:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `session` | `BrowserSession \\| undefined \\| null` | Session to close |\n| `sessionIdToLog` | `string` | ID for logging purposes |\n\n**Features:**\n\n- Tracks sessions being cleaned in `cleaningUpSessions` Set\n- Prevents double-cleanup of the same session\n- Always removes from cleanup tracking in `finally` block\n\n```typescript\nif (this.cleaningUpSessions.has(sessionIdToLog)) {\n process.stderr.write(\n `[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\\n`,\n );\n return;\n}\nthis.cleaningUpSessions.add(sessionIdToLog);\n```\n\nSource: [src/sessionManager.ts:145-180](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `cleanupSession()`\n\nRemoves a session and resets state:\n\n```typescript\nasync cleanupSession(sessionId: string): Promise {\n const session = this.browsers.get(sessionId);\n if (session) {\n await this.closeBrowserGracefully(session, sessionId);\n }\n this.browsers.delete(sessionId);\n \n if (sessionId === this.defaultSessionId) {\n this.defaultBrowserSession = null;\n }\n if (this.activeSessionId === sessionId) {\n this.setActiveSessionId(this.defaultSessionId);\n }\n}\n```\n\nSource: [src/sessionManager.ts:110-145](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `closeAllSessions()`\n\nCloses all managed sessions in parallel:\n\n```typescript\nasync closeAllSessions(): Promise {\n const closePromises: Promise[] = [];\n for (const [id, session] of this.browsers.entries()) {\n closePromises.push(this.closeBrowserGracefully(session, id));\n }\n await Promise.all(closePromises);\n this.browsers.clear();\n this.defaultBrowserSession = null;\n this.setActiveSessionId(this.defaultSessionId);\n}\n```\n\nSource: [src/sessionManager.ts:155-175](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Tools (MCP Interface)\n\nSession management is exposed to MCP clients through tools defined in `src/tools/session.ts` and registered in the TOOLS array:\n\n| Tool | Description |\n|------|-------------|\n| `start` | Creates a new browser session |\n| `end` | Closes an existing session |\n\nSource: [src/tools/index.ts:1-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n### Tool Exports\n\n```typescript\nexport const TOOLS = [\n ...sessionTools,\n navigateTool,\n actTool,\n observeTool,\n extractTool,\n];\n\nexport const sessionManagementTools = sessionTools;\n```\n\nSource: [src/tools/index.ts:16-18](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Integration with Context\n\nThe `Context` class provides the bridge between MCP infrastructure and session management:\n\n```typescript\nexport class Context {\n public readonly config: Config;\n private server: Server;\n private sessionManager: SessionManager;\n\n public get currentSessionId(): string {\n return this.sessionManager.getActiveSessionId();\n }\n\n public async getStagehand(\n sessionId: string = this.currentSessionId,\n ): Promise {\n const session = await this.sessionManager.getSession(\n sessionId,\n this.config,\n );\n if (!session) {\n throw new Error(\"Session not found\");\n }\n return session.stagehand;\n }\n}\n```\n\nSource: [src/context.ts:15-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Concurrency Handling\n\n### Mutex Pattern for Default Session\n\nThe default session creation uses a mutex pattern to prevent race conditions:\n\n```mermaid\ngraph LR\n A[\"Request 1\"] --> M{\"In Progress?\"}\n B[\"Request 2\"] --> M\n C[\"Request 3\"] --> M\n \n M -->|No| Create[\"Create Session\"]\n M -->|Yes| Wait[\"Wait on Promise\"]\n \n Create --> Store[\"Store Promise\"]\n Store --> Return[\"Return to Request 1\"]\n Wait --> Return\n```\n\n**Implementation:**\n\n```typescript\nprivate defaultSessionCreationPromise: Promise | null = null;\n\nasync ensureDefaultSessionInternal(config: Config): Promise {\n if (this.defaultSessionCreationPromise) {\n return await this.defaultSessionCreationPromise;\n }\n \n this.defaultSessionCreationPromise = (async () => {\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n } finally {\n this.defaultSessionCreationPromise = null;\n }\n })();\n \n return await this.defaultSessionCreationPromise;\n}\n```\n\nSource: [src/sessionManager.ts:200-240](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Cleanup Tracking\n\nThe `cleaningUpSessions` Set prevents concurrent cleanup operations:\n\n```typescript\nprivate cleaningUpSessions: Set = new Set();\n\nasync closeBrowserGracefully(...): Promise {\n if (this.cleaningUpSessions.has(sessionIdToLog)) {\n return; // Skip if already being cleaned\n }\n \n this.cleaningUpSessions.add(sessionIdToLog);\n try {\n // Perform cleanup\n } finally {\n this.cleaningUpSessions.delete(sessionIdToLog);\n }\n}\n```\n\nSource: [src/sessionManager.ts:145-175](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Error Handling\n\n### Session Creation Errors\n\nErrors during session creation trigger automatic retry:\n\n```typescript\ntry {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n} catch (creationError) {\n process.stderr.write(`[SessionManager] Initial attempt failed...\\n`);\n \n // Retry once\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n } catch (retryError) {\n throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);\n }\n} finally {\n this.defaultSessionCreationPromise = null;\n}\n```\n\nSource: [src/sessionManager.ts:225-260](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Graceful Degradation\n\nThe system logs warnings and continues operation on non-fatal errors:\n\n```typescript\n} catch (closeError) {\n process.stderr.write(\n `[SessionManager] WARN - Error closing Stagehand for session ${sessionIdToLog}: ${\n closeError instanceof Error\n ? closeError.message\n : String(closeError)\n }\\n`,\n );\n}\n```\n\nSource: [src/sessionManager.ts:160-170](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Identification\n\n### ID Generation\n\nDefault session IDs follow a structured format:\n\n```typescript\nconst uniqueId = randomUUID();\nthis.defaultSessionId = `browserbase_session_${contextId || \"default\"}_${Date.now()}_${uniqueId}`;\n```\n\nFormat: `browserbase_session_{contextId}_{timestamp}_{uuid}`\n\nExample: `browserbase_session_default_1699123456789_a1b2c3d4-e5f6-7890-abcd-ef1234567890`\n\nSource: [src/sessionManager.ts:66-70](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Active Session Management\n\nThe active session can be changed but only to existing sessions (or the default):\n\n```typescript\nsetActiveSessionId(id: string): void {\n if (this.browsers.has(id)) {\n this.activeSessionId = id;\n } else if (id === this.defaultSessionId) {\n this.activeSessionId = id; // Allow even if not created yet\n } else {\n process.stderr.write(`[SessionManager] WARN - Set active session failed for non-existent ID: ${id}\\n`);\n }\n}\n```\n\nSource: [src/sessionManager.ts:75-90](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Summary\n\nThe Session Management system provides a robust foundation for browser automation within the MCP server:\n\n- **Isolation**: Each session maintains independent browser state via Stagehand\n- **Reliability**: Automatic validation, recreation, and retry mechanisms\n- **Concurrency Safety**: Mutex patterns and cleanup tracking prevent race conditions\n- **Resource Management**: Graceful cleanup ensures proper resource disposal\n- **Integration**: Seamless connection through the Context layer to MCP tools\n\n---\n\n\n\n## Configuration Options\n\n### Related Pages\n\nRelated topics: [Model Configuration](#model-configuration), [Quick Start Guide](#quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/config.test.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n \n\n# Configuration Options\n\nThe 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.\n\n## Overview\n\nThe 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.\n\nThe configuration system is built on three pillars:\n\n- **Zod Schema Validation**: All configuration options are validated using Zod schemas defined in `src/index.ts`\n- **Environment Variable Support**: Sensitive values and deployment-specific settings can be injected via environment variables\n- **Command-Line Arguments**: Runtime behavior can be modified through CLI flags defined in `src/program.ts`\n\nSource: [src/config.ts:1-15]()\n\n## Configuration Schema\n\nThe root configuration interface `Config` defines the complete structure of valid configuration options. All options are type-safe and validated at server startup.\n\n### Core Configuration Interface\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies: boolean;\n server: {\n port?: number;\n host?: string;\n };\n viewPort: {\n browserWidth: number;\n browserHeight: number;\n };\n modelName: string;\n modelApiKey?: string;\n verified?: boolean;\n keepAlive?: boolean;\n}\n```\n\nSource: [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Zod Schema Definition\n\nThe configuration schema provides runtime validation and documentation for MCP clients:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether or not to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Use Browserbase Verified Identity\"),\n advancedStealth: z.boolean().optional().describe(\"Deprecated alias for verified\"),\n keepAlive: z.boolean().optional().describe(\"Whether or not to keep the Browserbase session alive\"),\n // Additional fields...\n});\n```\n\nSource: [src/index.ts:18-45]()\n\n## Command-Line Options\n\nThe server accepts the following command-line flags when run directly via Node.js or the CLI entry point:\n\n| Flag | Type | Description | Default |\n|------|------|-------------|---------|\n| `--browserbaseApiKey` | string | The Browserbase API Key to authenticate with the Browserbase service | _(none)_ |\n| `--browserbaseProjectId` | string | The Browserbase Project ID for organizing sessions and billing | _(none)_ |\n| `--proxies` | boolean | Enable Browserbase proxy rotation for requests | `false` |\n| `--verified` | boolean | Use Browserbase Verified Identity (requires Scale Plan) | `false` |\n| `--advancedStealth` | boolean | Deprecated alias for `--verified` | `false` |\n| `--contextId` | string | Browserbase context identifier for session continuity | _(none)_ |\n| `--persist` | boolean | Persist session data beyond server restart | `false` |\n| `--port` | number | HTTP server port for streamable transport | _(none)_ |\n| `--host` | string | HTTP server host binding address | _(none)_ |\n| `--browserWidth` | number | Viewport width in pixels for browser sessions | `1024` |\n| `--browserHeight` | number | Viewport height in pixels for browser sessions | `768` |\n| `--modelName` | string | AI model identifier for Stagehand operations | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey` | string | API key for the configured AI model | _(none)_ |\n| `--keepAlive` | boolean | Maintain browser session after request completion | `false` |\n| `--experimental` | boolean | Enable experimental features | `false` |\n\nSource: [src/program.ts:28-46]()\n\nSource: [src/config.ts:7-22]()\n\n## Environment Variables\n\nThe configuration system automatically loads values from environment variables when CLI options are not provided:\n\n| Environment Variable | Config Property | Description |\n|---------------------|-----------------|-------------|\n| `BROWSERBASE_API_KEY` | `browserbaseApiKey` | Authentication token for Browserbase API |\n| `BROWSERBASE_PROJECT_ID` | `browserbaseProjectId` | Project identifier for Browserbase resources |\n| `GEMINI_API_KEY` | `modelApiKey` | API key for Gemini models (fallback) |\n| `GOOGLE_API_KEY` | `modelApiKey` | Alternative API key for Google models |\n\nEnvironment variables are loaded using the `dotenv` package at application startup:\n\n```typescript\nimport * as dotenv from \"dotenv\";\ndotenv.config();\n```\n\nSource: [src/index.ts:1-2]()\n\n### Environment Variable Resolution Priority\n\nWhen resolving the model API key, the system checks environment variables in the following order:\n\n1. `process.env.GEMINI_API_KEY`\n2. `process.env.GOOGLE_API_KEY`\n\n```typescript\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\nSource: [src/config.ts:50-53]()\n\n## Default Configuration Values\n\nThe server ships with sensible defaults for all optional parameters:\n\n| Property | Default Value | Description |\n|----------|---------------|-------------|\n| `proxies` | `false` | Proxy rotation disabled by default |\n| `server.port` | `undefined` | Auto-assigned by the operating system |\n| `server.host` | `undefined` | Bind to all available interfaces |\n| `viewPort.browserWidth` | `1024` | Standard desktop viewport width |\n| `viewPort.browserHeight` | `768` | Standard desktop viewport height |\n| `modelName` | `google/gemini-2.5-flash-lite` | Default model matches hosted MCP service |\n\nSource: [src/config.ts:25-34]()\n\n## Configuration Resolution Flow\n\nThe configuration passes through several transformation stages before being used by the server:\n\n```mermaid\ngraph TD\n A[Default Config] --> B[CLI Options]\n B --> C[configFromCLIOptions]\n C --> D[mergeConfig]\n D --> E[normalizeVerifiedConfig]\n E --> F[normalizeVerifiedConfig with Env Vars]\n F --> G[Internal Config]\n G --> H[Server Initialization]\n \n I[process.env.GEMINI_API_KEY] -.-> F\n J[process.env.GOOGLE_API_KEY] -.-> F\n```\n\n### Configuration Processing Pipeline\n\nThe `resolveConfig` function orchestrates the complete configuration workflow:\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n // Order: Defaults < File Config < CLI Overrides\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n\n // --- Add Browserbase Env Vars ---\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n // ...\n}\n```\n\nSource: [src/config.ts:37-56]()\n\n## Verified Identity Configuration\n\nThe `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.\n\n### Legacy Alias Handling\n\n```typescript\nit(\"maps the legacy CLI advancedStealth alias to verified\", async () => {\n const config = await configFromCLIOptions({ advancedStealth: true });\n expect(config.verified).toBe(true);\n});\n\nit(\"prefers verified when both verified and advancedStealth are set\", () => {\n const config = normalizeVerifiedConfig({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n verified: false,\n advancedStealth: true,\n });\n expect(config.verified).toBe(false);\n});\n```\n\nSource: [src/config.test.ts:7-22]()\n\n## CLI Options Type Definition\n\nThe `CLIOptions` type represents all valid command-line input options:\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\nSource: [src/config.ts:7-22]()\n\n## Required Configuration\n\nCertain configuration values must be provided for the server to function:\n\n### Mandatory Fields\n\n| Field | Requirement | Error if Missing |\n|-------|-------------|------------------|\n| `browserbaseApiKey` | Required | `\"browserbaseApiKey is required\"` |\n| `browserbaseProjectId` | Required | `\"browserbaseProjectId is required\"` |\n\nThe validation is performed in `src/index.ts` before the MCP server is initialized:\n\n```typescript\nif (!config.browserbaseApiKey) {\n throw new Error(\"browserbaseApiKey is required\");\n}\nif (!config.browserbaseProjectId) {\n throw new Error(\"browserbaseProjectId is required\");\n}\n```\n\nSource: [src/index.ts:93-99]()\n\n## Tool Capability Configuration\n\nConfiguration options can be tagged with capability levels for feature gating:\n\n```typescript\nexport type ToolCapability = \"core\" | string;\n```\n\nThis allows future extension of the configuration system to support optional tool sets based on subscription tier or feature flags.\n\nSource: [src/config.ts:3-5]()\n\n## Configuration in MCP Client Setup\n\nWhen integrating with MCP clients, configuration is passed through the `env` property of the server definition:\n\n### NPM Package Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Direct Node.js Installation\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Docker Container Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Transport Configuration\n\nThe server supports multiple transport mechanisms, each with its own configuration requirements:\n\n| Transport | Configuration Method | Notes |\n|-----------|---------------------|-------|\n| STDIO | Environment variables or CLI flags | Default for local installations |\n| Streamable HTTP | Port/host CLI flags | Configured via `--port` and `--host` |\n| SHTTP (Hosted) | URL configuration only | Uses hosted service at `mcp.browserbase.com` |\n\nSource: [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n---\n\n\n\n## Model Configuration\n\n### Related Pages\n\nRelated topics: [Configuration Options](#configuration-options), [System Architecture Overview](#architecture-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# Model Configuration\n\nThe 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.\n\n## Overview\n\nThe MCP server leverages [Stagehand](https://www.stagehand.dev) 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.\n\n| Property | Type | Default Value | Description |\n|----------|------|---------------|-------------|\n| `modelName` | string | `google/gemini-2.5-flash-lite` | The model identifier for Stagehand |\n| `modelApiKey` | string | Environment variable | API key for the custom model provider |\n\nSource: [src/config.ts:26-27](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L26-L27)\n\n## Configuration Architecture\n\n### Configuration Resolution Order\n\nThe system employs a layered configuration strategy where settings are merged in a specific priority order:\n\n```mermaid\ngraph TD\n A[Default Configuration] --> B[File Configuration]\n B --> C[CLI Options]\n C --> D[Environment Variables]\n D --> E[Final Merged Config]\n \n F[modelApiKey Override] --> |\"if not set\"| D\n G[GEMINI_API_KEY or GOOGLE_API_KEY] --> F\n```\n\nThe resolution order from lowest to highest priority is:\n\n1. **Default Configuration** - Hardcoded defaults in `src/config.ts`\n2. **CLI Options** - Command-line arguments provided at runtime\n3. **Environment Variables** - Used as fallback for `modelApiKey`\n\nSource: [src/config.ts:29-43](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L29-L43)\n\n### Configuration Schema\n\nThe server uses Zod for runtime validation of the configuration object:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n modelName: z.string().optional(),\n modelApiKey: z.string().optional(),\n // ... other options\n});\n```\n\nSource: [src/index.ts:28-49](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts#L28-L49)\n\n## CLI Options\n\n### Available Flags\n\n| Flag | Type | Description | Required |\n|------|------|-------------|----------|\n| `--modelName ` | string | Model identifier (e.g., `anthropic/claude-sonnet-4.5`) | No |\n| `--modelApiKey ` | string | API key for the custom model provider | Conditional |\n\nThe `--modelName` and `--modelApiKey` flags are exposed through Commander.js:\n\n```typescript\n.option(\"--modelName \", \"The model to use for Stagehand\")\n.option(\"--modelApiKey \", \"API key for the model provider\")\n```\n\nSource: [src/program.ts:45-46](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts#L45-L46)\n\n### CLI Options Type Definition\n\n```typescript\nexport type CLIOptions = {\n modelName?: string;\n modelApiKey?: string;\n // ... other options\n};\n```\n\nSource: [src/config.ts:13-24](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L13-L24)\n\n## Environment Variable Handling\n\nThe `modelApiKey` can be automatically populated from environment variables when not explicitly provided:\n\n```typescript\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\nThis allows users to set credentials once in their environment rather than repeatedly on the command line.\n\nSource: [src/config.ts:38-41](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L38-L41)\n\n## Supported Models\n\nThe server uses Stagehand for browser automation, and the model must be supported by Stagehand. Refer to the [Stagehand documentation](https://docs.stagehand.dev/examples/custom_llms#supported-llms) for the complete list of supported models.\n\n### Default Model\n\nThe default model is `google/gemini-2.5-flash-lite`, chosen for its performance in web interaction tasks:\n\n```typescript\nconst defaultConfig: Config = {\n // ...\n modelName: \"google/gemini-2.5-flash-lite\", // Default Model — matches hosted MCP\n};\n```\n\nSource: [src/config.ts:26](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L26)\n\n### Popular Alternative Models\n\n| Provider | Model Identifier | Use Case |\n|----------|------------------|----------|\n| Anthropic | `anthropic/claude-sonnet-4.5` | High-quality reasoning |\n| Anthropic | `anthropic/claude-opus-4` | Maximum capability |\n| OpenAI | `openai/gpt-4o` | Vision and speed |\n| Google | `google/gemini-2.0-flash` | Balanced performance |\n\n## Configuration Examples\n\n### Using Default Model\n\nWhen using the default Gemini model, provide the API key via environment variable:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Using Custom Model\n\nTo use a custom model like Claude:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### NPM Installation with Custom Model\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"sk-ant-...\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-...\",\n \"BROWSERBASE_PROJECT_ID\": \"...\"\n }\n }\n }\n}\n```\n\n### Docker Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"MODEL_NAME\",\n \"-e\",\n \"MODEL_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"MODEL_NAME\": \"anthropic/claude-sonnet-4.5\",\n \"MODEL_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n## Requirements for Custom Models\n\nWhen 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.\n\n| Requirement | Reason |\n|-------------|--------|\n| Valid `--modelName` | Must be supported by Stagehand |\n| Valid `--modelApiKey` | Required for authentication with external providers |\n| Sufficient quota | Check your LLM provider's rate limits |\n\n## Configuration Flow Diagram\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as Command Line\n participant Config as Config Module\n participant Stagehand\n \n User->>CLI: Start server with options\n CLI->>Config: Parse CLI options\n Config->>Config: Load default config\n Config->>Config: Merge CLI options\n Config->>Config: Check env vars for modelApiKey\n Config->>Config: Return resolved config\n CLI->>Stagehand: Initialize with config\n Stagehand->>User: Server ready with model\n```\n\n## Related Dependencies\n\nThe model configuration system depends on the following key packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@browserbasehq/stagehand` | ^3.3.0 | Browser automation with AI |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP server framework |\n| `commander` | ^14.0.0 | CLI argument parsing |\n| `zod` | ^3.25.67 | Schema validation |\n\nSource: [package.json:40-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json#L40-L45)\n\n## Best Practices\n\n1. **Environment Variables for Secrets**: Store API keys in environment variables rather than command-line arguments to avoid exposing sensitive data in process listings.\n\n2. **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.\n\n3. **Validation**: The Zod schema validates configuration at runtime, ensuring required fields are present before the server starts.\n\n4. **Compatibility**: Always verify your chosen model is supported by Stagehand before configuration.\n\n---\n\n\n\n## Deployment Methods\n\n### Related Pages\n\nRelated topics: [Quick Start Guide](#quickstart), [Transport Layer](#transport-layer)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n \n\n# Deployment Methods\n\nThe 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.\n\n## Overview\n\nThe MCP server can be deployed in three primary ways:\n\n1. **Direct Installation** - Clone the repository and run locally with Node.js\n2. **Docker Container** - Run the server in an isolated container\n3. **NPM Package** - Use the pre-built `@browserbasehq/mcp` package via npx\n\nAdditionally, the server supports two transport mechanisms for communication:\n\n- **STDIO** - Standard input/output communication for local CLI integrations\n- **SHTTP** - HTTP-based transport for networked or hosted deployments\n\nSource: [README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n A[Client MCP Config] --> B{Transport Type}\n B -->|STDIO| C[Direct Installation / NPM]\n B -->|SHTTP| D[Hosted Server / Self-Hosted HTTP]\n \n C --> E[Node.js Runtime]\n D --> F[mcp.browserbase.com]\n D --> G[Self-Hosted Docker/Node]\n \n E --> H[Browserbase Cloud]\n F --> H\n G --> H\n \n H --> I[Stagehand]\n I --> J[Browser Automation]\n```\n\n## Method 1: Direct Installation\n\nDirect installation provides full control over the server and is suitable for development environments or custom deployments.\n\n### Prerequisites\n\n- Node.js 18+ (LTS recommended)\n- npm or pnpm package manager\n- Valid Browserbase API credentials\n\n### Installation Steps\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\nSource: [README.md:1-10](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Project Structure\n\nThe built artifacts are generated in the `dist/` directory with the following structure:\n\n| File | Purpose |\n|------|---------|\n| `cli.js` | Main CLI entry point |\n| `index.js` | Module entry point for programmatic use |\n| `config.d.ts` | TypeScript type definitions |\n\nSource: [package.json:11-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n### Available Build Scripts\n\n| Script | Command | Description |\n|--------|---------|-------------|\n| `build` | `tsc && shx chmod +x dist/*.js` | Compiles TypeScript and sets executable permissions |\n| `watch` | `tsc --watch` | Watch mode for development |\n| `test` | `vitest run` | Run test suite |\n| `inspector` | `npx @modelcontextprotocol/inspector` | MCP protocol inspector |\n\nSource: [package.json:22-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Method 2: Docker Deployment\n\nDocker deployment provides an isolated, reproducible environment that includes all dependencies.\n\n### Building the Docker Image\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n### Running the Container\n\nThe Docker image exposes the server with environment variable support for configuration:\n\n```bash\ndocker run --rm -i \\\n -e BROWSERBASE_API_KEY \\\n -e BROWSERBASE_PROJECT_ID \\\n -e GEMINI_API_KEY \\\n mcp-browserbase\n```\n\nSource: [README.md:10-25](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Docker Configuration Benefits\n\n- **Isolation**: Runs independently of host system dependencies\n- **Consistency**: Identical behavior across different environments\n- **Security**: Sandboxed execution environment\n- **Portability**: Easy to deploy to any container runtime\n\n## Method 3: NPM Package (npx)\n\nThe pre-built package provides the fastest path to deployment without manual cloning or building.\n\n### Quick Start\n\n```bash\nnpx @browserbasehq/mcp\n```\n\n### Configuration in MCP Client\n\nAdd the following to your MCP configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:60-75](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@browserbasehq/mcp` |\n| Version | 3.0.0 |\n| License | Apache-2.0 |\n| Entry Point | `./cli.js` |\n| Module Entry | `./src/index.ts` |\n\nSource: [package.json:1-12](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Transport Methods\n\nThe MCP server supports two transport protocols for client communication.\n\n### STDIO Transport\n\nSTDIO is the default transport when no HTTP configuration is specified. It uses standard input/output streams for communication.\n\n```mermaid\ngraph LR\n A[MCP Client] -->|stdio| B[Browserbase MCP Server]\n B -->|stdout| A\n```\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:60-72](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### SHTTP Transport\n\nSHTTP (Secure HTTP) enables networked deployments and is the recommended transport for hosted deployments.\n\n#### Hosted Server (Recommended)\n\nUse the Browserbase hosted MCP server for the simplest setup:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### Self-Hosted HTTP\n\nFor self-hosted HTTP transport, specify port and host in the CLI:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n#### Remote Access via mcp-remote\n\nClients without native SHTTP support can use the `mcp-remote` tool:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n## Command-Line Options\n\nThe server accepts the following CLI flags for configuration:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--proxies` | Enable Browserbase proxies for the session | `false` |\n| `--verified` | Enable Browserbase Verified Identity (Scale Plan only) | `false` |\n| `--advancedStealth` | Deprecated alias for `--verified` | `false` |\n| `--keepAlive` | Enable Browserbase Keep Alive Session | `false` |\n| `--contextId ` | Specify a Browserbase Context ID to use | _(none)_ |\n| `--persist` | Whether to persist the Browserbase context | `true` |\n| `--port ` | Port for HTTP/SHTTP transport | _(stdio)_ |\n| `--host ` | Host to bind server to | `localhost` |\n| `--browserWidth ` | Browser viewport width | `1024` |\n| `--browserHeight ` | Browser viewport height | `768` |\n| `--modelName ` | Stagehand model name | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey ` | API key for custom model provider | _(none)_ |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [README.md:85-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### CLI Option Definitions\n\nThe CLI options are parsed using the `commander` package:\n\n```typescript\nprogram\n .option(\"--browserbaseApiKey \", \"The Browserbase API Key to use\")\n .option(\"--browserbaseProjectId \", \"The Browserbase Project ID to use\")\n .option(\"--proxies\", \"Use Browserbase proxies.\")\n .option(\"--verified\", \"Use Browserbase Verified Identity. Only available to Browserbase Scale Plan users.\")\n .option(\"--advancedStealth\", \"Deprecated alias for --verified.\")\n .option(\"--contextId \", \"Browserbase Context ID to use\");\n```\n\nSource: [src/program.ts:30-40](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n\n## Environment Variables\n\n### Required Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `BROWSERBASE_API_KEY` | Your Browserbase API key | Yes |\n| `BROWSERBASE_PROJECT_ID` | Your Browserbase Project ID | Yes |\n| `GEMINI_API_KEY` | Gemini API key for default model | Yes (unless using hosted) |\n\n### Optional Variables\n\n| Variable | Description | Auto-resolved From |\n|----------|-------------|-------------------|\n| `modelApiKey` | API key for custom models | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |\n\n### Configuration Resolution Order\n\nThe server resolves configuration using this precedence (highest to lowest):\n\n1. CLI arguments\n2. Environment variables\n3. Default values\n\n```mermaid\ngraph TD\n A[Config Resolution] --> B[Load Defaults]\n B --> C[Merge Env Variables]\n C --> D[Apply CLI Overrides]\n D --> E[Validate Configuration]\n E --> F[Start Server]\n```\n\nSource: [src/config.ts:40-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Configuration Type Definition\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n keepAlive?: boolean;\n context?: {\n contextId?: string;\n persist?: boolean;\n };\n server?: {\n port?: number;\n host?: string;\n };\n viewPort?: {\n browserWidth?: number;\n browserHeight?: number;\n };\n modelName?: string;\n modelApiKey?: string;\n experimental?: boolean;\n}\n```\n\nSource: [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Model Configuration\n\nThe server defaults to Google's Gemini 2.5 Flash Lite model but supports custom models.\n\n### Default Configuration\n\n| Setting | Value |\n|---------|-------|\n| Default Model | `google/gemini-2.5-flash-lite` |\n| API Key Source | `GEMINI_API_KEY` or `GOOGLE_API_KEY` env var |\n\n### Custom Model Setup\n\nTo use a custom model, provide both `--modelName` and `--modelApiKey`:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\n> **Note**: The model must be supported by Stagehand. See [Stagehand Custom LLM docs](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\nSource: [README.md:110-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Decision Matrix\n\n| Use Case | Recommended Method | Transport |\n|----------|-------------------|-----------|\n| Quick testing | NPM (npx) | STDIO |\n| Development | Direct Installation | STDIO |\n| Production (self-hosted) | Docker | SHTTP |\n| Production (managed) | Hosted Server | SHTTP |\n| CI/CD pipelines | Docker | STDIO |\n| Claude Code integration | NPM | STDIO |\n\n## Security Considerations\n\n### Host Binding\n\n| Host Value | Behavior | Security Level |\n|------------|----------|----------------|\n| `localhost` | Local connections only | High |\n| `0.0.0.0` | All network interfaces | Low - requires firewall |\n\n> **Warning**: Use `0.0.0.0` only when you need external access and have proper security measures in place.\n\n### API Key Management\n\n- Store credentials in environment variables, never in config files committed to version control\n- Use secret management solutions in production environments\n- Rotate API keys regularly\n\nSource: [config.d.ts:25-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Quick Reference\n\n### Minimal STDIO Setup\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### Full-Featured Docker Setup\n\n```bash\ndocker run --rm -i \\\n -e BROWSERBASE_API_KEY \\\n -e BROWSERBASE_PROJECT_ID \\\n -e GEMINI_API_KEY \\\n mcp-browserbase \\\n --proxies \\\n --verified \\\n --browserWidth 1920 \\\n --browserHeight 1080\n```\n\n## Related Documentation\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n\n---\n\n\n\n## Testing\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [vitest.config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/vitest.config.ts)\n- [src/config.test.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [eslint.config.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/eslint.config.js)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n \n\n# Testing\n\n## Overview\n\nThe 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.\n\n## Testing Stack\n\n### Core Testing Framework\n\nThe 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.\n\n### Supporting Tools\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| `vitest` | ^4.1.2 | Primary testing framework |\n| `mcpvals` | ^0.4.0 | MCP protocol validation |\n| `tsx` | ^4.20.3 | TypeScript execution for evals |\n| `typescript` | ^5.6.2 | TypeScript compiler and type checking |\n| `eslint` | ^9.29.0 | Code linting |\n| `prettier` | ^3.6.1 | Code formatting |\n\nSource: [package.json:39-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Test Configuration\n\n### Vitest Configuration\n\nThe Vitest configuration defines the scope and boundaries of test discovery within the project:\n\n```typescript\nimport { defineConfig } from \"vitest/config\";\n\nexport default defineConfig({\n test: {\n include: [\"src/**/*.test.ts\", \"tests/**/*.test.ts\"],\n exclude: [\"node_modules\", \"dist\"],\n },\n});\n```\n\n**Configuration Parameters:**\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| `include` | `[\"src/**/*.test.ts\", \"tests/**/*.test.ts\"]` | Glob patterns for test file discovery |\n| `exclude` | `[\"node_modules\", \"dist\"]` | Directories excluded from test discovery |\n\nSource: [vitest.config.ts:1-9](https://github.com/browserbase/mcp-server-browserbase/blob/main/vitest.config.ts)\n\n### Test Execution\n\nTests are executed through npm/pnpm scripts defined in package.json:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `test` | `vitest run` | Run tests once without watch mode |\n| `prepare` | `husky && pnpm build` | Git hook setup and build (runs on `npm install`) |\n| `pre-commit` | `pnpm lint-staged` | Pre-commit hooks for linting and formatting |\n\nSource: [package.json:32-34](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Test Structure\n\n### Directory Organization\n\nTests follow a co-located pattern within the source directory:\n\n```mermaid\ngraph TD\n A[Project Root] --> B[src/]\n A --> C[tests/]\n B --> D[config.test.ts]\n B --> E[index.ts]\n B --> F[config.ts]\n \n D -. tests .-> F\n D -. validates .-> E\n```\n\n### Configuration Tests\n\nThe `config.test.ts` file contains comprehensive tests for configuration handling, verifying the behavior of configuration normalization and schema validation:\n\n#### Test Suite: Verified Config Compatibility\n\nThe test suite validates configuration alias handling and priority resolution between different configuration sources:\n\n**Test 1: Legacy CLI AdvancedStealth Alias Mapping**\n\n```typescript\nit(\"maps the legacy CLI advancedStealth alias to verified\", async () => {\n const config = await configFromCLIOptions({ advancedStealth: true });\n expect(config.verified).toBe(true);\n});\n```\n\nThis test verifies that the deprecated `advancedStealth` option correctly maps to the `verified` configuration property, maintaining backward compatibility.\n\nSource: [src/config.test.ts:9-13](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n**Test 2: Verified/AdvancedStealth Priority Resolution**\n\n```typescript\nit(\"prefers verified when both verified and advancedStealth are set\", () => {\n const config = normalizeVerifiedConfig({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n verified: false,\n advancedStealth: true,\n });\n expect(config.verified).toBe(false);\n});\n```\n\nThis 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.\n\nSource: [src/config.test.ts:15-23](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n**Test 3: Smithery Config Schema Compatibility**\n\n```typescript\nit(\"accepts advancedStealth in the Smithery config schema\", () => {\n const config = configSchema.parse({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n advancedStealth: true,\n });\n expect(config.advancedStealth).toBe(true);\n});\n```\n\nThis test validates compatibility with external configuration schemas like Smithery, ensuring the `advancedStealth` property is correctly parsed and preserved.\n\nSource: [src/config.test.ts:25-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n## Code Quality Integration\n\n### ESLint Configuration\n\nThe project uses ESLint with TypeScript support to maintain code quality across test files and source code:\n\n```javascript\nexport default defineConfig([\n {\n files: [\"**/*.{js,mjs,cjs,ts,mts,cts}\"],\n plugins: { js },\n extends: [\"js/recommended\"],\n ignores: [\"dist/**/*\"],\n },\n {\n files: [\"**/*.{js,mjs,cjs,ts,mts,cts}\"],\n languageOptions: { globals: { ...globals.browser, ...globals.node } },\n ignores: [\"dist/**/*\"],\n },\n ...tseslint.configs.recommended,\n {\n files: [\"src/types/**/*.ts\", \"src/mcp/**/*.ts\"],\n rules: {\n \"@typescript-eslint/no-explicit-any\": \"off\",\n \"@typescript-eslint/no-unused-vars\": \"off\",\n \"@typescript-eslint/ban-ts-comment\": \"off\",\n },\n },\n {\n ignores: [\"dist/**/*\", \"node_modules/**/*\"],\n },\n]);\n```\n\n**ESLint Rule Configuration:**\n\n| Rule | Applied To | Setting | Rationale |\n|------|------------|---------|-----------|\n| `no-explicit-any` | `src/types/**`, `src/mcp/**` | Off | Type definitions may require explicit any |\n| `no-unused-vars` | `src/types/**`, `src/mcp/**` | Off | Allow exported types with potential future use |\n| `ban-ts-comment` | `src/types/**`, `src/mcp/**` | Off | Allow TypeScript directive comments |\n\nSource: [eslint.config.js:1-34](https://github.com/browserbase/mcp-server-browserbase/blob/main/eslint.config.js)\n\n### Lint-Staged Configuration\n\nThe project uses lint-staged to run automated linting and formatting on staged files before commits:\n\n```json\n\"lint-staged\": {\n \"*.{js,jsx,ts,tsx,json,css,scss,md}\": [\n \"prettier --write .\",\n \"eslint --fix\"\n ]\n}\n```\n\nThis configuration ensures all staged files are formatted with Prettier and fixed with ESLint before being committed, maintaining consistent code style.\n\nSource: [package.json:26-31](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Configuration Resolution Flow\n\nThe testing infrastructure validates the configuration resolution process, which follows a cascading merge strategy:\n\n```mermaid\ngraph LR\n A[Default Config] --> B[CLI Options]\n B --> C[mergeConfig]\n C --> D[normalizeVerifiedConfig]\n D --> E[Final Config]\n \n F[Env: GEMINI_API_KEY] -.-> E\n F -.-> G[modelApiKey]\n G --> E\n```\n\n**Configuration Priority Order (Lowest to Highest):**\n\n1. Default configuration values\n2. Environment variables\n3. CLI options\n4. Explicit verified flag (overrides deprecated advancedStealth)\n\nSource: [src/config.ts:18-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Default Configuration Values\n\nThe test suite validates against the following default configuration structure:\n\n| Property | Default Value | Source |\n|----------|---------------|--------|\n| `browserbaseApiKey` | `process.env.BROWSERBASE_API_KEY` | Environment |\n| `browserbaseProjectId` | `process.env.BROWSERBASE_PROJECT_ID` | Environment |\n| `proxies` | `false` | Hardcoded |\n| `server.port` | `undefined` | None |\n| `server.host` | `undefined` | None |\n| `viewPort.browserWidth` | `1024` | Hardcoded |\n| `viewPort.browserHeight` | `768` | Hardcoded |\n| `modelName` | `google/gemini-2.5-flash-lite` | Hardcoded |\n\nSource: [src/config.ts:18-28](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Test Coverage Areas\n\n### Currently Covered\n\n| Area | File | Status |\n|------|------|--------|\n| Configuration alias mapping | `src/config.test.ts` | Implemented |\n| Verified config priority | `src/config.test.ts` | Implemented |\n| Schema validation | `src/config.test.ts` | Implemented |\n\n### Evals System\n\nThe project includes an evaluation system for testing MCP server behavior:\n\n```bash\n\"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\"\n```\n\nThe evals system runs multiple evaluation configurations to validate the MCP server's functionality against expected behavior patterns.\n\nSource: [package.json:30](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Running Tests\n\n### Standard Test Execution\n\n```bash\n# Run all tests once\npnpm test\n\n# Run tests in watch mode during development\nnpx vitest\n```\n\n### With Evals\n\n```bash\n# Run comprehensive evaluation suite\npnpm evals\n```\n\n### Code Quality Checks\n\n```bash\n# Run ESLint\npnpm lint\n\n# Format code with Prettier\npnpm format\n\n# Run all pre-commit checks\npnpm pre-commit\n```\n\n## Best Practices Demonstrated\n\nThe testing infrastructure demonstrates several best practices:\n\n1. **Co-located tests**: Test files are placed alongside source files with `.test.ts` suffix\n2. **Descriptive test names**: Tests use clear, descriptive names explaining the scenario being validated\n3. **Configuration validation**: Zod schemas are tested for backward compatibility\n4. **Code quality automation**: Pre-commit hooks ensure consistent formatting and linting\n5. **Multiple test configurations**: The eval system provides tiered testing with basic, minimal, and full configurations\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: browserbase/mcp-server-browserbase\n\nSummary: Found 11 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives.\n\n## 1. security_permissions · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. identity · 仓库名和安装名不一致\n\n- Severity: medium\n- Evidence strength: runtime_trace\n- Finding: 仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- User impact: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Suggested check: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Reproduction command: `npx @browserbasehq/mcp`\n- Guardrail action: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. installation · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. security_permissions · 来源证据：Add MCPpedia security badge to README\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. security_permissions · 来源证据：Add policy enforcement for cloud browser sessions\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n\n\n",
"markdown_key": "mcp-server-browserbase",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:899184149",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/browserbase/mcp-server-browserbase"
},
{
"evidence_id": "art_889d6bbaa27a4978989c3e2408bad577",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/browserbase/mcp-server-browserbase#readme"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "mcp-server-browserbase 说明书",
"toc": [
"https://github.com/browserbase/mcp-server-browserbase Project Manual",
"Table of Contents",
"Introduction",
"Project Overview",
"Architecture Overview",
"Available Tools",
"Configuration Options",
"Transport Types",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1e196b3d3c4dc70944e0d19038dd9eb3608b207a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"Dockerfile",
"package.json",
"README.md",
"src/index.ts",
"src/config.ts",
"src/server.ts",
"src/program.ts",
"src/config.test.ts",
"src/transport.ts",
"src/sessionManager.ts",
"src/context.ts",
"src/mcp/sampling.ts",
"src/mcp/resources.ts",
"src/tools/navigate.ts",
"src/tools/observe.ts",
"src/tools/index.ts",
"src/tools/act.ts",
"src/tools/extract.ts",
"src/tools/session.ts",
"src/tools/tool.ts",
"src/types/types.ts",
"src/tools/__tests__/tools.test.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @browserbasehq/mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @browserbasehq/mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/browserbase/mcp-server-browserbase.git` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npm install && npm run build` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `evals/mcp-eval-basic.config.json`, `evals/mcp-eval-minimal.config.json`, `evals/mcp-eval.config.json` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：50\n- 重要文件覆盖：36/50\n- 证据索引条目：35\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @browserbasehq/mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @browserbasehq/mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @browserbasehq/mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Browserbase MCP Server**（project_doc）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Rename Advanced Stealth To Verified**（project_doc）：Add verified as the canonical Browserbase Verified Identity setting while preserving advancedStealth as a deprecated alias. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/rename-advanced-stealth-to-verified.md`\n- **@browserbasehq/mcp**（project_doc）：- 8f0b070: Align tool names and schemas with the hosted Browserbase MCP server at mcp.browserbase.com. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 35 条证据。\n\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **Browserbase MCP Server**（documentation）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@browserbasehq/mcp\", \"version\": \"3.0.0\", \"description\": \"MCP server for AI web browser automation using Browserbase and Stagehand\", \"mcpName\": \"io.github.browserbase/mcp-server-browserbase\", \"license\": \"Apache-2.0\", \"author\": \"Browserbase, Inc. https://www.browserbase.com/ \", \"homepage\": \"https://www.browserbase.com\", \"bugs\": \"https://github.com/browserbase/mcp-server-browserbase/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/browserbase/mcp-server-browserbase\" }, \"type\": \"module\", \"main\": \"./cli.js\", \"module\": \"./src/index.ts\", \"bin\": { \"mcp-server-browserbase\": \"cli.js\" }, \"files\": \"assets\", \"README.md\", \"dist\", \"cli.js\", \"index.d.ts\", \"index.js\", \"config.d.… 证据：`package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Rename Advanced Stealth To Verified**（documentation）：Add verified as the canonical Browserbase Verified Identity setting while preserving advancedStealth as a deprecated alias. 证据：`.changeset/rename-advanced-stealth-to-verified.md`\n- **@browserbasehq/mcp**（documentation）：- 8f0b070: Align tool names and schemas with the hosted Browserbase MCP server at mcp.browserbase.com. 证据：`CHANGELOG.md`\n- **Config**（structured_config）：{ \"$schema\": \"https://unpkg.com/@changesets/config@3.1.1/schema.json\", \"changelog\": \"@changesets/cli/changelog\", \"commit\": false, \"fixed\": , \"linked\": , \"access\": \"public\", \"baseBranch\": \"main\", \"updateInternalDependencies\": \"patch\", \"ignore\": } 证据：`.changeset/config.json`\n- **Mcp Eval Basic.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 180000, \"llmJudge\": false, \"workflows\": { \"name\": \"basic-navigation-test\", \"description\": \"Test basic browser navigation functionality\", \"steps\": { \"user\": \"Create a browser session, navigate to https://example.com, and close the session\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"search-and-extract-test\", \"description\": \"Test navigation, search interaction, and data extraction\", \"steps… 证据：`evals/mcp-eval-basic.config.json`\n- **Mcp Eval Minimal.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 60000, \"llmJudge\": false, \"workflows\": { \"name\": \"smoke-test-navigation\", \"description\": \"Quick test to verify basic navigation works\", \"steps\": { \"user\": \"Open a browser and go to example.org\", \"expectedState\": \"success\" }, { \"user\": \"Close the browser\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"smoke-test-extraction\", \"description\": \"Quick test to verify data extraction works\", \"steps… 证据：`evals/mcp-eval-minimal.config.json`\n- **Mcp Eval.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 180000, \"llmJudge\": false, \"workflows\": { \"name\": \"basic-navigation-test\", \"description\": \"Test basic browser navigation functionality\", \"steps\": { \"user\": \"Create a browser session, navigate to https://example.com, and close the session\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"search-and-extract-test\", \"description\": \"Test navigation, search interaction, and data extraction\", \"steps… 证据：`evals/mcp-eval.config.json`\n- **Gemini Extension**（structured_config）：{ \"name\": \"mcp-server-browserbase\", \"version\": \"2.4.1\", \"mcpServers\": { \"mcp-server-browserbase\": { \"command\": \"npx\", \"args\": \"@browserbasehq/mcp\" } } } 证据：`gemini-extension.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json\", \"name\": \"io.github.browserbase/mcp-server-browserbase\", \"description\": \"MCP server for AI web browser automation using Browserbase and Stagehand\", \"status\": \"active\", \"repository\": { \"url\": \"https://github.com/browserbase/mcp-server-browserbase\", \"source\": \"github\" }, \"version\": \"2.2.0\", \"packages\": { \"registry type\": \"npm\", \"registry base url\": \"https://registry.npmjs.org\", \"identifier\": \"@browserbasehq/mcp\", \"version\": \"2.2.0\", \"transport\": { \"type\": \"stdio\" }, \"environment variables\": { \"description\": \"Your Browserbase API key\", \"is required\": true, \"format\": \"string\", \"is secret\": true, \"name\":… 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"outDir\": \"dist\", \"rootDir\": \"src\", \"noErrorTruncation\": false }, \"include\": \"src/ / .ts\" , \"exclude\": \"node modules\" } 证据：`tsconfig.json`\n- **Dependencies**（source_file）：Documentation .md !README.md assets/ 证据：`.dockerignore`\n- **.gitattributes**（source_file）：package-lock.json linguist-generated=true 证据：`.gitattributes`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log .pnpm-debug.log 证据：`.gitignore`\n- **!/bin/sh**（source_file）：!/bin/sh pnpm install pnpm build pnpm pre-commit 证据：`.husky/pre-commit`\n- **Use npm for package management**（source_file）：Use npm for package management engine-strict=true 证据：`.npmrc`\n- **Dockerfile**（source_file）：COPY package.json pnpm-lock.yaml ./ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \\ pnpm install --frozen-lockfile --ignore-scripts 证据：`Dockerfile`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node import \"./dist/program.js\"; 证据：`cli.js`\n- **Config.D**（source_file）：import type { AvailableModelSchema } from \"@browserbasehq/stagehand\"; 证据：`config.d.ts`\n- **Eslint.Config**（source_file）：import js from \"@eslint/js\"; import globals from \"globals\"; import tseslint from \"typescript-eslint\"; import { defineConfig } from \"eslint/config\"; 证据：`eslint.config.js`\n- **!/usr/bin/env tsx**（source_file）：import { Command } from \"commander\"; import as fs from \"fs/promises\"; import as path from \"path\"; import { evaluate } from \"mcpvals\"; import os from \"os\"; import chalk from \"chalk\"; 证据：`evals/run-evals.ts`\n- **Index.D**（source_file）：import type { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; 证据：`index.d.ts`\n- **Index**（source_file）：import { createServer } from \"./dist/index.js\"; export default { createServer }; 证据：`index.js`\n- **Config.Test**（source_file）：import { describe, expect, it } from \"vitest\"; 证据：`src/config.test.ts`\n- **Config**（source_file）：import type { Config } from \"../config.d.ts\"; 证据：`src/config.ts`\n- **Context**（source_file）：import type { Stagehand } from \"@browserbasehq/stagehand\"; import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; import type { Config } from \"../config.d.ts\"; import { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\"; import { listResources, readResource } from \"./mcp/resources.js\"; import { SessionManager } from \"./sessionManager.js\"; import type { MCPTool } from \"./types/types.js\"; 证据：`src/context.ts`\n- **Index**（source_file）：import as dotenv from \"dotenv\"; dotenv.config ; 证据：`src/index.ts`\n- **Program**（source_file）：import { program } from \"commander\"; import as fs from \"fs\"; import as path from \"path\"; import { fileURLToPath } from \"url\"; 证据：`src/program.ts`\n- **Server**（source_file）：import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; 证据：`src/server.ts`\n- **Sessionmanager**（source_file）：import { Stagehand } from \"@browserbasehq/stagehand\"; import type { Config } from \"../config.d.ts\"; 证据：`src/sessionManager.ts`\n- **Transport**（source_file）：import http from \"node:http\"; import assert from \"node:assert\"; import crypto from \"node:crypto\"; 证据：`src/transport.ts`\n- **Smoke.Test**（source_file）：import { describe, it, expect } from \"vitest\"; import { Client } from \"@modelcontextprotocol/sdk/client/index.js\"; import { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\"; 证据：`tests/smoke.test.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from \"vitest/config\"; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Introduction**：importance `high`\n - source_paths: README.md, package.json, src/index.ts\n- **Quick Start Guide**：importance `high`\n - source_paths: README.md, cli.js, Dockerfile\n- **System Architecture Overview**：importance `high`\n - source_paths: src/index.ts, src/server.ts, src/program.ts, src/types/types.ts\n- **Transport Layer**：importance `medium`\n - source_paths: src/transport.ts, src/server.ts, server.json\n- **MCP Tools Reference**：importance `high`\n - source_paths: src/tools/index.ts, src/tools/navigate.ts, src/tools/act.ts, src/tools/observe.ts, src/tools/extract.ts\n- **Session Management**：importance `high`\n - source_paths: src/sessionManager.ts, src/context.ts, src/tools/session.ts\n- **Configuration Options**：importance `high`\n - source_paths: src/config.ts, src/config.test.ts, config.d.ts\n- **Model Configuration**：importance `medium`\n - source_paths: src/config.ts, src/program.ts, gemini-extension.json\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1e196b3d3c4dc70944e0d19038dd9eb3608b207a`\n- inspected_files: `pnpm-lock.yaml`, `Dockerfile`, `package.json`, `README.md`, `src/index.ts`, `src/config.ts`, `src/server.ts`, `src/program.ts`, `src/config.test.ts`, `src/transport.ts`, `src/sessionManager.ts`, `src/context.ts`, `src/mcp/sampling.ts`, `src/mcp/resources.ts`, `src/tools/navigate.ts`, `src/tools/observe.ts`, `src/tools/index.ts`, `src/tools/act.ts`, `src/tools/extract.ts`, `src/tools/session.ts`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 来源证据：Add MCPpedia security badge to README\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: 来源证据：Add policy enforcement for cloud browser sessions\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 10: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: browserbase/mcp-server-browserbase\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives (high): 可能影响授权、密钥配置或安全边界。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 仓库名和安装名不一致 (medium): 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 Suggested check: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：Your MCP server is now indexed on Joy Trust Network (medium): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/browserbase/mcp-server-browserbase Project Manual\n\nGenerated on: 2026-05-21 16:46:07 UTC\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Quick Start Guide](#quickstart)\n- [System Architecture Overview](#architecture-overview)\n- [Transport Layer](#transport-layer)\n- [MCP Tools Reference](#mcp-tools)\n- [Session Management](#session-management)\n- [Configuration Options](#configuration-options)\n- [Model Configuration](#model-configuration)\n- [Deployment Methods](#deployment-methods)\n- [Testing](#testing)\n\n\n\n## Introduction\n\n### Related Pages\n\nRelated topics: [System Architecture Overview](#architecture-overview), [Quick Start Guide](#quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n \n\n# Introduction\n\nThe **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]()\n\n## Project Overview\n\nThis 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]()\n\n| Attribute | Value |\n|-----------|-------|\n| **Package Name** | `@browserbasehq/mcp` |\n| **Current Version** | `3.0.0` |\n| **License** | Apache 2.0 |\n| **Repository** | `browserbase/mcp-server-browserbase` |\n| **Package Manager** | pnpm 10.12.4 |\n\nSource: [package.json]()\n\n## Architecture Overview\n\nThe MCP server follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[MCP Client] -->|MCP Protocol| B[MCP Server Entry]\n B --> C[Context Manager]\n C --> D[Session Manager]\n C --> E[Tools Registry]\n D --> F[Stagehand Instances]\n F --> G[Browserbase Cloud]\n E --> H[start]\n E --> I[navigate]\n E --> J[act]\n E --> K[observe]\n E --> L[extract]\n E --> M[end]\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|---------------|---------|\n| **Server Entry** | `src/index.ts` | MCP server initialization, tool registration, and request handling |\n| **Context Manager** | `src/context.ts` | Executes tools and manages tool lifecycle |\n| **Session Manager** | `src/sessionManager.ts` | Manages Stagehand browser sessions with lifecycle handling |\n| **Tools Registry** | `src/tools/index.ts` | Defines available MCP tools |\n| **Type Definitions** | `src/types/types.ts` | TypeScript interfaces for sessions, tools, and configurations |\n\nSource: [src/index.ts](), [src/context.ts](), [src/sessionManager.ts](), [src/types/types.ts]()\n\n## Available Tools\n\nThe MCP server exposes six primary tools for browser automation:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `start` | Create a new browser session | `{ apiKey?, projectId?, modelName?, modelApiKey?, browserbaseSessionID?, meta? }` |\n| `navigate` | Navigate to a URL | `{ url: string }` |\n| `act` | Perform an action on the page | `{ action: string }` |\n| `observe` | Observe actionable elements on the page | `{ instruction: string }` |\n| `extract` | Extract data from the page | `{ instruction?: string }` |\n| `end` | Close the browser session | _(none)_ |\n\nSource: [README.md](), [CHANGELOG.md]()\n\n## Configuration Options\n\n### Command-Line Flags\n\nThe server accepts the following configuration flags:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--proxies` | Enable proxy support for sessions | `false` |\n| `--viewportWidth` | Browser viewport width in pixels | `1280` |\n| `--viewportHeight` | Browser viewport height in pixels | `768` |\n| `--modelName` | Stagehand model identifier | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey` | API key for custom model provider | _(none)_ |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [README.md]()\n\n### Configuration Schema\n\nThe server validates configuration using Zod with the following schema:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Browserbase Verified Identity\"),\n advancedStealth: z.boolean().optional().describe(\"Deprecated alias for verified\"),\n keepAlive: z.boolean().optional().describe(\"Keep session alive\"),\n context: z.object({\n contextId: z.string().optional().describe(\"Context ID\")\n }).optional()\n});\n```\n\nSource: [src/index.ts]()\n\n### Required Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `BROWSERBASE_API_KEY` | Your Browserbase API key | Yes |\n| `BROWSERBASE_PROJECT_ID` | Your Browserbase Project ID | Yes |\n| `GEMINI_API_KEY` | Gemini API key (for default model) | Yes |\n\nSource: [README.md](), [server.json]()\n\n## Transport Types\n\nThe MCP server supports two transport mechanisms for communication:\n\n```mermaid\ngraph LR\n A[MCP Client] --> B[SHTTP Transport]\n A --> C[STDIO Transport]\n B -->|HTTP| D[Hosted Server
mcp.browserbase.com]\n C -->|stdin/stdout| E[Local Server]\n E --> F[Direct Installation]\n E --> G[Docker Container]\n```\n\n### SHTTP (Hosted)\n\nThe hosted solution runs at `https://mcp.browserbase.com/mcp` and is the recommended approach for most users. Source: [README.md]()\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n### STDIO (Self-Hosted)\n\nSelf-hosted deployment supports both direct npm installation and Docker containers. Source: [README.md]()\n\n**Via NPM:**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**Via Docker:**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"BROWSERBASE_API_KEY\", \"-e\", \"BROWSERBASE_PROJECT_ID\", \"-e\", \"GEMINI_API_KEY\", \"mcp-browserbase\"]\n }\n }\n}\n```\n\n## Session Management\n\nThe SessionManager handles browser session lifecycle with automatic validation and recreation:\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: No sessions\n Idle --> Creating: start tool called\n Creating --> Active: Session created\n Active --> Validating: Periodic check\n Validating --> Active: Session valid\n Validating --> Recreating: Session stale\n Recreating --> Creating: Retry\n Active --> Closing: end tool called\n Closing --> Idle: Cleanup complete\n```\n\n### Session Validation\n\nSessions 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]()\n\n## Model Configuration\n\nStagehand 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]()\n\n### Supported Models\n\nThe model must be supported by Stagehand. For a full list of supported models, see the [Stagehand documentation](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\n### Custom Model Setup\n\nWhen using a custom model, provide both the model name and API key:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ]\n }\n }\n}\n```\n\nSource: [README.md]()\n\n## Version History\n\n### v3.0.0 (Breaking Changes)\n\nThe latest major version introduced significant changes to align with the hosted MCP server:\n\n- Tool names renamed (e.g., `browserbase_session_create` → `start`)\n- Removed tools: `browserbase_screenshot`, `browserbase_stagehand_get_url`, `browserbase_stagehand_agent`\n- Default model changed from `gemini-2.0-flash` to `google/gemini-2.5-flash-lite`\n- Removed Smithery references and dependencies\n\nSource: [CHANGELOG.md]()\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@browserbasehq/sdk` | `^2.6.0` | Browserbase API client |\n| `@browserbasehq/stagehand` | `^3.3.0` | AI browser automation |\n| `@modelcontextprotocol/sdk` | `^1.13.1` | MCP protocol implementation |\n| `zod` | `^3.25.67` | Schema validation |\n| `commander` | `^14.0.0` | CLI argument parsing |\n\nSource: [package.json]()\n\n## Resources and Sampling\n\nThe server implements MCP's optional capabilities for completeness:\n\n- **Resources**: Currently returns empty (no custom resources defined)\n- **Sampling**: Capability declared but depends on client support\n\nSource: [src/mcp/resources.ts](), [src/mcp/sampling.ts]()\n\n## See Also\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n- [Stagehand Evals](https://www.stagehand.dev/evals)\n\n---\n\n\n\n## Quick Start Guide\n\n### Related Pages\n\nRelated topics: [Introduction](#introduction), [Deployment Methods](#deployment-methods)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# Quick Start Guide\n\nThe 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.\n\n## Overview\n\nThe 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.\n\n### Key Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| **Browser Navigation** | Navigate to URLs and interact with web pages |\n| **Element Interaction** | Click, type, and perform actions on page elements |\n| **Data Extraction** | Extract structured data from web pages |\n| **Session Management** | Create and manage persistent browser sessions |\n| **Proxy Support** | Route traffic through Browserbase proxies |\n| **Stealth Mode** | Use Browserbase Verified Identity for undetected automation |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Architecture\n\n```mermaid\ngraph TD\n A[MCP Client] -->|HTTP or STDIO| B[MCP Server]\n B -->|Tool Calls| C[Context Handler]\n C -->|Session Mgmt| D[Stagehand Instance]\n D -->|Browser Automation| E[Browserbase Cloud]\n E -->|CDP| F[Remote Browser]\n \n G[BROWSERBASE_API_KEY] --> B\n H[BROWSERBASE_PROJECT_ID] --> B\n I[GEMINI_API_KEY] --> B\n```\n\nThe 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.\n\nSource: [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts:32-48)\nSource: [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Available Tools\n\nThe server exposes the following MCP tools that can be called by any compatible MCP client:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `start` | Create a new browser session | `{ apiKey?, projectId?, modelName?, modelApiKey? }` |\n| `end` | Close an existing browser session | `{ sessionId: string }` |\n| `navigate` | Navigate to a URL | `{ url: string }` |\n| `act` | Perform an action on the page | `{ action: string }` |\n| `observe` | Observe actionable elements on the page | `{ instruction: string }` |\n| `extract` | Extract data from the page | `{ instruction?: string }` |\n\nSource: [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Methods\n\nThe server supports multiple transport mechanisms and deployment options depending on your requirements.\n\n```mermaid\ngraph LR\n A[Deployment Options] --> B[SHTTP Hosted]\n A --> C[NPM Package]\n A --> D[Direct Installation]\n A --> E[Docker]\n \n B --> F[Easiest Setup]\n C --> G[Managed Runtime]\n D --> H[Full Control]\n E --> I[Containerized]\n```\n\n### Method 1: SHTTP (Hosted MCP)\n\nThe 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.\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:42-44)\n\n#### Configuration for SHTTP-Clients\n\nIf your MCP client supports HTTP transport:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### Configuration for Non-SHTTP Clients\n\nIf your client only supports STDIO but can invoke external processes:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:46-61)\n\n### Method 2: NPM Package (Recommended for Self-Hosted)\n\nThis method runs the server locally while still using Browserbase's cloud infrastructure for browser sessions.\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nThe package is published as `@browserbasehq/mcp` with version tracking available on npm.\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:82-96)\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:2-6)\n\n### Method 3: Direct Installation\n\nFor full control over the runtime environment, clone and build the repository locally.\n\n#### Prerequisites\n\n- Node.js 18+ \n- npm or pnpm\n- Git\n\n#### Installation Steps\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\nThe build script compiles TypeScript and sets executable permissions on the output files:\n\n```bash\n\"build\": \"tsc && shx chmod +x dist/*.js\"\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:103-115)\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:21)\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Method 4: Docker\n\nContainerized deployment provides isolation and consistency across environments.\n\n#### Build the Image\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:116-143)\n\n## Configuration Options\n\nThe server accepts configuration through environment variables and command-line arguments.\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BROWSERBASE_API_KEY` | Yes | Your Browserbase API key for session management |\n| `BROWSERBASE_PROJECT_ID` | Yes | Your Browserbase Project ID |\n| `GEMINI_API_KEY` | Yes | Gemini API key for LLM inference (default model) |\n\nSource: [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json:17-34)\n\n### Command-Line Flags\n\n| Flag | Description |\n|------|-------------|\n| `--proxies` | Enable Browserbase proxy sessions |\n| `--modelName` | Specify a different model to use (must be supported by Stagehand) |\n| `--modelApiKey` | API key for the custom model |\n| `--keepAlive` | Keep the browser session alive after tool execution |\n| `--verified` | Use Browserbase Verified Identity (Scale Plan only) |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:78-80)\nSource: [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts:15-35)\n\n### Default Configuration\n\nThe server uses sensible defaults that can be overridden:\n\n| Setting | Default Value |\n|---------|---------------|\n| Default Model | `google/gemini-2.5-flash-lite` |\n| Browser Width | 1024px |\n| Browser Height | 768px |\n| Proxies | Disabled |\n| Keep Alive | Disabled |\n\nSource: [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts:37-48)\n\n## Custom Model Configuration\n\nTo use a different LLM model, you must use a self-hosted deployment (not the hosted MCP server) and specify the model name:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\", \"--modelName\", \"anthropic/claude-sonnet-4-20250514\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"ANTHROPIC_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nThe model must be supported in Stagehand. Check the supported models documentation at [docs.stagehand.dev](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md:154-167)\n\n## Session Workflow\n\nBrowser sessions follow a specific lifecycle managed by the MCP server:\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Browserbase\n participant Browser\n \n Client->>Server: start session\n Server->>Browserbase: Create Browserbase Session\n Browserbase->>Browser: Launch Remote Browser\n Browser->>Server: Session Established\n Server->>Client: sessionId returned\n \n Client->>Server: navigate { url }\n Server->>Browser: Load URL\n Browser->>Server: Page Loaded\n Server->>Client: Navigation Complete\n \n Client->>Server: act { action }\n Server->>Browser: Execute Action\n Browser->>Server: Action Result\n Server->>Client: Action Complete\n \n Client->>Server: extract { instruction }\n Server->>Browser: Extract Data\n Browser->>Server: Extracted Data\n Server->>Client: Data Returned\n \n Client->>Server: end session\n Server->>Browserbase: Close Session\n Browserbase->>Browser: Terminate\n Server->>Client: Session Closed\n```\n\n### Session Creation Parameters\n\nWhen starting a session, the following parameters are available:\n\n```typescript\ntype CreateSessionParams = {\n apiKey?: string; // Override default API key\n projectId?: string; // Override default project ID\n modelName?: string; // Use custom model\n modelApiKey?: string; // API key for custom model\n browserbaseSessionID?: string; // Resume existing session\n browserbaseSessionCreateParams?: any; // Browserbase-specific options\n meta?: Record; // Session metadata\n};\n```\n\nSource: [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts:10-20)\n\n## Verifying Installation\n\nAfter configuring your MCP client, verify the connection by checking that the server responds to tool list requests. The server should advertise the following tools:\n\n1. `start` - Session management\n2. `end` - Session cleanup\n3. `navigate` - URL navigation\n4. `act` - Page interactions\n5. `observe` - Element detection\n6. `extract` - Data extraction\n\nYou can use the MCP inspector for debugging:\n\n```bash\nnpx @modelcontextprotocol/inspector build/index.js\n```\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:24)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"browserbaseApiKey is required\" | Set the `BROWSERBASE_API_KEY` environment variable |\n| \"browserbaseProjectId is required\" | Set the `BROWSERBASE_PROJECT_ID` environment variable |\n| Model not supported | Check [Stagehand supported models](https://docs.stagehand.dev/examples/custom_llms#supported-llms) |\n| Docker connection issues | Ensure environment variables are passed with `-e` flags |\n\nSource: [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts:8-14)\n\n## Development\n\nFor local development and testing:\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the project\npnpm build\n\n# Run tests\npnpm test\n\n# Watch mode for development\npnpm watch\n\n# Lint code\npnpm lint\n\n# Format code\npnpm format\n```\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json:21-31)\n\n## Next Steps\n\n- Review the [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction) for advanced usage\n- Explore the [MCP Specification](https://spec.modelcontextprotocol.io/) for protocol details\n- Check the [Stagehand Documentation](https://docs.stagehand.dev/) for browser automation capabilities\n- Report issues at [GitHub Issues](https://github.com/browserbase/mcp-server-browserbase/issues)\n\n---\n\n\n\n## System Architecture Overview\n\n### Related Pages\n\nRelated topics: [Transport Layer](#transport-layer), [MCP Tools Reference](#mcp-tools), [Session Management](#session-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# System Architecture Overview\n\nThe 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.\n\n## Architecture Layers\n\nThe system follows a layered architecture pattern that separates concerns between transport, protocol, execution, and browser automation.\n\n```mermaid\ngraph TD\n subgraph \"Transport Layer\"\n STDIO[STDIO Transport]\n SHTTP[SHTTP Transport]\n end\n \n subgraph \"MCP Protocol Layer\"\n MCP_SDK[MCP SDK Server]\n Tools[MCP Tools]\n Resources[Resources]\n Sampling[Sampling]\n end\n \n subgraph \"Application Layer\"\n Context[Context Controller]\n Config[Configuration Resolver]\n SessionMgr[Session Manager]\n end\n \n subgraph \"Browser Automation Layer\"\n Stagehand[Stagehand Instance]\n Browserbase[Browserbase SDK]\n end\n \n STDIO --> MCP_SDK\n SHTTP --> MCP_SDK\n MCP_SDK --> Tools\n MCP_SDK --> Resources\n MCP_SDK --> Sampling\n Context --> SessionMgr\n SessionMgr --> Stagehand\n Stagehand --> Browserbase\n```\n\n**Source:** [src/index.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts) | [src/context.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Core Components\n\n### 1. Entry Point and CLI (program.ts)\n\nThe application entry point uses Commander.js to parse command-line arguments and initialize the server.\n\n```mermaid\ngraph LR\n CLI[CLI Arguments] --> Program[program.ts]\n Program --> Config[resolveConfig]\n Config --> CreateServer[createServer]\n CreateServer --> Transport[Start Transport]\n```\n\n**Source:** [src/program.ts:1-80](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n\n**Command-line options supported:**\n\n| Flag | Type | Description | Default |\n|------|------|-------------|---------|\n| `--browserbaseApiKey` | string | Browserbase API Key | env.BROWSERBASE_API_KEY |\n| `--browserbaseProjectId` | string | Browserbase Project ID | env.BROWSERBASE_PROJECT_ID |\n| `--proxies` | boolean | Enable Browserbase proxies | false |\n| `--verified` | boolean | Use Verified Identity (Scale Plan) | false |\n| `--advancedStealth` | boolean | Deprecated alias for verified | false |\n| `--contextId` | string | Browserbase Context ID | undefined |\n| `--persist` | boolean | Keep session alive | false |\n| `--port` | number | SHTTP transport port | undefined (uses STDIO) |\n| `--host` | string | SHTTP bind host | undefined |\n| `--browserWidth` | number | Viewport width | 1024 |\n| `--browserHeight` | number | Viewport height | 768 |\n| `--modelName` | string | Stagehand model | google/gemini-2.5-flash-lite |\n| `--modelApiKey` | string | Custom model API key | env.GEMINI_API_KEY |\n| `--experimental` | boolean | Enable experimental features | false |\n\n**Source:** [src/config.ts:15-28](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 2. Configuration System\n\nThe configuration system uses Zod for schema validation and implements a merge strategy: Defaults < File Config < CLI Options.\n\n```mermaid\ngraph TD\n Default[Default Config] --> Merge[mergeConfig]\n File[File Config] --> Merge\n CLI[CLI Options] --> Merge\n Merge --> Normalize[normalizeVerifiedConfig]\n Normalize --> FinalConfig[Resolved Config]\n FinalConfig --> AddEnvVars[Add Env Vars]\n AddEnvVars --> Validate[Validation]\n```\n\n**Source:** [src/config.ts:50-75](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n**Configuration schema (Zod):**\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Use Browserbase Verified Identity\"),\n keepAlive: z.boolean().optional().describe(\"Keep session alive\"),\n context: z.object({\n contextId: z.string().optional()\n }).optional()\n});\n```\n\n**Source:** [src/index.ts:30-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### 3. MCP Server (server.ts + index.ts)\n\nThe MCP server is built on the @modelcontextprotocol/sdk and handles tool registration, request routing, and protocol compliance.\n\n**Source:** [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts) | [src/index.ts:80-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n**MCP Server capabilities:**\n\n| Capability | Implementation | Description |\n|------------|----------------|-------------|\n| Tools | TOOLS array | Browser automation operations |\n| Resources | RESOURCE_TEMPLATES | URI-based resource access |\n| Sampling | SAMPLING_CAPABILITY | Server-initiated LLM completions |\n\n### 4. Context Controller (context.ts)\n\nThe Context class serves as the central orchestrator, maintaining references to the MCP server instance, configuration, and SessionManager.\n\n```mermaid\nclassDiagram\n class Context {\n +Server server\n +Config config\n -SessionManager sessionManager\n +getServer() Server\n +getSessionManager() SessionManager\n +getStagehand(sessionId?) Promise~Stagehand~\n +run(tool, params) CallToolResult\n }\n \n class SessionManager {\n -Map sessions\n -string activeSessionId\n +createSession(config) Promise~Session~\n +getSession(id) Promise~Session~\n +closeSession(id) Promise~void~\n +getActiveSessionId() string\n }\n \n Context --> SessionManager\n```\n\n**Source:** [src/context.ts:15-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n### 5. Session Manager (sessionManager.ts)\n\nThe SessionManager handles lifecycle management of browser sessions, creating and caching Stagehand instances per session.\n\n**Source:** [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n**Session lifecycle:**\n\n```mermaid\nstateDiagram-v2\n [*] --> NoSession: Initial State\n NoSession --> Creating: start tool called\n Creating --> Active: Stagehand initialized\n Active --> Active: navigate/act/observe/extract\n Active --> Closing: end tool called\n Closing --> NoSession: Session closed\n Closing --> Active: Error, retry\n```\n\n### 6. Tool System\n\nTools are the primary interface for MCP clients to interact with browser automation capabilities.\n\n**Source:** [src/tools/index.ts:1-25](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n**Available tools:**\n\n| Tool | Description | Input Schema |\n|------|-------------|--------------|\n| `start` | Create new browser session | `{ contextId?: string, proxies?: boolean, verified?: boolean }` |\n| `end` | Close browser session | `{}` |\n| `navigate` | Navigate to URL | `{ url: string }` |\n| `act` | Perform action on page | `{ action: string }` |\n| `observe` | Observe actionable elements | `{ instruction: string }` |\n| `extract` | Extract data from page | `{ instruction?: string }` |\n\n**Source:** [src/tools/index.ts:10-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n**Tool registration flow:**\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Context as Context\n participant SessionMgr as SessionManager\n participant Stagehand as Stagehand\n \n Client->>Server: Call Tool\n Server->>Context: run(tool, params)\n Context->>SessionMgr: getSession(id)\n SessionMgr->>Stagehand: Get/Create Instance\n Stagehand->>Stagehand: Execute operation\n Stagehand-->>Context: Result\n Context-->>Server: CallToolResult\n Server-->>Client: JSON-RPC Response\n```\n\n## Transport Layer\n\nThe server supports two transport mechanisms for MCP communication.\n\n**Source:** [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n| Transport | Use Case | Configuration |\n|-----------|----------|---------------|\n| STDIO | Local CLI tools, Claude Desktop | Default when no port specified |\n| SHTTP | HTTP clients, Remote servers | `--port` flag required |\n\n**STDIO Configuration (Docker):**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"mcp-browserbase\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Data Flow\n\n### Tool Execution Pipeline\n\n```mermaid\ngraph TD\n Request[Tool Request] --> Validate[Zod Validation]\n Validate --> Authenticate[Auth Check]\n Authenticate --> GetSession[Get Session]\n GetSession --> GetStagehand[Get Stagehand]\n GetStagehand --> Execute[Execute Tool]\n Execute --> Transform[Transform Result]\n Transform --> Response[JSON-RPC Response]\n \n Execute -->|Error| ErrorHandler[Error Handler]\n ErrorHandler --> Response\n```\n\n**Source:** [src/index.ts:110-145](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### Configuration Merging Strategy\n\n```mermaid\ngraph LR\n A[Defaults] -->|Low Priority| M[Merge Config]\n B[Environment Vars] -->|Medium Priority| M\n C[CLI Arguments] -->|High Priority| M\n M --> R[Resolved Config]\n```\n\n**Source:** [src/config.ts:40-65](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Type System\n\n**Source:** [src/types/types.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/types/types.ts)\n\n### Key Types\n\n| Type | Definition | Usage |\n|------|------------|-------|\n| `MCPTool` | Tool definition with schema | Tool registration |\n| `MCPToolsArray` | Array of MCPTool | Tool collection |\n| `Config` | Server configuration interface | All config operations |\n| `CLIOptions` | Command-line options | CLI parsing |\n\n### Configuration Interface (config.d.ts)\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies: boolean;\n verified?: boolean;\n modelName: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n viewPort?: {\n browserWidth: number;\n browserHeight: number;\n };\n server?: {\n port?: number;\n host?: string;\n };\n}\n```\n\n**Source:** [config.d.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Dependencies Architecture\n\n**Source:** [package.json:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n```mermaid\ngraph BT\n MCP[\"@modelcontextprotocol/sdk\"]\n Stagehand[\"@browserbasehq/stagehand\"]\n BrowserbaseSDK[\"@browserbasehq/sdk\"]\n Zod[\"zod\"]\n Commander[\"commander\"]\n \n mcp-server-browserbase --> MCP\n mcp-server-browserbase --> Stagehand\n mcp-server-browserbase --> BrowserbaseSDK\n mcp-server-browserbase --> Zod\n mcp-server-browserbase --> Commander\n```\n\n### Core Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP protocol implementation |\n| `@browserbasehq/stagehand` | ^3.3.0 | AI browser automation |\n| `@browserbasehq/sdk` | ^2.6.0 | Browserbase API client |\n| `zod` | ^3.25.67 | Schema validation |\n| `commander` | ^14.0.0 | CLI framework |\n\n## Error Handling\n\nThe server implements structured error handling at multiple levels:\n\n**Source:** [src/index.ts:125-140](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```mermaid\ngraph TD\n Error[Error Thrown] --> Log[Log to stderr]\n Log --> Format[Format error message]\n Format --> Throw[Throw MCP Error]\n Throw --> Response[JSON-RPC Error Response]\n \n Response --> Client[Client receives error]\n```\n\n**Error message format:**\n```\n[MCP Error] {ISO timestamp} Error running tool {tool_name}: {error_message}\n```\n\n## Module Structure Summary\n\n```\nmcp-server-browserbase/\n├── src/\n│ ├── index.ts # Server factory, tool registration\n│ ├── server.ts # MCP server initialization\n│ ├── program.ts # CLI entry point\n│ ├── context.ts # Central controller\n│ ├── config.ts # Configuration resolver\n│ ├── sessionManager.ts # Session lifecycle\n│ ├── transport.ts # STDIO/SHTTP transport\n│ ├── types/\n│ │ └── types.ts # TypeScript definitions\n│ ├── mcp/\n│ │ ├── resources.ts # MCP resources\n│ │ └── sampling.ts # MCP sampling\n│ └── tools/\n│ ├── index.ts # Tool exports\n│ ├── session.ts # start/end tools\n│ ├── navigate.ts # navigate tool\n│ ├── act.ts # act tool\n│ ├── observe.ts # observe tool\n│ └── extract.ts # extract tool\n├── config.d.ts # Config interface definition\n├── package.json # Dependencies and scripts\n└── README.md # Documentation\n```\n\n## Deployment Modes\n\n### NPM Package (npx)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Docker Container\n\n```bash\ndocker build -t mcp-browserbase .\n```\n\n### Hosted MCP Server\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n**Source:** [README.md:50-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n---\n\n\n\n## Transport Layer\n\n### Related Pages\n\nRelated topics: [System Architecture Overview](#architecture-overview), [Deployment Methods](#deployment-methods)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# Transport Layer\n\n## Overview\n\nThe 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.\n\nThe transport layer is responsible for:\n\n- Accepting incoming connections from MCP clients\n- Managing server sessions for stateful communication\n- Routing requests to appropriate handlers\n- Handling the serialization and deserialization of MCP protocol messages\n\nSource: [src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Supported Transport Protocols\n\nThe MCP server supports two transport protocols:\n\n| Transport Type | Description | Use Case |\n|----------------|-------------|----------|\n| **STDIO** | Standard Input/Output communication via process streams | Local development, CLI tools, direct execution |\n| **SHTTP** | Streamable HTTP transport using the MCP HTTP extension | Hosted deployments, production environments, remote access |\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### STDIO Transport\n\nThe STDIO transport uses standard input and output streams for communication. This is the default transport when no server configuration is provided.\n\n```mermaid\ngraph LR\n A[MCP Client] -->|stdin| B[MCP Server]\n B -->|stdout| A\n```\n\nThe STDIO transport is initialized when both `port` and `host` are undefined in the server configuration. Source: [config.d.ts:45-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### SHTTP (Streamable HTTP) Transport\n\nThe SHTTP transport uses HTTP with session management for stateful communication. It supports multiple concurrent sessions through a session ID mechanism.\n\n```mermaid\ngraph TD\n A[HTTP Request] --> B{Session ID Present?}\n B -->|Yes| C[Existing Session]\n B -->|No| D[Create New Session]\n C --> E[StreamableHTTPServerTransport]\n D --> F[Generate UUID Session ID]\n F --> E\n E --> G[Server Instance]\n G --> H[Tool Execution]\n```\n\nSource: [src/transport.ts:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Architecture\n\n### Server Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transport\n participant Server\n participant SessionManager\n participant Stagehand\n\n Client->>Transport: HTTP Request\n Transport->>Transport: Check Session ID\n alt No Session\n Transport->>Transport: Generate UUID\n Transport->>Server: Create Instance\n Server->>SessionManager: Initialize Session\n Server->>Stagehand: Create Browser Context\n else Has Session\n Transport->>Server: Route to Existing Session\n end\n Server->>Transport: Process Request\n Transport->>Client: Response\n```\n\n### Component Responsibilities\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `startStdioTransport` | [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts) | Initializes STDIO transport with the MCP SDK |\n| `startHttpTransport` | [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts) | Creates HTTP server with session management |\n| `ServerList` | [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts) | Manages server instance lifecycle |\n| `Context` | [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts) | Holds server state and session information |\n\n## Session Management\n\nThe SHTTP transport implements a session-based model to maintain state across multiple requests.\n\n### Session Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> NoSession: No Session ID Header\n NoSession --> Active: POST /mcp\n Active --> Active: Subsequent Requests\n Active --> Closed: Transport Close Event\n Closed --> [*]\n```\n\n### Session Storage\n\nSessions are stored in an in-memory `Map` structure:\n\n```typescript\nconst streamableSessions = new Map();\n```\n\n| Operation | Method | Description |\n|-----------|--------|-------------|\n| Create | POST without session ID | Generates new UUID, creates transport |\n| Retrieve | Request with session ID | Looks up existing transport from Map |\n| Delete | Transport close event | Removes session from Map on `onclose` |\n\nSource: [src/transport.ts:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Configuration\n\n### Server Transport Options\n\nThe transport layer is configured through the `server` configuration object:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `port` | `number` | `undefined` | Port for SHTTP transport. When `undefined`, uses STDIO |\n| `host` | `string` | `\"localhost\"` | Host interface to bind. Use `\"0.0.0.0\"` for external access |\n\nSource: [config.d.ts:40-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Configuration Resolution\n\nThe configuration is resolved in order of precedence:\n\n1. **Default values** - Built-in defaults for all options\n2. **Environment variables** - `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, etc.\n3. **CLI options** - Command-line arguments passed at runtime\n\n```mermaid\ngraph LR\n A[CLI Options] --> B[mergeConfig]\n C[Default Config] --> B\n B --> D[normalizeVerifiedConfig]\n D --> E[Final Config]\n```\n\nSource: [src/config.ts:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BROWSERBASE_API_KEY` | Yes | Browserbase authentication key |\n| `BROWSERBASE_PROJECT_ID` | Yes | Browserbase project identifier |\n| `GEMINI_API_KEY` | For default model | Google AI API key (falls back to `GOOGLE_API_KEY`) |\n\nSource: [src/config.ts:55-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Request Handling\n\n### HTTP Request Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Incoming HTTP Request │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ URL Validation │\n│ Check: url.pathname.startsWith(\"/mcp\") │\n└─────────────────────────────────────────────────────────────┘\n │\n ┌───────────────┴───────────────┐\n │ │\n ▼ ▼\n [Invalid URL] [Valid /mcp]\n Return 400 Continue\n │ │\n ▼ ▼\n ┌─────────┐ ┌─────────────────────────┐\n │ End │ │ Session Check │\n └─────────┘ │ mcp-session-id header? │\n └─────────────────────────┘\n │\n ┌───────────────┴───────────────┐\n │ │\n ▼ ▼\n [Session Found] [No Session]\n Route to transport Create new transport\n from Map Generate UUID\n │ │\n │ ┌────────┴────────┐\n │ │ Create Server │\n │ │ Connect │\n │ └────────────────┘\n ▼ │\n ┌─────────────────┐ │\n │ Handle Request │◄──────────────────────┘\n │ via Transport │\n └─────────────────┘\n```\n\nSource: [src/transport.ts:35-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## Security Considerations\n\nThe transport layer implements several security measures:\n\n| Aspect | Implementation | Notes |\n|--------|---------------|-------|\n| **Default Binding** | `localhost` | Only accepts local connections by default |\n| **External Access** | Explicit `host: \"0.0.0.0\"` | Requires deliberate configuration |\n| **Session Isolation** | Session ID validation | Requests without valid session ID rejected |\n| **Session Cleanup** | `onclose` handler | Automatic removal of closed sessions |\n\nSource: [config.d.ts:47-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Security Recommendations\n\n1. **Development**: Use default `localhost` binding\n2. **Production**: If external access required:\n - Use firewall rules to restrict access\n - Consider VPN or reverse proxy\n - Implement authentication at the application layer\n3. **Hosted Service**: Use Browserbase hosted MCP at `https://mcp.browserbase.com/mcp` for managed security\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Usage Examples\n\n### STDIO Configuration (Self-Hosted)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### SHTTP Configuration (Hosted)\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n### Docker with SHTTP\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ]\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## CLI Options\n\nThe transport layer can be configured via command-line arguments:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--browserbaseApiKey ` | Browserbase API Key | Environment variable |\n| `--browserbaseProjectId ` | Browserbase Project ID | Environment variable |\n| `--proxies` | Enable Browserbase proxies | `false` |\n| `--verified` | Use Verified Identity | `false` |\n| `--port ` | SHTTP server port | STDIO if unset |\n| `--host ` | SHTTP bind address | `localhost` |\n| `--browserWidth ` | Viewport width | `1024` |\n| `--browserHeight ` | Viewport height | `768` |\n| `--modelName ` | Stagehand model | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey ` | Custom model API key | Required for custom models |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [src/config.ts:15-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Error Handling\n\nThe transport layer implements robust error handling:\n\n| Error Scenario | Handling | Response |\n|----------------|----------|----------|\n| Missing URL | Return 400 | `\"Bad request: missing URL\"` |\n| Session not found | Return 404 | `\"Session not found\"` |\n| Invalid request method | Return 400 | `\"Invalid request\"` |\n| Tool execution failure | Log to stderr, throw MCP error | Formatted error message |\n\nSource: [src/transport.ts:20-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\nError responses are logged with ISO timestamps for debugging:\n\n```typescript\nprocess.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n);\n```\n\nSource: [src/index.ts:120-125](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n## Dependencies\n\nThe transport layer relies on the following key dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | `^1.13.1` | MCP protocol implementation, transport abstractions |\n| `@browserbasehq/stagehand` | `^3.3.0` | Browser automation capabilities |\n| `http` | Node.js built-in | HTTP server for SHTTP transport |\n| `crypto` | Node.js built-in | UUID generation for session IDs |\n\nSource: [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n---\n\n\n\n## MCP Tools Reference\n\n### Related Pages\n\nRelated topics: [Session Management](#session-management), [System Architecture Overview](#architecture-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n- [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n- [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n \n\n# MCP Tools Reference\n\nThis page documents all available MCP (Model Context Protocol) tools provided by the Browserbase MCP Server for AI-powered web browser automation.\n\n## Overview\n\nThe 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.\n\nSource: [src/tools/index.ts:1-18](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Architecture\n\nThe tools module follows a modular architecture where each tool is defined as an independent module with a consistent schema and handler structure.\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[TOOLS Array]\n B --> C[Session Tools]\n B --> D[navigateTool]\n B --> E[actTool]\n B --> F[observeTool]\n B --> G[extractTool]\n \n C --> H[start]\n C --> I[end]\n \n J[Context] --> K[SessionManager]\n K --> L[Stagehand Instances]\n```\n\nAll tools are exported as a unified array that matches the hosted MCP server at `mcp.browserbase.com`. Source: [src/tools/index.ts:13-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Tool Registration\n\nTools 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.\n\nSource: [src/index.ts:42-63](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Tool as Tool Handler\n participant Context as Context\n participant Stagehand as Stagehand\n \n MCP->>Tool: Execute Tool with params\n Tool->>Context: context.run(tool, params)\n Context->>Stagehand: Invoke Stagehand method\n Stagehand-->>Context: Return result\n Context-->>MCP: CallToolResult\n```\n\n## Tool Schema Structure\n\nAll tools implement a common interface defined in the `MCPTool` type. Each tool consists of a schema and a handler function.\n\nSource: [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `schema.name` | `string` | Unique identifier for the tool |\n| `schema.description` | `string` | Human-readable description of tool functionality |\n| `schema.inputSchema` | `ZodObject` | Validation schema for tool parameters |\n\n## Available Tools\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Session Management | `start`, `end` | Create and terminate browser sessions |\n| Navigation | `navigate` | Navigate to URLs |\n| Interaction | `act` | Perform actions on page elements |\n| Observation | `observe` | Identify actionable elements |\n| Extraction | `extract` | Extract data from pages |\n\n### Complete Tool List\n\nSource: [src/tools/index.ts:13-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n```typescript\nexport const TOOLS = [\n ...sessionTools, // start, end\n navigateTool, // navigate\n actTool, // act\n observeTool, // observe\n extractTool, // extract\n];\n```\n\n## Session Management Tools\n\nSession tools manage the lifecycle of Browserbase browser sessions. Each session maintains its own Stagehand instance for isolated browser automation.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n```mermaid\ngraph LR\n A[start] -->|Creates| B[SessionManager]\n B -->|Manages| C[Stagehand Instance]\n C --> D[Browser Tab]\n E[end] -->|Closes| B\n```\n\n### `start` Tool\n\nCreates a new browser session and initializes a Stagehand instance. A session must be started before any other tools can be used.\n\n**Renamed in v3.0.0** - Previously named `browserbase_session_create`.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `proxy` | `boolean` | No | Enable Browserbase proxies |\n| `verified` | `boolean` | No | Use Browserbase Verified Identity (Scale Plan only) |\n| `modelName` | `string` | No | Custom LLM model name |\n| `modelApiKey` | `string` | No | API key for custom model |\n| `keepAlive` | `boolean` | No | Keep session alive after operations |\n| `contextId` | `string` | No | Optional context identifier |\n\n### `end` Tool\n\nCloses the current browser session and releases all associated resources.\n\n**Renamed in v3.0.0** - Previously named `browserbase_session_close`.\n\nSource: [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| No parameters | - | - | Closes the active session |\n\n## Navigation Tool\n\n### `navigate` Tool\n\nNavigates the browser to a specified URL. The tool uses Stagehand's navigation capabilities for reliable page loading.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_navigate`.\n\nSource: [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | `string` | Yes | The target URL to navigate to |\n\n**Example usage:**\n\n```json\n{\n \"name\": \"navigate\",\n \"arguments\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n## Interaction Tool\n\n### `act` Tool\n\nPerforms 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.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_act`.\n\n**Breaking change in v3.0.0** - The `variables` parameter has been removed.\n\nSource: [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | `string` | Yes | Natural language description of the action to perform |\n\n**Supported action types:**\n\n- Click on elements (buttons, links, etc.)\n- Fill form fields (text inputs, textareas)\n- Select dropdown options\n- Check/uncheck checkboxes\n- Submit forms\n\n**Example usage:**\n\n```json\n{\n \"name\": \"act\",\n \"arguments\": {\n \"action\": \"Click the 'Sign In' button\"\n }\n}\n```\n\n## Observation Tool\n\n### `observe` Tool\n\nObserves the current page and identifies all actionable elements. Returns a list of elements that can be interacted with, categorized by type.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_observe`.\n\nSource: [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `instruction` | `string` | Yes | Description of what elements to look for |\n\n**Example usage:**\n\n```json\n{\n \"name\": \"observe\",\n \"arguments\": {\n \"instruction\": \"Find all clickable buttons on the page\"\n }\n}\n```\n\n**Return value structure:**\n\nThe tool returns an array of observed elements with their properties:\n\n```typescript\ninterface ObservedElement {\n type: \"button\" | \"link\" | \"input\" | \"select\" | ...;\n description: string;\n selector?: string;\n attributes?: Record;\n}\n```\n\n## Data Extraction Tool\n\n### `extract` Tool\n\nExtracts structured data from the current page based on natural language instructions. Uses AI to understand the page content and return relevant information.\n\n**Renamed in v3.0.0** - Previously named `browserbase_stagehand_extract`.\n\n**Breaking change in v3.0.0** - The `instruction` parameter is now optional.\n\nSource: [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `instruction` | `string` | No | Natural language description of what data to extract |\n\nWhen `instruction` is omitted, the tool extracts all meaningful content from the page.\n\n**Example usage:**\n\n```json\n{\n \"name\": \"extract\",\n \"arguments\": {\n \"instruction\": \"Extract all product names and prices\"\n }\n}\n```\n\n## Tool Handler Implementation\n\nEach tool follows a consistent implementation pattern using the tool factory function.\n\nSource: [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n```typescript\nexport interface MCPTool {\n schema: {\n name: string;\n description: string;\n inputSchema: z.ZodObject;\n };\n handler: (params: any, context: Context) => Promise;\n}\n```\n\n### Handler Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `params` | `object` | Validated input parameters matching the tool's inputSchema |\n| `context` | `Context` | Server context providing access to SessionManager and Stagehand instances |\n\n## Error Handling\n\nAll tool handlers are wrapped in try-catch blocks at the MCP server level. Errors are logged with timestamps and re-thrown with descriptive messages.\n\nSource: [src/index.ts:47-59](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n );\n throw new Error(\n `Failed to run tool '${tool.schema.name}': ${errorMessage}`,\n );\n}\n```\n\n## Session Management Integration\n\nTools interact with the SessionManager through the Context class, which provides synchronized access to session state.\n\nSource: [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n```mermaid\ngraph TD\n A[Tool Handler] --> B[Context.run]\n B --> C[currentSessionId getter]\n C --> D[SessionManager.getActiveSessionId]\n D --> E[Returns active session]\n B --> F[SessionManager.getSession]\n F --> G[Stagehand instance]\n```\n\nThe `currentSessionId` property is a getter that delegates to SessionManager to ensure synchronization between Context and SessionManager session tracking.\n\nSource: [src/context.ts:18-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Configuration Options\n\nThe following configuration options affect tool behavior:\n\n| Option | Tool Affected | Description |\n|--------|---------------|-------------|\n| `proxies` | `start` | Enable Browserbase proxies for the session |\n| `verified` | `start` | Enable Verified Identity (Scale Plan) |\n| `modelName` | `start` | Specify custom LLM model |\n| `modelApiKey` | `start` | API key for custom model |\n| `keepAlive` | `start` | Prevent session timeout |\n| `browserWidth` | `start` | Browser viewport width (default: 1024) |\n| `browserHeight` | `start` | Browser viewport height (default: 768) |\n\n## Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant Handler as Tool Handler\n participant Context as Context\n participant Session as SessionManager\n participant Stagehand as Stagehand\n \n Client->>Server: tool/CallRequest\n Server->>Handler: Execute with params\n Handler->>Context: context.run(tool, params)\n Context->>Session: getSession(currentSessionId)\n Session->>Stagehand: Get/initialize instance\n Stagehand-->>Context: Stagehand ready\n Context->>Stagehand: Execute operation\n Stagehand-->>Handler: Result\n Handler-->>Server: CallToolResult\n Server-->>Client: Response\n```\n\n## Changelog\n\n### v3.0.0 Breaking Changes\n\nSource: [CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n\n| Change | Previous | Current |\n|--------|----------|---------|\n| `browserbase_session_create` | `start` | Tool renamed |\n| `browserbase_session_close` | `end` | Tool renamed |\n| `browserbase_stagehand_navigate` | `navigate` | Tool renamed |\n| `browserbase_stagehand_act` | `act` | Tool renamed |\n| `browserbase_stagehand_observe` | `observe` | Tool renamed |\n| `browserbase_stagehand_extract` | `extract` | Tool renamed |\n| `act` parameters | `variables` accepted | Removed |\n| `extract` parameters | `instruction` required | Now optional |\n| Default model | `gemini-2.0-flash` | `google/gemini-2.5-flash-lite` |\n\n### Removed Tools\n\nThe following tools were removed in v3.0.0:\n\n- `browserbase_screenshot` - Screenshot functionality consolidated elsewhere\n- `browserbase_stagehand_get_url` - URL accessible via session state\n- `browserbase_stagehand_agent` - Agent capabilities restructured\n\n## See Also\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n\n---\n\n\n\n## Session Management\n\n### Related Pages\n\nRelated topics: [MCP Tools Reference](#mcp-tools), [Configuration Options](#configuration-options)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# Session Management\n\n## Overview\n\nSession 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.\n\nThe session management system serves as the backbone for all browser-based operations, providing:\n\n- **Isolation**: Multiple concurrent browser sessions with independent state\n- **Lifecycle Management**: Automated creation, validation, cleanup, and recovery\n- **Concurrency Control**: Mutex patterns to prevent race conditions during session creation\n- **Resource Optimization**: Session reuse and graceful cleanup to minimize resource consumption\n\nSource: [src/sessionManager.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Architecture\n\n### High-Level Components\n\nThe session management architecture consists of three primary layers working in coordination:\n\n```mermaid\ngraph TD\n subgraph \"MCP Layer\"\n MCP[\"MCP Server\"]\n Tools[\"Session Tools
(start, end)\"]\n end\n \n subgraph \"Context Layer\"\n Context[\"Context
(src/context.ts)\"]\n SessionId[\"currentSessionId
(getter)\"]\n end\n \n subgraph \"Session Management Layer\"\n SM[\"SessionManager
(src/sessionManager.ts)\"]\n Browsers[\"Map<string, BrowserSession>\"]\n Active[\"activeSessionId\"]\n Default[\"defaultBrowserSession\"]\n Mutex[\"defaultSessionCreationPromise\"]\n Cleanup[\"cleaningUpSessions\"]\n end\n \n subgraph \"Stagehand Layer\"\n Stagehand[\"Stagehand Instance\"]\n Browser[\"Browser Context\"]\n Page[\"Page\"]\n end\n \n MCP --> Tools\n Tools --> Context\n Context --> SM\n SM --> Stagehand\n Stagehand --> Browser\n Browser --> Page\n \n Context -.-> SessionId\n SM -.-> Browsers\n SM -.-> Active\n SM -.-> Default\n SM -.-> Mutex\n SM -.-> Cleanup\n```\n\n### Class Hierarchy\n\n| Layer | Class/Module | Responsibility |\n|-------|--------------|----------------|\n| MCP | `TOOLS` array | Exposes session tools via MCP protocol |\n| Context | `Context` | Central controller, holds SessionManager reference |\n| Session | `SessionManager` | Core session lifecycle management |\n| Stagehand | `createStagehandInstance()` | Browser automation driver |\n\nSource: [src/context.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Data Model\n\n### BrowserSession Interface\n\n```typescript\ninterface BrowserSession {\n page: Page; // Playwright Page instance\n sessionId: string; // Browserbase session identifier\n stagehand: Stagehand; // Stagehand automation instance\n}\n```\n\nSource: [src/sessionManager.ts:120-125](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### SessionManager State\n\nThe `SessionManager` class maintains the following internal state:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `browsers` | `Map` | Stores all active browser sessions |\n| `defaultBrowserSession` | `BrowserSession \\| null` | Reference to the default session |\n| `defaultSessionId` | `string` | Unique identifier for the default session |\n| `activeSessionId` | `string` | Currently active session ID |\n| `defaultSessionCreationPromise` | `Promise \\| null` | Mutex for concurrent creation attempts |\n| `cleaningUpSessions` | `Set` | Tracks sessions currently being cleaned |\n\nSource: [src/sessionManager.ts:56-73](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Lifecycle\n\n### Lifecycle States\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: createNewBrowserSession()\n Created --> Active: setActiveSessionId()\n Active --> Validating: getSession()\n Validating --> Active: Session valid\n Validating --> Recreating: Session stale\n Recreating --> Active: Recreated successfully\n Recreating --> Error: Creation failed\n Active --> CleaningUp: cleanupSession()\n CleaningUp --> [*]: Cleanup complete\n Active --> [*]: closeAllSessions()\n```\n\n### Session Creation Flow\n\n```mermaid\ngraph TD\n Start[\"Request Session\"] --> CheckDefault{\"Is Default
Session?\"}\n \n CheckDefault -->|Yes| CheckInProgress{\"Creation
In Progress?\"}\n CheckDefault -->|No| GetFromMap[\"Get from
browsers Map\"]\n \n CheckInProgress -->|Yes| Wait[\"Wait for
existing promise\"]\n CheckInProgress -->|No| CheckExists{\"Session
Exists?\"}\n \n Wait --> ReturnExisting[\"Return Promise\"]\n CheckExists -->|No| Create[\"createNewBrowserSession()\"]\n CheckExists -->|Yes| Validate[\"Validate
Session\"]\n \n Create --> Stagehand[\"Create Stagehand
Instance\"]\n Stagehand --> Extract[\"Extract Page &
Session ID\"]\n Extract --> Store[\"Store in Map\"]\n Store --> SetActive[\"Set Active\"]\n \n Validate -->|Valid| Return[\"Return Session\"]\n Validate -->|Stale| Remove[\"Close & Remove\"]\n Remove --> Create\n```\n\nSource: [src/sessionManager.ts:130-200](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Session Validation\n\nSessions are validated before use by checking page availability:\n\n```typescript\ntry {\n const pages = sessionObj.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n needsReCreation = true;\n}\n```\n\nSource: [src/sessionManager.ts:83-91](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Core Methods\n\n### Creating Sessions\n\n#### `createNewBrowserSession()`\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `newSessionId` | `string` | Yes | Internal tracking ID |\n| `config` | `Config` | Yes | Browserbase configuration |\n| `resumeSessionId` | `string` | No | Browserbase session to resume |\n\n**Process:**\n\n1. Validate API key and project ID exist in config\n2. Create Stagehand instance with optional resume capability\n3. Extract page and Browserbase session ID\n4. Store session in browsers Map\n5. Update active session ID\n\n```typescript\nconst stagehand = await createStagehandInstance(\n config,\n {\n ...(resumeSessionId && { browserbaseSessionID: resumeSessionId }),\n },\n newSessionId,\n);\n```\n\nSource: [src/sessionManager.ts:140-195](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Retrieving Sessions\n\n#### `getSession()`\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `sessionId` | `string` | Required | Session identifier to retrieve |\n| `config` | `Config` | Required | Configuration object |\n| `createIfMissing` | `boolean` | `true` | Auto-create default session if missing |\n\n**Returns:** `BrowserSession | null`\n\n```typescript\nasync getSession(\n sessionId: string,\n config: Config,\n createIfMissing: boolean = true,\n): Promise\n```\n\nSource: [src/sessionManager.ts:240-280](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `ensureDefaultSessionInternal()`\n\nEnsures 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.\n\n```typescript\nif (this.defaultSessionCreationPromise) {\n process.stderr.write(\n `[SessionManager] Default session creation already in progress, waiting...\\n`,\n );\n return await this.defaultSessionCreationPromise;\n}\n```\n\nSource: [src/sessionManager.ts:200-220](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Cleanup Operations\n\n#### `closeBrowserGracefully()`\n\nSafely closes a single session with concurrent cleanup protection:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `session` | `BrowserSession \\| undefined \\| null` | Session to close |\n| `sessionIdToLog` | `string` | ID for logging purposes |\n\n**Features:**\n\n- Tracks sessions being cleaned in `cleaningUpSessions` Set\n- Prevents double-cleanup of the same session\n- Always removes from cleanup tracking in `finally` block\n\n```typescript\nif (this.cleaningUpSessions.has(sessionIdToLog)) {\n process.stderr.write(\n `[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\\n`,\n );\n return;\n}\nthis.cleaningUpSessions.add(sessionIdToLog);\n```\n\nSource: [src/sessionManager.ts:145-180](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `cleanupSession()`\n\nRemoves a session and resets state:\n\n```typescript\nasync cleanupSession(sessionId: string): Promise {\n const session = this.browsers.get(sessionId);\n if (session) {\n await this.closeBrowserGracefully(session, sessionId);\n }\n this.browsers.delete(sessionId);\n \n if (sessionId === this.defaultSessionId) {\n this.defaultBrowserSession = null;\n }\n if (this.activeSessionId === sessionId) {\n this.setActiveSessionId(this.defaultSessionId);\n }\n}\n```\n\nSource: [src/sessionManager.ts:110-145](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n#### `closeAllSessions()`\n\nCloses all managed sessions in parallel:\n\n```typescript\nasync closeAllSessions(): Promise {\n const closePromises: Promise[] = [];\n for (const [id, session] of this.browsers.entries()) {\n closePromises.push(this.closeBrowserGracefully(session, id));\n }\n await Promise.all(closePromises);\n this.browsers.clear();\n this.defaultBrowserSession = null;\n this.setActiveSessionId(this.defaultSessionId);\n}\n```\n\nSource: [src/sessionManager.ts:155-175](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Tools (MCP Interface)\n\nSession management is exposed to MCP clients through tools defined in `src/tools/session.ts` and registered in the TOOLS array:\n\n| Tool | Description |\n|------|-------------|\n| `start` | Creates a new browser session |\n| `end` | Closes an existing session |\n\nSource: [src/tools/index.ts:1-20](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n### Tool Exports\n\n```typescript\nexport const TOOLS = [\n ...sessionTools,\n navigateTool,\n actTool,\n observeTool,\n extractTool,\n];\n\nexport const sessionManagementTools = sessionTools;\n```\n\nSource: [src/tools/index.ts:16-18](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n\n## Integration with Context\n\nThe `Context` class provides the bridge between MCP infrastructure and session management:\n\n```typescript\nexport class Context {\n public readonly config: Config;\n private server: Server;\n private sessionManager: SessionManager;\n\n public get currentSessionId(): string {\n return this.sessionManager.getActiveSessionId();\n }\n\n public async getStagehand(\n sessionId: string = this.currentSessionId,\n ): Promise {\n const session = await this.sessionManager.getSession(\n sessionId,\n this.config,\n );\n if (!session) {\n throw new Error(\"Session not found\");\n }\n return session.stagehand;\n }\n}\n```\n\nSource: [src/context.ts:15-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## Concurrency Handling\n\n### Mutex Pattern for Default Session\n\nThe default session creation uses a mutex pattern to prevent race conditions:\n\n```mermaid\ngraph LR\n A[\"Request 1\"] --> M{\"In Progress?\"}\n B[\"Request 2\"] --> M\n C[\"Request 3\"] --> M\n \n M -->|No| Create[\"Create Session\"]\n M -->|Yes| Wait[\"Wait on Promise\"]\n \n Create --> Store[\"Store Promise\"]\n Store --> Return[\"Return to Request 1\"]\n Wait --> Return\n```\n\n**Implementation:**\n\n```typescript\nprivate defaultSessionCreationPromise: Promise | null = null;\n\nasync ensureDefaultSessionInternal(config: Config): Promise {\n if (this.defaultSessionCreationPromise) {\n return await this.defaultSessionCreationPromise;\n }\n \n this.defaultSessionCreationPromise = (async () => {\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n } finally {\n this.defaultSessionCreationPromise = null;\n }\n })();\n \n return await this.defaultSessionCreationPromise;\n}\n```\n\nSource: [src/sessionManager.ts:200-240](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Cleanup Tracking\n\nThe `cleaningUpSessions` Set prevents concurrent cleanup operations:\n\n```typescript\nprivate cleaningUpSessions: Set = new Set();\n\nasync closeBrowserGracefully(...): Promise {\n if (this.cleaningUpSessions.has(sessionIdToLog)) {\n return; // Skip if already being cleaned\n }\n \n this.cleaningUpSessions.add(sessionIdToLog);\n try {\n // Perform cleanup\n } finally {\n this.cleaningUpSessions.delete(sessionIdToLog);\n }\n}\n```\n\nSource: [src/sessionManager.ts:145-175](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Error Handling\n\n### Session Creation Errors\n\nErrors during session creation trigger automatic retry:\n\n```typescript\ntry {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n} catch (creationError) {\n process.stderr.write(`[SessionManager] Initial attempt failed...\\n`);\n \n // Retry once\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n return this.defaultBrowserSession;\n } catch (retryError) {\n throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);\n }\n} finally {\n this.defaultSessionCreationPromise = null;\n}\n```\n\nSource: [src/sessionManager.ts:225-260](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Graceful Degradation\n\nThe system logs warnings and continues operation on non-fatal errors:\n\n```typescript\n} catch (closeError) {\n process.stderr.write(\n `[SessionManager] WARN - Error closing Stagehand for session ${sessionIdToLog}: ${\n closeError instanceof Error\n ? closeError.message\n : String(closeError)\n }\\n`,\n );\n}\n```\n\nSource: [src/sessionManager.ts:160-170](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Session Identification\n\n### ID Generation\n\nDefault session IDs follow a structured format:\n\n```typescript\nconst uniqueId = randomUUID();\nthis.defaultSessionId = `browserbase_session_${contextId || \"default\"}_${Date.now()}_${uniqueId}`;\n```\n\nFormat: `browserbase_session_{contextId}_{timestamp}_{uuid}`\n\nExample: `browserbase_session_default_1699123456789_a1b2c3d4-e5f6-7890-abcd-ef1234567890`\n\nSource: [src/sessionManager.ts:66-70](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### Active Session Management\n\nThe active session can be changed but only to existing sessions (or the default):\n\n```typescript\nsetActiveSessionId(id: string): void {\n if (this.browsers.has(id)) {\n this.activeSessionId = id;\n } else if (id === this.defaultSessionId) {\n this.activeSessionId = id; // Allow even if not created yet\n } else {\n process.stderr.write(`[SessionManager] WARN - Set active session failed for non-existent ID: ${id}\\n`);\n }\n}\n```\n\nSource: [src/sessionManager.ts:75-90](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## Summary\n\nThe Session Management system provides a robust foundation for browser automation within the MCP server:\n\n- **Isolation**: Each session maintains independent browser state via Stagehand\n- **Reliability**: Automatic validation, recreation, and retry mechanisms\n- **Concurrency Safety**: Mutex patterns and cleanup tracking prevent race conditions\n- **Resource Management**: Graceful cleanup ensures proper resource disposal\n- **Integration**: Seamless connection through the Context layer to MCP tools\n\n---\n\n\n\n## Configuration Options\n\n### Related Pages\n\nRelated topics: [Model Configuration](#model-configuration), [Quick Start Guide](#quickstart)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/config.test.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n \n\n# Configuration Options\n\nThe 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.\n\n## Overview\n\nThe 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.\n\nThe configuration system is built on three pillars:\n\n- **Zod Schema Validation**: All configuration options are validated using Zod schemas defined in `src/index.ts`\n- **Environment Variable Support**: Sensitive values and deployment-specific settings can be injected via environment variables\n- **Command-Line Arguments**: Runtime behavior can be modified through CLI flags defined in `src/program.ts`\n\nSource: [src/config.ts:1-15]()\n\n## Configuration Schema\n\nThe root configuration interface `Config` defines the complete structure of valid configuration options. All options are type-safe and validated at server startup.\n\n### Core Configuration Interface\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies: boolean;\n server: {\n port?: number;\n host?: string;\n };\n viewPort: {\n browserWidth: number;\n browserHeight: number;\n };\n modelName: string;\n modelApiKey?: string;\n verified?: boolean;\n keepAlive?: boolean;\n}\n```\n\nSource: [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n### Zod Schema Definition\n\nThe configuration schema provides runtime validation and documentation for MCP clients:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n proxies: z.boolean().optional().describe(\"Whether or not to use Browserbase proxies\"),\n verified: z.boolean().optional().describe(\"Use Browserbase Verified Identity\"),\n advancedStealth: z.boolean().optional().describe(\"Deprecated alias for verified\"),\n keepAlive: z.boolean().optional().describe(\"Whether or not to keep the Browserbase session alive\"),\n // Additional fields...\n});\n```\n\nSource: [src/index.ts:18-45]()\n\n## Command-Line Options\n\nThe server accepts the following command-line flags when run directly via Node.js or the CLI entry point:\n\n| Flag | Type | Description | Default |\n|------|------|-------------|---------|\n| `--browserbaseApiKey` | string | The Browserbase API Key to authenticate with the Browserbase service | _(none)_ |\n| `--browserbaseProjectId` | string | The Browserbase Project ID for organizing sessions and billing | _(none)_ |\n| `--proxies` | boolean | Enable Browserbase proxy rotation for requests | `false` |\n| `--verified` | boolean | Use Browserbase Verified Identity (requires Scale Plan) | `false` |\n| `--advancedStealth` | boolean | Deprecated alias for `--verified` | `false` |\n| `--contextId` | string | Browserbase context identifier for session continuity | _(none)_ |\n| `--persist` | boolean | Persist session data beyond server restart | `false` |\n| `--port` | number | HTTP server port for streamable transport | _(none)_ |\n| `--host` | string | HTTP server host binding address | _(none)_ |\n| `--browserWidth` | number | Viewport width in pixels for browser sessions | `1024` |\n| `--browserHeight` | number | Viewport height in pixels for browser sessions | `768` |\n| `--modelName` | string | AI model identifier for Stagehand operations | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey` | string | API key for the configured AI model | _(none)_ |\n| `--keepAlive` | boolean | Maintain browser session after request completion | `false` |\n| `--experimental` | boolean | Enable experimental features | `false` |\n\nSource: [src/program.ts:28-46]()\n\nSource: [src/config.ts:7-22]()\n\n## Environment Variables\n\nThe configuration system automatically loads values from environment variables when CLI options are not provided:\n\n| Environment Variable | Config Property | Description |\n|---------------------|-----------------|-------------|\n| `BROWSERBASE_API_KEY` | `browserbaseApiKey` | Authentication token for Browserbase API |\n| `BROWSERBASE_PROJECT_ID` | `browserbaseProjectId` | Project identifier for Browserbase resources |\n| `GEMINI_API_KEY` | `modelApiKey` | API key for Gemini models (fallback) |\n| `GOOGLE_API_KEY` | `modelApiKey` | Alternative API key for Google models |\n\nEnvironment variables are loaded using the `dotenv` package at application startup:\n\n```typescript\nimport * as dotenv from \"dotenv\";\ndotenv.config();\n```\n\nSource: [src/index.ts:1-2]()\n\n### Environment Variable Resolution Priority\n\nWhen resolving the model API key, the system checks environment variables in the following order:\n\n1. `process.env.GEMINI_API_KEY`\n2. `process.env.GOOGLE_API_KEY`\n\n```typescript\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\nSource: [src/config.ts:50-53]()\n\n## Default Configuration Values\n\nThe server ships with sensible defaults for all optional parameters:\n\n| Property | Default Value | Description |\n|----------|---------------|-------------|\n| `proxies` | `false` | Proxy rotation disabled by default |\n| `server.port` | `undefined` | Auto-assigned by the operating system |\n| `server.host` | `undefined` | Bind to all available interfaces |\n| `viewPort.browserWidth` | `1024` | Standard desktop viewport width |\n| `viewPort.browserHeight` | `768` | Standard desktop viewport height |\n| `modelName` | `google/gemini-2.5-flash-lite` | Default model matches hosted MCP service |\n\nSource: [src/config.ts:25-34]()\n\n## Configuration Resolution Flow\n\nThe configuration passes through several transformation stages before being used by the server:\n\n```mermaid\ngraph TD\n A[Default Config] --> B[CLI Options]\n B --> C[configFromCLIOptions]\n C --> D[mergeConfig]\n D --> E[normalizeVerifiedConfig]\n E --> F[normalizeVerifiedConfig with Env Vars]\n F --> G[Internal Config]\n G --> H[Server Initialization]\n \n I[process.env.GEMINI_API_KEY] -.-> F\n J[process.env.GOOGLE_API_KEY] -.-> F\n```\n\n### Configuration Processing Pipeline\n\nThe `resolveConfig` function orchestrates the complete configuration workflow:\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n // Order: Defaults < File Config < CLI Overrides\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n\n // --- Add Browserbase Env Vars ---\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n // ...\n}\n```\n\nSource: [src/config.ts:37-56]()\n\n## Verified Identity Configuration\n\nThe `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.\n\n### Legacy Alias Handling\n\n```typescript\nit(\"maps the legacy CLI advancedStealth alias to verified\", async () => {\n const config = await configFromCLIOptions({ advancedStealth: true });\n expect(config.verified).toBe(true);\n});\n\nit(\"prefers verified when both verified and advancedStealth are set\", () => {\n const config = normalizeVerifiedConfig({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n verified: false,\n advancedStealth: true,\n });\n expect(config.verified).toBe(false);\n});\n```\n\nSource: [src/config.test.ts:7-22]()\n\n## CLI Options Type Definition\n\nThe `CLIOptions` type represents all valid command-line input options:\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\nSource: [src/config.ts:7-22]()\n\n## Required Configuration\n\nCertain configuration values must be provided for the server to function:\n\n### Mandatory Fields\n\n| Field | Requirement | Error if Missing |\n|-------|-------------|------------------|\n| `browserbaseApiKey` | Required | `\"browserbaseApiKey is required\"` |\n| `browserbaseProjectId` | Required | `\"browserbaseProjectId is required\"` |\n\nThe validation is performed in `src/index.ts` before the MCP server is initialized:\n\n```typescript\nif (!config.browserbaseApiKey) {\n throw new Error(\"browserbaseApiKey is required\");\n}\nif (!config.browserbaseProjectId) {\n throw new Error(\"browserbaseProjectId is required\");\n}\n```\n\nSource: [src/index.ts:93-99]()\n\n## Tool Capability Configuration\n\nConfiguration options can be tagged with capability levels for feature gating:\n\n```typescript\nexport type ToolCapability = \"core\" | string;\n```\n\nThis allows future extension of the configuration system to support optional tool sets based on subscription tier or feature flags.\n\nSource: [src/config.ts:3-5]()\n\n## Configuration in MCP Client Setup\n\nWhen integrating with MCP clients, configuration is passed through the `env` property of the server definition:\n\n### NPM Package Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Direct Node.js Installation\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Docker Container Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Transport Configuration\n\nThe server supports multiple transport mechanisms, each with its own configuration requirements:\n\n| Transport | Configuration Method | Notes |\n|-----------|---------------------|-------|\n| STDIO | Environment variables or CLI flags | Default for local installations |\n| Streamable HTTP | Port/host CLI flags | Configured via `--port` and `--host` |\n| SHTTP (Hosted) | URL configuration only | Uses hosted service at `mcp.browserbase.com` |\n\nSource: [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n---\n\n\n\n## Model Configuration\n\n### Related Pages\n\nRelated topics: [Configuration Options](#configuration-options), [System Architecture Overview](#architecture-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# Model Configuration\n\nThe 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.\n\n## Overview\n\nThe MCP server leverages [Stagehand](https://www.stagehand.dev) 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.\n\n| Property | Type | Default Value | Description |\n|----------|------|---------------|-------------|\n| `modelName` | string | `google/gemini-2.5-flash-lite` | The model identifier for Stagehand |\n| `modelApiKey` | string | Environment variable | API key for the custom model provider |\n\nSource: [src/config.ts:26-27](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L26-L27)\n\n## Configuration Architecture\n\n### Configuration Resolution Order\n\nThe system employs a layered configuration strategy where settings are merged in a specific priority order:\n\n```mermaid\ngraph TD\n A[Default Configuration] --> B[File Configuration]\n B --> C[CLI Options]\n C --> D[Environment Variables]\n D --> E[Final Merged Config]\n \n F[modelApiKey Override] --> |\"if not set\"| D\n G[GEMINI_API_KEY or GOOGLE_API_KEY] --> F\n```\n\nThe resolution order from lowest to highest priority is:\n\n1. **Default Configuration** - Hardcoded defaults in `src/config.ts`\n2. **CLI Options** - Command-line arguments provided at runtime\n3. **Environment Variables** - Used as fallback for `modelApiKey`\n\nSource: [src/config.ts:29-43](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L29-L43)\n\n### Configuration Schema\n\nThe server uses Zod for runtime validation of the configuration object:\n\n```typescript\nexport const configSchema = z.object({\n browserbaseApiKey: z.string().describe(\"The Browserbase API Key to use\"),\n browserbaseProjectId: z.string().describe(\"The Browserbase Project ID to use\"),\n modelName: z.string().optional(),\n modelApiKey: z.string().optional(),\n // ... other options\n});\n```\n\nSource: [src/index.ts:28-49](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts#L28-L49)\n\n## CLI Options\n\n### Available Flags\n\n| Flag | Type | Description | Required |\n|------|------|-------------|----------|\n| `--modelName ` | string | Model identifier (e.g., `anthropic/claude-sonnet-4.5`) | No |\n| `--modelApiKey ` | string | API key for the custom model provider | Conditional |\n\nThe `--modelName` and `--modelApiKey` flags are exposed through Commander.js:\n\n```typescript\n.option(\"--modelName \", \"The model to use for Stagehand\")\n.option(\"--modelApiKey \", \"API key for the model provider\")\n```\n\nSource: [src/program.ts:45-46](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts#L45-L46)\n\n### CLI Options Type Definition\n\n```typescript\nexport type CLIOptions = {\n modelName?: string;\n modelApiKey?: string;\n // ... other options\n};\n```\n\nSource: [src/config.ts:13-24](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L13-L24)\n\n## Environment Variable Handling\n\nThe `modelApiKey` can be automatically populated from environment variables when not explicitly provided:\n\n```typescript\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\nThis allows users to set credentials once in their environment rather than repeatedly on the command line.\n\nSource: [src/config.ts:38-41](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L38-L41)\n\n## Supported Models\n\nThe server uses Stagehand for browser automation, and the model must be supported by Stagehand. Refer to the [Stagehand documentation](https://docs.stagehand.dev/examples/custom_llms#supported-llms) for the complete list of supported models.\n\n### Default Model\n\nThe default model is `google/gemini-2.5-flash-lite`, chosen for its performance in web interaction tasks:\n\n```typescript\nconst defaultConfig: Config = {\n // ...\n modelName: \"google/gemini-2.5-flash-lite\", // Default Model — matches hosted MCP\n};\n```\n\nSource: [src/config.ts:26](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts#L26)\n\n### Popular Alternative Models\n\n| Provider | Model Identifier | Use Case |\n|----------|------------------|----------|\n| Anthropic | `anthropic/claude-sonnet-4.5` | High-quality reasoning |\n| Anthropic | `anthropic/claude-opus-4` | Maximum capability |\n| OpenAI | `openai/gpt-4o` | Vision and speed |\n| Google | `google/gemini-2.0-flash` | Balanced performance |\n\n## Configuration Examples\n\n### Using Default Model\n\nWhen using the default Gemini model, provide the API key via environment variable:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Using Custom Model\n\nTo use a custom model like Claude:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### NPM Installation with Custom Model\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"sk-ant-...\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-...\",\n \"BROWSERBASE_PROJECT_ID\": \"...\"\n }\n }\n }\n}\n```\n\n### Docker Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"MODEL_NAME\",\n \"-e\",\n \"MODEL_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"MODEL_NAME\": \"anthropic/claude-sonnet-4.5\",\n \"MODEL_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n## Requirements for Custom Models\n\nWhen 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.\n\n| Requirement | Reason |\n|-------------|--------|\n| Valid `--modelName` | Must be supported by Stagehand |\n| Valid `--modelApiKey` | Required for authentication with external providers |\n| Sufficient quota | Check your LLM provider's rate limits |\n\n## Configuration Flow Diagram\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as Command Line\n participant Config as Config Module\n participant Stagehand\n \n User->>CLI: Start server with options\n CLI->>Config: Parse CLI options\n Config->>Config: Load default config\n Config->>Config: Merge CLI options\n Config->>Config: Check env vars for modelApiKey\n Config->>Config: Return resolved config\n CLI->>Stagehand: Initialize with config\n Stagehand->>User: Server ready with model\n```\n\n## Related Dependencies\n\nThe model configuration system depends on the following key packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@browserbasehq/stagehand` | ^3.3.0 | Browser automation with AI |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP server framework |\n| `commander` | ^14.0.0 | CLI argument parsing |\n| `zod` | ^3.25.67 | Schema validation |\n\nSource: [package.json:40-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json#L40-L45)\n\n## Best Practices\n\n1. **Environment Variables for Secrets**: Store API keys in environment variables rather than command-line arguments to avoid exposing sensitive data in process listings.\n\n2. **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.\n\n3. **Validation**: The Zod schema validates configuration at runtime, ensuring required fields are present before the server starts.\n\n4. **Compatibility**: Always verify your chosen model is supported by Stagehand before configuration.\n\n---\n\n\n\n## Deployment Methods\n\n### Related Pages\n\nRelated topics: [Quick Start Guide](#quickstart), [Transport Layer](#transport-layer)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n \n\n# Deployment Methods\n\nThe 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.\n\n## Overview\n\nThe MCP server can be deployed in three primary ways:\n\n1. **Direct Installation** - Clone the repository and run locally with Node.js\n2. **Docker Container** - Run the server in an isolated container\n3. **NPM Package** - Use the pre-built `@browserbasehq/mcp` package via npx\n\nAdditionally, the server supports two transport mechanisms for communication:\n\n- **STDIO** - Standard input/output communication for local CLI integrations\n- **SHTTP** - HTTP-based transport for networked or hosted deployments\n\nSource: [README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n A[Client MCP Config] --> B{Transport Type}\n B -->|STDIO| C[Direct Installation / NPM]\n B -->|SHTTP| D[Hosted Server / Self-Hosted HTTP]\n \n C --> E[Node.js Runtime]\n D --> F[mcp.browserbase.com]\n D --> G[Self-Hosted Docker/Node]\n \n E --> H[Browserbase Cloud]\n F --> H\n G --> H\n \n H --> I[Stagehand]\n I --> J[Browser Automation]\n```\n\n## Method 1: Direct Installation\n\nDirect installation provides full control over the server and is suitable for development environments or custom deployments.\n\n### Prerequisites\n\n- Node.js 18+ (LTS recommended)\n- npm or pnpm package manager\n- Valid Browserbase API credentials\n\n### Installation Steps\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\nSource: [README.md:1-10](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Project Structure\n\nThe built artifacts are generated in the `dist/` directory with the following structure:\n\n| File | Purpose |\n|------|---------|\n| `cli.js` | Main CLI entry point |\n| `index.js` | Module entry point for programmatic use |\n| `config.d.ts` | TypeScript type definitions |\n\nSource: [package.json:11-17](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n### Available Build Scripts\n\n| Script | Command | Description |\n|--------|---------|-------------|\n| `build` | `tsc && shx chmod +x dist/*.js` | Compiles TypeScript and sets executable permissions |\n| `watch` | `tsc --watch` | Watch mode for development |\n| `test` | `vitest run` | Run test suite |\n| `inspector` | `npx @modelcontextprotocol/inspector` | MCP protocol inspector |\n\nSource: [package.json:22-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Method 2: Docker Deployment\n\nDocker deployment provides an isolated, reproducible environment that includes all dependencies.\n\n### Building the Docker Image\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n### Running the Container\n\nThe Docker image exposes the server with environment variable support for configuration:\n\n```bash\ndocker run --rm -i \\\n -e BROWSERBASE_API_KEY \\\n -e BROWSERBASE_PROJECT_ID \\\n -e GEMINI_API_KEY \\\n mcp-browserbase\n```\n\nSource: [README.md:10-25](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Docker Configuration Benefits\n\n- **Isolation**: Runs independently of host system dependencies\n- **Consistency**: Identical behavior across different environments\n- **Security**: Sandboxed execution environment\n- **Portability**: Easy to deploy to any container runtime\n\n## Method 3: NPM Package (npx)\n\nThe pre-built package provides the fastest path to deployment without manual cloning or building.\n\n### Quick Start\n\n```bash\nnpx @browserbasehq/mcp\n```\n\n### Configuration in MCP Client\n\nAdd the following to your MCP configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:60-75](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@browserbasehq/mcp` |\n| Version | 3.0.0 |\n| License | Apache-2.0 |\n| Entry Point | `./cli.js` |\n| Module Entry | `./src/index.ts` |\n\nSource: [package.json:1-12](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Transport Methods\n\nThe MCP server supports two transport protocols for client communication.\n\n### STDIO Transport\n\nSTDIO is the default transport when no HTTP configuration is specified. It uses standard input/output streams for communication.\n\n```mermaid\ngraph LR\n A[MCP Client] -->|stdio| B[Browserbase MCP Server]\n B -->|stdout| A\n```\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:60-72](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### SHTTP Transport\n\nSHTTP (Secure HTTP) enables networked deployments and is the recommended transport for hosted deployments.\n\n#### Hosted Server (Recommended)\n\nUse the Browserbase hosted MCP server for the simplest setup:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### Self-Hosted HTTP\n\nFor self-hosted HTTP transport, specify port and host in the CLI:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSource: [README.md:30-55](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n#### Remote Access via mcp-remote\n\nClients without native SHTTP support can use the `mcp-remote` tool:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n## Command-Line Options\n\nThe server accepts the following CLI flags for configuration:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--proxies` | Enable Browserbase proxies for the session | `false` |\n| `--verified` | Enable Browserbase Verified Identity (Scale Plan only) | `false` |\n| `--advancedStealth` | Deprecated alias for `--verified` | `false` |\n| `--keepAlive` | Enable Browserbase Keep Alive Session | `false` |\n| `--contextId ` | Specify a Browserbase Context ID to use | _(none)_ |\n| `--persist` | Whether to persist the Browserbase context | `true` |\n| `--port ` | Port for HTTP/SHTTP transport | _(stdio)_ |\n| `--host ` | Host to bind server to | `localhost` |\n| `--browserWidth ` | Browser viewport width | `1024` |\n| `--browserHeight ` | Browser viewport height | `768` |\n| `--modelName ` | Stagehand model name | `google/gemini-2.5-flash-lite` |\n| `--modelApiKey ` | API key for custom model provider | _(none)_ |\n| `--experimental` | Enable experimental features | `false` |\n\nSource: [README.md:85-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### CLI Option Definitions\n\nThe CLI options are parsed using the `commander` package:\n\n```typescript\nprogram\n .option(\"--browserbaseApiKey \", \"The Browserbase API Key to use\")\n .option(\"--browserbaseProjectId \", \"The Browserbase Project ID to use\")\n .option(\"--proxies\", \"Use Browserbase proxies.\")\n .option(\"--verified\", \"Use Browserbase Verified Identity. Only available to Browserbase Scale Plan users.\")\n .option(\"--advancedStealth\", \"Deprecated alias for --verified.\")\n .option(\"--contextId \", \"Browserbase Context ID to use\");\n```\n\nSource: [src/program.ts:30-40](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n\n## Environment Variables\n\n### Required Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `BROWSERBASE_API_KEY` | Your Browserbase API key | Yes |\n| `BROWSERBASE_PROJECT_ID` | Your Browserbase Project ID | Yes |\n| `GEMINI_API_KEY` | Gemini API key for default model | Yes (unless using hosted) |\n\n### Optional Variables\n\n| Variable | Description | Auto-resolved From |\n|----------|-------------|-------------------|\n| `modelApiKey` | API key for custom models | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |\n\n### Configuration Resolution Order\n\nThe server resolves configuration using this precedence (highest to lowest):\n\n1. CLI arguments\n2. Environment variables\n3. Default values\n\n```mermaid\ngraph TD\n A[Config Resolution] --> B[Load Defaults]\n B --> C[Merge Env Variables]\n C --> D[Apply CLI Overrides]\n D --> E[Validate Configuration]\n E --> F[Start Server]\n```\n\nSource: [src/config.ts:40-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Configuration Type Definition\n\n```typescript\ninterface Config {\n browserbaseApiKey: string;\n browserbaseProjectId: string;\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n keepAlive?: boolean;\n context?: {\n contextId?: string;\n persist?: boolean;\n };\n server?: {\n port?: number;\n host?: string;\n };\n viewPort?: {\n browserWidth?: number;\n browserHeight?: number;\n };\n modelName?: string;\n modelApiKey?: string;\n experimental?: boolean;\n}\n```\n\nSource: [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Model Configuration\n\nThe server defaults to Google's Gemini 2.5 Flash Lite model but supports custom models.\n\n### Default Configuration\n\n| Setting | Value |\n|---------|-------|\n| Default Model | `google/gemini-2.5-flash-lite` |\n| API Key Source | `GEMINI_API_KEY` or `GOOGLE_API_KEY` env var |\n\n### Custom Model Setup\n\nTo use a custom model, provide both `--modelName` and `--modelApiKey`:\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4.5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\n> **Note**: The model must be supported by Stagehand. See [Stagehand Custom LLM docs](https://docs.stagehand.dev/examples/custom_llms#supported-llms).\n\nSource: [README.md:110-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## Deployment Decision Matrix\n\n| Use Case | Recommended Method | Transport |\n|----------|-------------------|-----------|\n| Quick testing | NPM (npx) | STDIO |\n| Development | Direct Installation | STDIO |\n| Production (self-hosted) | Docker | SHTTP |\n| Production (managed) | Hosted Server | SHTTP |\n| CI/CD pipelines | Docker | STDIO |\n| Claude Code integration | NPM | STDIO |\n\n## Security Considerations\n\n### Host Binding\n\n| Host Value | Behavior | Security Level |\n|------------|----------|----------------|\n| `localhost` | Local connections only | High |\n| `0.0.0.0` | All network interfaces | Low - requires firewall |\n\n> **Warning**: Use `0.0.0.0` only when you need external access and have proper security measures in place.\n\n### API Key Management\n\n- Store credentials in environment variables, never in config files committed to version control\n- Use secret management solutions in production environments\n- Rotate API keys regularly\n\nSource: [config.d.ts:25-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n## Quick Reference\n\n### Minimal STDIO Setup\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### Full-Featured Docker Setup\n\n```bash\ndocker run --rm -i \\\n -e BROWSERBASE_API_KEY \\\n -e BROWSERBASE_PROJECT_ID \\\n -e GEMINI_API_KEY \\\n mcp-browserbase \\\n --proxies \\\n --verified \\\n --browserWidth 1920 \\\n --browserHeight 1080\n```\n\n## Related Documentation\n\n- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n- [Stagehand Documentation](https://docs.stagehand.dev/)\n\n---\n\n\n\n## Testing\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [vitest.config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/vitest.config.ts)\n- [src/config.test.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [eslint.config.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/eslint.config.js)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n \n\n# Testing\n\n## Overview\n\nThe 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.\n\n## Testing Stack\n\n### Core Testing Framework\n\nThe 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.\n\n### Supporting Tools\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| `vitest` | ^4.1.2 | Primary testing framework |\n| `mcpvals` | ^0.4.0 | MCP protocol validation |\n| `tsx` | ^4.20.3 | TypeScript execution for evals |\n| `typescript` | ^5.6.2 | TypeScript compiler and type checking |\n| `eslint` | ^9.29.0 | Code linting |\n| `prettier` | ^3.6.1 | Code formatting |\n\nSource: [package.json:39-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Test Configuration\n\n### Vitest Configuration\n\nThe Vitest configuration defines the scope and boundaries of test discovery within the project:\n\n```typescript\nimport { defineConfig } from \"vitest/config\";\n\nexport default defineConfig({\n test: {\n include: [\"src/**/*.test.ts\", \"tests/**/*.test.ts\"],\n exclude: [\"node_modules\", \"dist\"],\n },\n});\n```\n\n**Configuration Parameters:**\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| `include` | `[\"src/**/*.test.ts\", \"tests/**/*.test.ts\"]` | Glob patterns for test file discovery |\n| `exclude` | `[\"node_modules\", \"dist\"]` | Directories excluded from test discovery |\n\nSource: [vitest.config.ts:1-9](https://github.com/browserbase/mcp-server-browserbase/blob/main/vitest.config.ts)\n\n### Test Execution\n\nTests are executed through npm/pnpm scripts defined in package.json:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `test` | `vitest run` | Run tests once without watch mode |\n| `prepare` | `husky && pnpm build` | Git hook setup and build (runs on `npm install`) |\n| `pre-commit` | `pnpm lint-staged` | Pre-commit hooks for linting and formatting |\n\nSource: [package.json:32-34](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Test Structure\n\n### Directory Organization\n\nTests follow a co-located pattern within the source directory:\n\n```mermaid\ngraph TD\n A[Project Root] --> B[src/]\n A --> C[tests/]\n B --> D[config.test.ts]\n B --> E[index.ts]\n B --> F[config.ts]\n \n D -. tests .-> F\n D -. validates .-> E\n```\n\n### Configuration Tests\n\nThe `config.test.ts` file contains comprehensive tests for configuration handling, verifying the behavior of configuration normalization and schema validation:\n\n#### Test Suite: Verified Config Compatibility\n\nThe test suite validates configuration alias handling and priority resolution between different configuration sources:\n\n**Test 1: Legacy CLI AdvancedStealth Alias Mapping**\n\n```typescript\nit(\"maps the legacy CLI advancedStealth alias to verified\", async () => {\n const config = await configFromCLIOptions({ advancedStealth: true });\n expect(config.verified).toBe(true);\n});\n```\n\nThis test verifies that the deprecated `advancedStealth` option correctly maps to the `verified` configuration property, maintaining backward compatibility.\n\nSource: [src/config.test.ts:9-13](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n**Test 2: Verified/AdvancedStealth Priority Resolution**\n\n```typescript\nit(\"prefers verified when both verified and advancedStealth are set\", () => {\n const config = normalizeVerifiedConfig({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n verified: false,\n advancedStealth: true,\n });\n expect(config.verified).toBe(false);\n});\n```\n\nThis 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.\n\nSource: [src/config.test.ts:15-23](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n**Test 3: Smithery Config Schema Compatibility**\n\n```typescript\nit(\"accepts advancedStealth in the Smithery config schema\", () => {\n const config = configSchema.parse({\n browserbaseApiKey: \"test-key\",\n browserbaseProjectId: \"test-project\",\n advancedStealth: true,\n });\n expect(config.advancedStealth).toBe(true);\n});\n```\n\nThis test validates compatibility with external configuration schemas like Smithery, ensuring the `advancedStealth` property is correctly parsed and preserved.\n\nSource: [src/config.test.ts:25-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.test.ts)\n\n## Code Quality Integration\n\n### ESLint Configuration\n\nThe project uses ESLint with TypeScript support to maintain code quality across test files and source code:\n\n```javascript\nexport default defineConfig([\n {\n files: [\"**/*.{js,mjs,cjs,ts,mts,cts}\"],\n plugins: { js },\n extends: [\"js/recommended\"],\n ignores: [\"dist/**/*\"],\n },\n {\n files: [\"**/*.{js,mjs,cjs,ts,mts,cts}\"],\n languageOptions: { globals: { ...globals.browser, ...globals.node } },\n ignores: [\"dist/**/*\"],\n },\n ...tseslint.configs.recommended,\n {\n files: [\"src/types/**/*.ts\", \"src/mcp/**/*.ts\"],\n rules: {\n \"@typescript-eslint/no-explicit-any\": \"off\",\n \"@typescript-eslint/no-unused-vars\": \"off\",\n \"@typescript-eslint/ban-ts-comment\": \"off\",\n },\n },\n {\n ignores: [\"dist/**/*\", \"node_modules/**/*\"],\n },\n]);\n```\n\n**ESLint Rule Configuration:**\n\n| Rule | Applied To | Setting | Rationale |\n|------|------------|---------|-----------|\n| `no-explicit-any` | `src/types/**`, `src/mcp/**` | Off | Type definitions may require explicit any |\n| `no-unused-vars` | `src/types/**`, `src/mcp/**` | Off | Allow exported types with potential future use |\n| `ban-ts-comment` | `src/types/**`, `src/mcp/**` | Off | Allow TypeScript directive comments |\n\nSource: [eslint.config.js:1-34](https://github.com/browserbase/mcp-server-browserbase/blob/main/eslint.config.js)\n\n### Lint-Staged Configuration\n\nThe project uses lint-staged to run automated linting and formatting on staged files before commits:\n\n```json\n\"lint-staged\": {\n \"*.{js,jsx,ts,tsx,json,css,scss,md}\": [\n \"prettier --write .\",\n \"eslint --fix\"\n ]\n}\n```\n\nThis configuration ensures all staged files are formatted with Prettier and fixed with ESLint before being committed, maintaining consistent code style.\n\nSource: [package.json:26-31](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Configuration Resolution Flow\n\nThe testing infrastructure validates the configuration resolution process, which follows a cascading merge strategy:\n\n```mermaid\ngraph LR\n A[Default Config] --> B[CLI Options]\n B --> C[mergeConfig]\n C --> D[normalizeVerifiedConfig]\n D --> E[Final Config]\n \n F[Env: GEMINI_API_KEY] -.-> E\n F -.-> G[modelApiKey]\n G --> E\n```\n\n**Configuration Priority Order (Lowest to Highest):**\n\n1. Default configuration values\n2. Environment variables\n3. CLI options\n4. Explicit verified flag (overrides deprecated advancedStealth)\n\nSource: [src/config.ts:18-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Default Configuration Values\n\nThe test suite validates against the following default configuration structure:\n\n| Property | Default Value | Source |\n|----------|---------------|--------|\n| `browserbaseApiKey` | `process.env.BROWSERBASE_API_KEY` | Environment |\n| `browserbaseProjectId` | `process.env.BROWSERBASE_PROJECT_ID` | Environment |\n| `proxies` | `false` | Hardcoded |\n| `server.port` | `undefined` | None |\n| `server.host` | `undefined` | None |\n| `viewPort.browserWidth` | `1024` | Hardcoded |\n| `viewPort.browserHeight` | `768` | Hardcoded |\n| `modelName` | `google/gemini-2.5-flash-lite` | Hardcoded |\n\nSource: [src/config.ts:18-28](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## Test Coverage Areas\n\n### Currently Covered\n\n| Area | File | Status |\n|------|------|--------|\n| Configuration alias mapping | `src/config.test.ts` | Implemented |\n| Verified config priority | `src/config.test.ts` | Implemented |\n| Schema validation | `src/config.test.ts` | Implemented |\n\n### Evals System\n\nThe project includes an evaluation system for testing MCP server behavior:\n\n```bash\n\"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\"\n```\n\nThe evals system runs multiple evaluation configurations to validate the MCP server's functionality against expected behavior patterns.\n\nSource: [package.json:30](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## Running Tests\n\n### Standard Test Execution\n\n```bash\n# Run all tests once\npnpm test\n\n# Run tests in watch mode during development\nnpx vitest\n```\n\n### With Evals\n\n```bash\n# Run comprehensive evaluation suite\npnpm evals\n```\n\n### Code Quality Checks\n\n```bash\n# Run ESLint\npnpm lint\n\n# Format code with Prettier\npnpm format\n\n# Run all pre-commit checks\npnpm pre-commit\n```\n\n## Best Practices Demonstrated\n\nThe testing infrastructure demonstrates several best practices:\n\n1. **Co-located tests**: Test files are placed alongside source files with `.test.ts` suffix\n2. **Descriptive test names**: Tests use clear, descriptive names explaining the scenario being validated\n3. **Configuration validation**: Zod schemas are tested for backward compatibility\n4. **Code quality automation**: Pre-commit hooks ensure consistent formatting and linting\n5. **Multiple test configurations**: The eval system provides tiered testing with basic, minimal, and full configurations\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: browserbase/mcp-server-browserbase\n\nSummary: Found 11 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives.\n\n## 1. security_permissions · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. identity · 仓库名和安装名不一致\n\n- Severity: medium\n- Evidence strength: runtime_trace\n- Finding: 仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- User impact: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Suggested check: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Reproduction command: `npx @browserbasehq/mcp`\n- Guardrail action: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. installation · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. security_permissions · 来源证据：Add MCPpedia security badge to README\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. security_permissions · 来源证据：Add policy enforcement for cloud browser sessions\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: browserbase/mcp-server-browserbase\n\nSummary: Found 11 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives.\n\n## 1. security_permissions · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. identity · 仓库名和安装名不一致\n\n- Severity: medium\n- Evidence strength: runtime_trace\n- Finding: 仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- User impact: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Suggested check: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Reproduction command: `npx @browserbasehq/mcp`\n- Guardrail action: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. installation · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. security_permissions · 来源证据：Add MCPpedia security badge to README\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. security_permissions · 来源证据：Add policy enforcement for cloud browser sessions\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-server-browserbase - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for browserbase/mcp-server-browserbase.\n\nProject:\n- Name: mcp-server-browserbase\n- Repository: https://github.com/browserbase/mcp-server-browserbase\n- Summary: Allow LLMs to control a browser with Browserbase and Stagehand\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Allow LLMs to control a browser with Browserbase and Stagehand\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Allow LLMs to control a browser with Browserbase and Stagehand\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. architecture-overview: System Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-tools: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n5. session-management: Session Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/browserbase/mcp-server-browserbase\n- https://github.com/browserbase/mcp-server-browserbase#readme\n- README.md\n- package.json\n- src/index.ts\n- cli.js\n- Dockerfile\n- src/server.ts\n- src/program.ts\n- src/types/types.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: browserbase/mcp-server-browserbase\n\n## Official Entry Points\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @browserbasehq/mcp\n```\n\nSource：https://github.com/browserbase/mcp-server-browserbase#readme\n\n## Sources\n\n- repo: https://github.com/browserbase/mcp-server-browserbase\n- docs: https://github.com/browserbase/mcp-server-browserbase#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_c54342a96f3141908b3d3ae8102ada57"
}