Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:30-125 (handler)

  Main handler function that orchestrates session creation or reuse via SessionManager, initializes Browserbase SDK for debug URLs, and returns session view and debugger links.
  async function handleCreateSession( context: Context, params: CreateSessionInput, ): Promise<ToolResult> { const action = async (): Promise<ToolActionResult> => { try { const sessionManager = context.getSessionManager(); const config = context.config; // Get config from context let targetSessionId: string; // Session ID Strategy: Use raw sessionId for both internal tracking and Browserbase operations // Default session uses generated ID with timestamp/UUID, user sessions use provided ID as-is if (params.sessionId) { targetSessionId = params.sessionId; process.stderr.write( `[tool.createSession] Attempting to create/assign session with specified ID: ${targetSessionId}\n`, ); } else { targetSessionId = sessionManager.getDefaultSessionId(); } let session: BrowserSession; const defaultSessionId = sessionManager.getDefaultSessionId(); if (targetSessionId === defaultSessionId) { session = await sessionManager.ensureDefaultSessionInternal(config); } else { // When user provides a sessionId, we want to resume that Browserbase session // Note: targetSessionId is used for internal tracking in SessionManager // while params.sessionId is the Browserbase session ID to resume session = await sessionManager.createNewBrowserSession( targetSessionId, // Internal session ID for tracking config, params.sessionId, // Browserbase session ID to resume ); } if ( !session || !session.page || !session.sessionId || !session.stagehand ) { throw new Error( `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}`, ); } // Note: No need to set context.currentSessionId - SessionManager handles this // and context.currentSessionId is a getter that delegates to SessionManager const bb = new Browserbase({ apiKey: config.browserbaseApiKey, }); const browserbaseSessionId = session.stagehand.browserbaseSessionId; if (!browserbaseSessionId) { throw new Error( "Browserbase session ID not found in Stagehand instance", ); } const debugUrl = (await bb.sessions.debug(browserbaseSessionId)) .debuggerFullscreenUrl; return { content: [ { type: "text", text: `Browserbase Live Session View URL: https://www.browserbase.com/sessions/${browserbaseSessionId}`, }, { type: "text", text: `Browserbase Live Debugger URL: ${debugUrl}`, }, createUIResource({ uri: "ui://analytics-dashboard/main", content: { type: "externalUrl", iframeUrl: debugUrl }, encoding: "text", }) as unknown as TextContent, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); process.stderr.write( `[tool.createSession] Action failed: ${errorMessage}\n`, ); // 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:10-27 (schema)

  Zod schema definition for the tool's input parameters and the ToolSchema object defining name, description, and inputSchema.
  // --- Tool: Create Session --- const CreateSessionInputSchema = z.object({ // Keep sessionId optional 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 Browserbase browser session and set it as active.", inputSchema: CreateSessionInputSchema, };
• src/index.ts:168-198 (registration)

  Registration loop that iterates over all tools from src/tools/index.ts TOOLS array and registers each with the MCP server using server.tool(), wrapping the tool handler via context.run.
  const tools: MCPToolsArray = [...TOOLS]; // Register each tool with the Smithery server tools.forEach((tool) => { if (tool.schema.inputSchema instanceof z.ZodObject) { server.tool( tool.schema.name, tool.schema.description, tool.schema.inputSchema.shape, async (params: z.infer<typeof tool.schema.inputSchema>) => { try { const result = await context.run(tool, params); return result; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); process.stderr.write( `[Smithery Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`, ); throw new Error( `Failed to run tool '${tool.schema.name}': ${errorMessage}`, ); } }, ); } else { console.warn( `Tool "${tool.schema.name}" has an input schema that is not a ZodObject. Schema type: ${tool.schema.inputSchema.constructor.name}`, ); } });
• src/tools/index.ts:21-30 (registration)

  Aggregation of all tools into the TOOLS export array, importing and including sessionTools which contains browserbase_session_create.
  export const TOOLS = [ ...sessionTools, navigateTool, actTool, extractTool, observeTool, screenshotTool, getUrlTool, agentTool, ];
• src/sessionManager.ts:12-72 (helper)

  Helper function to create and initialize Stagehand instance used by SessionManager for browser sessions, configuring Browserbase parameters.
  export const createStagehandInstance = async ( config: Config, params: CreateSessionParams = {}, sessionId: string, ): Promise<Stagehand> => { const apiKey = params.apiKey || config.browserbaseApiKey; const projectId = params.projectId || config.browserbaseProjectId; if (!apiKey || !projectId) { throw new Error("Browserbase API Key and Project ID are required"); } const modelName = params.modelName || config.modelName || "gemini-2.0-flash"; const modelApiKey = config.modelApiKey || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY; const stagehand = new Stagehand({ env: "BROWSERBASE", apiKey, projectId, model: modelApiKey ? { apiKey: modelApiKey, modelName: modelName, } : modelName, ...(params.browserbaseSessionID && { browserbaseSessionID: params.browserbaseSessionID, }), experimental: config.experimental ?? false, browserbaseSessionCreateParams: { projectId, proxies: config.proxies, keepAlive: config.keepAlive ?? false, browserSettings: { viewport: { width: config.viewPort?.browserWidth ?? 1288, height: config.viewPort?.browserHeight ?? 711, }, context: config.context?.contextId ? { id: config.context?.contextId, persist: config.context?.persist ?? true, } : undefined, advancedStealth: config.advancedStealth ?? undefined, }, userMetadata: { mcp: "true", }, }, logger: (logLine) => { console.error(`Stagehand[${sessionId}]: ${logLine.message}`); }, }); await stagehand.init(); return stagehand; };