Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/multiSession.ts:83-147 (handler)

  Complete tool definition: registers the tool 'multi_browserbase_stagehand_session_create' with input schema, description, and handler logic that creates a Browserbase session via stagehandStore, fetches debug URL, and returns session details.

  export const createSessionTool = defineTool({
    capability: "create_session",
    schema: {
      name: "multi_browserbase_stagehand_session_create",
      description:
        "Create parallel browser session for multi-session workflows. Use this when you need multiple browser instances running simultaneously: parallel data scraping, concurrent automation, A/B testing, multiple user accounts, cross-site operations, batch processing, or any task requiring more than one browser. Creates an isolated browser session with independent cookies, authentication, and state. Always pair with session-specific tools (those ending with '_session'). Perfect for scaling automation tasks that require multiple browsers working in parallel.",
      inputSchema: z.object({
        name: z
          .string()
          .optional()
          .describe(
            "Highly recommended: Descriptive name for tracking multiple sessions (e.g. 'amazon-scraper', 'user-login-flow', 'checkout-test-1'). Makes debugging and session management much easier!",
          ),
        browserbaseSessionID: z
          .string()
          .optional()
          .describe(
            "Resume an existing Browserbase session by providing its session ID. Use this to continue work in a previously created browser session that may have been paused or disconnected.",
          ),
      }),
    },
    handle: async (
      context: Context,
      { name, browserbaseSessionID },
    ): Promise<ToolResult> => {
      try {
        const params: CreateSessionParams = {
          browserbaseSessionID,
          meta: name ? { name } : undefined,
        };
  
        const session = await stagehandStore.create(context.config, params);
  
        const bbSessionId = session.metadata?.bbSessionId;
        if (!bbSessionId) {
          throw new Error("No Browserbase session ID available");
        }
  
        // Get the debug URL using Browserbase SDK
        const bb = new Browserbase({
          apiKey: context.config.browserbaseApiKey,
        });
        const debugUrl = (await bb.sessions.debug(bbSessionId))
          .debuggerFullscreenUrl;
  
        return {
          action: async () => ({
            content: [
              {
                type: "text",
                text: `Created session ${session.id}${name ? ` (${name})` : ""}\nBrowserbase session: ${bbSessionId}\nBrowserbase Live Session View URL: https://www.browserbase.com/sessions/${bbSessionId}\nBrowserbase Live Debugger URL: ${debugUrl}`,
              },
            ],
          }),
          waitForNetwork: false,
        };
      } catch (error) {
        const errorMessage =
          error instanceof Error ? error.message : String(error);
        throw new Error(
          `Failed to create browser session: ${errorMessage}. Please check your Browserbase credentials and try again.`,
        );
      }
    },
  });

• src/tools/index.ts:8-52 (registration)

  Imports and registers the multi-session tools, including 'multi_browserbase_stagehand_session_create', into the main TOOLS array used by the MCP server.

  import {
    createSessionTool,
    listSessionsTool,
    closeSessionTool,
    navigateWithSessionTool,
    actWithSessionTool,
    extractWithSessionTool,
    observeWithSessionTool,
    getUrlWithSessionTool,
    getAllUrlsWithSessionTool,
  } from "./multiSession.js";
  
  // Export individual tools
  export { default as navigateTool } from "./navigate.js";
  export { default as actTool } from "./act.js";
  export { default as extractTool } from "./extract.js";
  export { default as observeTool } from "./observe.js";
  export { default as screenshotTool } from "./screenshot.js";
  export { default as sessionTools } from "./session.js";
  export { default as getUrlTool } from "./url.js";
  
  // Multi-session tools array
  export const multiSessionTools = [
    createSessionTool,
    listSessionsTool,
    closeSessionTool,
    navigateWithSessionTool,
    actWithSessionTool,
    extractWithSessionTool,
    observeWithSessionTool,
    getUrlWithSessionTool,
    getAllUrlsWithSessionTool,
  ];
  
  // Export all tools as array
  export const TOOLS = [
    ...multiSessionTools,
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
  ];

• src/stagehandStore.ts:50-120 (helper)

  stagehandStore.create - the underlying helper that actually initializes the browser session and Stagehand instance called by the tool handler.

            : undefined,
          advancedStealth: config.advancedStealth ?? undefined,
        },
        userMetadata: {
          mcp: "true",
        },
      },
      logger: (logLine) => {
        console.error(`Stagehand[${sessionId}]: ${logLine.message}`);
      },
    });
  
    await stagehand.init();
    return stagehand;
  };
  
  /**
   * Create a new Stagehand session
   */
  export const create = async (
    config: Config,
    params: CreateSessionParams = {},
  ): Promise<StagehandSession> => {
    // Global ID, must be 100% Unique
    const id = randomUUID() + "_" + config.browserbaseProjectId;
  
    process.stderr.write(`[StagehandStore] Creating new session ${id}...\n`);
  
    const stagehand = await createStagehandInstance(config, params, id);
  
    const page = stagehand.page as unknown as Page;
    const browser = page.context().browser();
  
    if (!browser) {
      throw new Error("Failed to get browser from Stagehand page context");
    }
  
    const session: StagehandSession = {
      id,
      stagehand,
      page,
      browser,
      created: Date.now(),
      metadata: {
        ...params.meta,
        bbSessionId: stagehand.browserbaseSessionID,
      },
    };
  
    store.set(id, session);
  
    process.stderr.write(
      `[StagehandStore] Session created: ${id} (BB: ${stagehand.browserbaseSessionID})\n`,
    );
    process.stderr.write(
      `[StagehandStore] Live debugger: https://www.browserbase.com/sessions/${stagehand.browserbaseSessionID}\n`,
    );
  
    // Set up disconnect handler
    const disconnectHandler = () => {
      process.stderr.write(`[StagehandStore] Session disconnected: ${id}\n`);
      store.delete(id);
    };
  
    browser.on("disconnected", disconnectHandler);
  
    // Store the handler for cleanup
    session.metadata = {
      ...session.metadata,
      disconnectHandler,
    };