browserbase_session_create
Create or reuse a single cloud browser session with Stagehand initialization for web automation tasks, configuring proxies, viewport, cookies, and stealth settings.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | No | Optional session ID to use/reuse. If not provided or invalid, a new session is created. |
Implementation Reference
- src/tools/session.ts:36-105 (handler)The handleCreateSession function implements the core logic of the 'browserbase_session_create' tool. It creates or reuses a Browserbase session using SessionManager functions, updates the context, and returns the session URL.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 { session = await createNewBrowserSession(targetSessionId, config); } if (!session || !session.browser || !session.page || !session.sessionId) { throw new Error( `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}` ); } context.currentSessionId = targetSessionId; process.stderr.write( `[tool.connected] Successfully connected to Browserbase session. Internal ID: ${targetSessionId}, Actual ID: ${session.sessionId}` ); process.stderr.write(`[SessionManager] Browserbase Live Debugger URL: https://www.browserbase.com/sessions/${session.sessionId}`); return { content: [ { type: "text", text: `https://www.browserbase.com/sessions/${session.sessionId}`, }, ], }; } catch (error: any) { process.stderr.write( `[tool.createSession] Action failed: ${ error.message || String(error) }` ); // Re-throw to be caught by Context.run's error handling for actions throw new Error( `Failed to create Browserbase session: ${ error.message || String(error) }` ); } }; // Return the ToolResult structure expected by Context.run return { action: action, captureSnapshot: false, code: [], waitForNetwork: false, }; }
- src/tools/session.ts:27-32 (schema)The ToolSchema definition for 'browserbase_session_create', including name, description, and reference to the input schema (defined above). The input schema is z.object({ sessionId: z.string().optional()... }) on lines 16-24.const createSessionSchema: ToolSchema<typeof CreateSessionInputSchema> = { name: "browserbase_session_create", description: "Create or reuse a cloud browser session using Browserbase. Updates the active session.", inputSchema: CreateSessionInputSchema, };
- src/tools/session.ts:108-112 (registration)The creation of the createSessionTool object, which bundles the schema and handler. This tool is exported in an array at line 239 and imported into src/index.ts for server registration.const createSessionTool: Tool<typeof CreateSessionInputSchema> = { capability: "core", // Add capability schema: createSessionSchema, handle: handleCreateSession, };
- src/index.ts:73-106 (registration)In src/index.ts, the session tools are included via '...session' in the tools array (line 79), and then registered on the MCP server via the forEach loop using server.tool() with the tool's schema and a wrapper around context.run(tool, params).const tools: Tool<any>[] = [ ...common, ...snapshot, ...keyboard, ...getText, ...navigate, ...session, ...contextTools, ]; // 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/context.ts:409-410 (helper)Special handling in Context.run() skips session validation for 'browserbase_session_create' since this tool is responsible for creating the session.if (toolName !== "browserbase_session_create") { try {