Browserbase MCP Server

Instructions

Implementation Reference

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

  The handler function that executes the browserbase_session_close tool. It retrieves the current session, closes the Stagehand instance if available, cleans up the session, resets the context to default session, and provides appropriate success or info messages with replay URLs.

  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)

  Input schema (empty object) and tool schema definition for browserbase_session_close, 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 schema and handler, exported as part of the default array for use in MCP server.

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