Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:141-229 (handler)

  Handler function that closes the current Browserbase session. It retrieves the session using getSession, closes the Stagehand instance if available, cleans up the session, resets the context's current session ID to default, and returns appropriate success or info messages. Includes error handling.

  async function handleCloseSession(context: Context): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      // Store the current session ID before it's potentially changed.
      const previousSessionId = context.currentSessionId;
      let stagehandClosedSuccessfully = false;
      let stagehandCloseErrorMessage = "";
  
      // Step 1: Attempt to get the session and close Stagehand
      let browserbaseSessionId: string | undefined;
      try {
        const session = await getSession(
          previousSessionId,
          context.config,
          false,
        );
  
        if (session && session.stagehand) {
          // Store the actual Browserbase session ID for the replay URL
          browserbaseSessionId = session.sessionId;
  
          process.stderr.write(
            `[tool.closeSession] Attempting to close Stagehand for session: ${previousSessionId || "default"} (Browserbase ID: ${browserbaseSessionId})`,
          );
  
          // Use Stagehand's close method which handles browser cleanup properly
          await session.stagehand.close();
          stagehandClosedSuccessfully = true;
  
          process.stderr.write(
            `[tool.closeSession] Stagehand and browser connection for session (${previousSessionId}) closed successfully.`,
          );
  
          // Clean up the session from tracking
          await cleanupSession(previousSessionId);
  
          if (browserbaseSessionId) {
            process.stderr.write(
              `[tool.closeSession] View session replay at https://www.browserbase.com/sessions/${browserbaseSessionId}`,
            );
          }
        } else {
          process.stderr.write(
            `[tool.closeSession] No Stagehand instance found for session: ${previousSessionId || "default/unknown"}`,
          );
        }
      } catch (error: unknown) {
        stagehandCloseErrorMessage =
          error instanceof Error ? error.message : String(error);
        process.stderr.write(
          `[tool.closeSession] Error retrieving or closing Stagehand (session ID was ${previousSessionId || "default/unknown"}): ${stagehandCloseErrorMessage}`,
        );
      }
  
      // Step 2: Always reset the context's current session ID to default
      const oldContextSessionId = context.currentSessionId;
      context.currentSessionId = defaultSessionId;
      process.stderr.write(
        `[tool.closeSession] Session context reset to default. Previous context session ID was ${oldContextSessionId || "default/unknown"}.`,
      );
  
      // Step 3: Determine the result message
      if (stagehandCloseErrorMessage && !stagehandClosedSuccessfully) {
        throw new Error(
          `Failed to close the Stagehand session (session ID in context was ${previousSessionId || "default/unknown"}). Error: ${stagehandCloseErrorMessage}. Session context has been reset to default.`,
        );
      }
  
      if (stagehandClosedSuccessfully) {
        let successMessage = `Browserbase session (${previousSessionId || "default"}) closed successfully via Stagehand. 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 Stagehand instance was found
      let infoMessage =
        "No active Stagehand session found to close. Session context has been reset to default.";
      if (previousSessionId && previousSessionId !== defaultSessionId) {
        infoMessage = `No active Stagehand 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:132-139 (schema)

  Zod input schema (empty object, no parameters required) and tool schema definition including name, description, and input schema reference.

  const CloseSessionInputSchema = z.object({});
  
  const closeSessionSchema: ToolSchema<typeof CloseSessionInputSchema> = {
    name: "browserbase_session_close",
    description:
      "Closes the current Browserbase session by properly shutting down the Stagehand instance, which handles browser cleanup and terminates the session recording.",
    inputSchema: CloseSessionInputSchema,
  };

• src/tools/session.ts:231-237 (registration)

  Tool object registration combining the schema and handler function. Exported as part of the default export array for inclusion in the MCP tools registry.

  const closeSessionTool: Tool<typeof CloseSessionInputSchema> = {
    capability: "core",
    schema: closeSessionSchema,
    handle: handleCloseSession,
  };
  
  export default [createSessionTool, closeSessionTool];