browserbase_session_create
Create or reuse a single cloud browser session with pre-configured settings via Browserbase. Ideal for tasks requiring one fully initialized browser session, including proxies, stealth, viewport, and cookies. Updates the active session for streamlined workflows.
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 handler function that executes the core logic of the 'browserbase_session_create' tool: determines target session ID, calls SessionManager functions to create or ensure the session, updates the context's current session, logs details, and returns the Browserbase 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:16-32 (schema)Zod input schema (optional sessionId) and ToolSchema definition for the 'browserbase_session_create' tool, including name, description, and input validation.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 cloud browser session using Browserbase. Updates the active session.", inputSchema: CreateSessionInputSchema, };
- src/tools/session.ts:108-112 (registration)Tool object registration combining the schema and handler for 'browserbase_session_create'.const createSessionTool: Tool<typeof CreateSessionInputSchema> = { capability: "core", // Add capability schema: createSessionSchema, handle: handleCreateSession, };
- src/tools/session.ts:239-239 (registration)Module-level export of the createSessionTool (among others), making it available for registration in the MCP tools list.export default [createSessionTool, closeSessionTool];
- src/tools/session.ts:7-13 (helper)Imports from sessionManager.js providing the underlying Browserbase session creation functions used by the tool handler.import { createNewBrowserSession, defaultSessionId, ensureDefaultSessionInternal, cleanupSession, type BrowserSession, } from "../sessionManager.js";