Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:144-218 (handler)

  The primary handler function that executes the tool's logic: retrieves the current session ID, attempts to clean up the session using SessionManager, handles cases where no session exists, logs details, and returns appropriate text content responses.
  async function handleCloseSession(context: Context): Promise<ToolResult> { const action = async (): Promise<ToolActionResult> => { // Store the current session ID before cleanup const previousSessionId = context.currentSessionId; let cleanupSuccessful = false; let cleanupErrorMessage = ""; // Step 1: Get session info before cleanup let browserbaseSessionId: string | undefined; const sessionManager = context.getSessionManager(); try { const session = await sessionManager.getSession( previousSessionId, context.config, false, ); if (session && session.stagehand) { // Store the actual Browserbase session ID for the replay URL browserbaseSessionId = session.sessionId; // cleanupSession handles both closing Stagehand and cleanup (idempotent) await sessionManager.cleanupSession(previousSessionId); cleanupSuccessful = true; } else { process.stderr.write( `[tool.closeSession] No session found for ID: ${previousSessionId || "default/unknown"}\n`, ); } } catch (error: unknown) { cleanupErrorMessage = error instanceof Error ? error.message : String(error); process.stderr.write( `[tool.closeSession] Error cleaning up session (ID was ${previousSessionId || "default/unknown"}): ${cleanupErrorMessage}\n`, ); } // Step 2: SessionManager automatically resets to default on cleanup // Context.currentSessionId getter will reflect the new active session const oldContextSessionId = previousSessionId; process.stderr.write( `[tool.closeSession] Session context reset to default. Previous context session ID was ${oldContextSessionId || "default/unknown"}.\n`, ); // Step 3: Determine the result message const defaultSessionId = sessionManager.getDefaultSessionId(); if (cleanupErrorMessage && !cleanupSuccessful) { throw new Error( `Failed to cleanup session (session ID was ${previousSessionId || "default/unknown"}). Error: ${cleanupErrorMessage}. Session context has been reset to default.`, ); } if (cleanupSuccessful) { let successMessage = `Browserbase session (${previousSessionId || "default"}) closed successfully. Context reset to default.`; if (browserbaseSessionId && previousSessionId !== defaultSessionId) { successMessage += ` View replay at https://www.browserbase.com/sessions/${browserbaseSessionId}`; } return { content: [{ type: "text", text: successMessage }] }; } // No session was found let infoMessage = "No active session found to close. Session context has been reset to default."; if (previousSessionId && previousSessionId !== defaultSessionId) { infoMessage = `No active session found for session ID '${previousSessionId}'. The context has been reset to default.`; } return { content: [{ type: "text", text: infoMessage }] }; }; return { action: action, waitForNetwork: false, }; }
• src/tools/session.ts:135-142 (schema)

  Defines the Zod input schema (empty, no parameters required) and the tool schema with name and description for the browserbase_session_close tool.
  const CloseSessionInputSchema = z.object({}); const closeSessionSchema: ToolSchema<typeof CloseSessionInputSchema> = { name: "browserbase_session_close", description: "Close the current Browserbase session and reset the active context.", inputSchema: CloseSessionInputSchema, };
• src/tools/index.ts:21-30 (registration)

  Registers the session tools (including browserbase_session_close from sessionTools) into the central TOOLS array, likely used by the MCP server to expose available tools.
  export const TOOLS = [ ...sessionTools, navigateTool, actTool, extractTool, observeTool, screenshotTool, getUrlTool, agentTool, ];
• src/tools/session.ts:220-224 (registration)

  Assembles the complete tool object by combining the schema, handler function, and capability for browserbase_session_close.
  const closeSessionTool: Tool<typeof CloseSessionInputSchema> = { capability: "core", schema: closeSessionSchema, handle: handleCloseSession, };
• src/sessionManager.ts:428-450 (helper)

  Supporting helper method in SessionManager called by the tool handler to perform the actual session cleanup and closure.
  async cleanupSession(sessionId: string): Promise<void> { process.stderr.write( `[SessionManager] Cleaning up session: ${sessionId}\n`, ); // Get the session to close it gracefully const session = this.browsers.get(sessionId); if (session) { await this.closeBrowserGracefully(session, sessionId); } // Remove from browsers map this.browsers.delete(sessionId); // Clear default session reference if this was the default if (sessionId === this.defaultSessionId && this.defaultBrowserSession) { this.defaultBrowserSession = null; } // Reset active session to default if this was the active one if (this.activeSessionId === sessionId) { process.stderr.write( `[SessionManager] Cleaned up active session ${sessionId}, resetting to default.\n`,