Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:37-122 (handler)

  The main handler function `handleCreateSession` that executes the tool's logic: creates or reuses a Browserbase session using SessionManager, connects Stagehand, updates context, and returns session view/debug URLs.
  async function handleCreateSession( context: Context, params: CreateSessionInput, ): Promise<ToolResult> { const action = async (): Promise<ToolActionResult> => { try { const config = context.config; // Get config from context let targetSessionId: string; if (params.sessionId) { const projectId = config.browserbaseProjectId || ""; targetSessionId = `${params.sessionId}_${projectId}`; process.stderr.write( `[tool.createSession] Attempting to create/assign session with specified ID: ${targetSessionId}`, ); } else { targetSessionId = defaultSessionId; } let session: BrowserSession; if (targetSessionId === defaultSessionId) { session = await ensureDefaultSessionInternal(config); } else { // When user provides a sessionId, we want to resume that Browserbase session session = await createNewBrowserSession( targetSessionId, config, params.sessionId, ); } if ( !session || !session.browser || !session.page || !session.sessionId || !session.stagehand ) { throw new Error( `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}`, ); } context.currentSessionId = targetSessionId; const bb = new Browserbase({ apiKey: config.browserbaseApiKey, }); const debugUrl = (await bb.sessions.debug(session.sessionId)) .debuggerFullscreenUrl; process.stderr.write( `[tool.connected] Successfully connected to Browserbase session. Internal ID: ${targetSessionId}, Actual ID: ${session.sessionId}`, ); process.stderr.write( `[SessionManager] Browserbase Live Session View URL: https://www.browserbase.com/sessions/${session.sessionId}`, ); process.stderr.write( `[SessionManager] Browserbase Live Debugger URL: ${debugUrl}`, ); return { content: [ { type: "text", text: `Browserbase Live Session View URL: https://www.browserbase.com/sessions/${session.sessionId}\nBrowserbase Live Debugger URL: ${debugUrl}`, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); process.stderr.write( `[tool.createSession] Action failed: ${errorMessage}`, ); // Re-throw to be caught by Context.run's error handling for actions throw new Error(`Failed to create Browserbase session: ${errorMessage}`); } }; // Return the ToolResult structure expected by Context.run return { action: action, waitForNetwork: false, }; }
• src/tools/session.ts:18-34 (schema)

  Zod input schema (CreateSessionInputSchema) and tool schema definition (createSessionSchema) including name, description, and inputSchema for the browserbase_session_create tool.
  const CreateSessionInputSchema = z.object({ // Keep sessionId optional, but clarify its role sessionId: z .string() .optional() .describe( "Optional session ID to use/reuse. If not provided or invalid, a new session is created.", ), }); type CreateSessionInput = z.infer<typeof CreateSessionInputSchema>; const createSessionSchema: ToolSchema<typeof CreateSessionInputSchema> = { name: "browserbase_session_create", description: "Create or reuse a single cloud browser session using Browserbase with fully initialized Stagehand. WARNING: This tool is for SINGLE browser workflows only. If you need multiple browser sessions running simultaneously (parallel scraping, A/B testing, multiple accounts), use 'multi_browserbase_stagehand_session_create' instead. This creates one browser session with all configuration flags (proxies, stealth, viewport, cookies, etc.) and initializes Stagehand to work with that session. Updates the active session.", inputSchema: CreateSessionInputSchema, };
• src/tools/session.ts:125-129 (registration)

  Tool object definition `createSessionTool` that registers the schema and handler for browserbase_session_create, exported as part of sessionTools array.
  const createSessionTool: Tool<typeof CreateSessionInputSchema> = { capability: "core", // Add capability schema: createSessionSchema, handle: handleCreateSession, };
• src/tools/index.ts:37-45 (registration)

  Main TOOLS export array in tools index that includes `...sessionTools` (containing browserbase_session_create), used for MCP server tool registration.
  export const TOOLS = [ ...multiSessionTools, ...sessionTools, navigateTool, actTool, extractTool, observeTool, screenshotTool, ];
• src/types/types.ts:15-23 (schema)

  TypeScript type definition for CreateSessionParams used in session creation, related to browserbase_session_create parameters.
  export type CreateSessionParams = { apiKey?: string; projectId?: string; modelName?: string; modelApiKey?: string; browserbaseSessionID?: string; browserbaseSessionCreateParams?: any; meta?: Record<string, any>; };