Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:37-122 (handler)

  The handler function for the 'browserbase_session_create' tool. It determines the target session ID, uses SessionManager to create or ensure the session (calling ensureDefaultSessionInternal or createNewBrowserSession), validates the session, sets the context's current session, fetches the debugger URL, logs details, and returns content with session and debugger URLs.

  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 {
          // When user provides a sessionId, we want to resume that Browserbase session
          session = await createNewBrowserSession(
            targetSessionId,
            config,
            params.sessionId,
          );
        }
  
        if (
          !session ||
          !session.browser ||
          !session.page ||
          !session.sessionId ||
          !session.stagehand
        ) {
          throw new Error(
            `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}`,
          );
        }
  
        context.currentSessionId = targetSessionId;
        const bb = new Browserbase({
          apiKey: config.browserbaseApiKey,
        });
        const debugUrl = (await bb.sessions.debug(session.sessionId))
          .debuggerFullscreenUrl;
        process.stderr.write(
          `[tool.connected] Successfully connected to Browserbase session. Internal ID: ${targetSessionId}, Actual ID: ${session.sessionId}`,
        );
  
        process.stderr.write(
          `[SessionManager] Browserbase Live Session View URL: https://www.browserbase.com/sessions/${session.sessionId}`,
        );
  
        process.stderr.write(
          `[SessionManager] Browserbase Live Debugger URL: ${debugUrl}`,
        );
  
        return {
          content: [
            {
              type: "text",
              text: `Browserbase Live Session View URL: https://www.browserbase.com/sessions/${session.sessionId}\nBrowserbase Live Debugger URL: ${debugUrl}`,
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : String(error);
        process.stderr.write(
          `[tool.createSession] Action failed: ${errorMessage}`,
        );
        // Re-throw to be caught by Context.run's error handling for actions
        throw new Error(`Failed to create Browserbase session: ${errorMessage}`);
      }
    };
  
    // Return the ToolResult structure expected by Context.run
    return {
      action: action,
      waitForNetwork: false,
    };
  }

• src/tools/session.ts:18-34 (schema)

  Zod input schema and tool schema definition for the 'browserbase_session_create' tool, including the optional sessionId parameter.

  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 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.",
    inputSchema: CreateSessionInputSchema,
  };

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

  The tools index file collects all tools including sessionTools (which contains browserbase_session_create) into the TOOLS array exported for registration in the MCP server.

  // Export all tools as array
  export const TOOLS = [
    ...multiSessionTools,
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
  ];

• src/index.ts:196-226 (registration)

  The MCP server registration loop that registers all tools from TOOLS, including 'browserbase_session_create', by calling server.tool with name, description, schema, and a wrapper handler that invokes context.run on the tool.

  const tools: MCPToolsArray = [...TOOLS];
  
  // Register each tool with the Smithery server
  tools.forEach((tool) => {
    if (tool.schema.inputSchema instanceof z.ZodObject) {
      server.tool(
        tool.schema.name,
        tool.schema.description,
        tool.schema.inputSchema.shape,
        async (params: z.infer<typeof tool.schema.inputSchema>) => {
          try {
            const result = await context.run(tool, params);
            return result;
          } catch (error) {
            const errorMessage =
              error instanceof Error ? error.message : String(error);
            process.stderr.write(
              `[Smithery Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`,
            );
            throw new Error(
              `Failed to run tool '${tool.schema.name}': ${errorMessage}`,
            );
          }
        },
      );
    } else {
      console.warn(
        `Tool "${tool.schema.name}" has an input schema that is not a ZodObject. Schema type: ${tool.schema.inputSchema.constructor.name}`,
      );
    }
  });

• src/sessionManager.ts:72-179 (helper)

  Key helper function called by the handler to create a new or resume Browserbase session using Stagehand, which is central to the tool's logic.

  export async function createNewBrowserSession(
    newSessionId: string,
    config: Config,
    resumeSessionId?: string,
  ): Promise<BrowserSession> {
    if (!config.browserbaseApiKey) {
      throw new Error("Browserbase API Key is missing in the configuration.");
    }
    if (!config.browserbaseProjectId) {
      throw new Error("Browserbase Project ID is missing in the configuration.");
    }
  
    try {
      process.stderr.write(
        `[SessionManager] ${resumeSessionId ? "Resuming" : "Creating"} Stagehand session ${newSessionId}...\n`,
      );
  
      // Create and initialize Stagehand instance using shared function
      const stagehand = await createStagehandInstance(
        config,
        {
          ...(resumeSessionId && { browserbaseSessionID: resumeSessionId }),
        },
        newSessionId,
      );
  
      // Get the page and browser from Stagehand
      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 browserbaseSessionId = stagehand.browserbaseSessionID;
  
      process.stderr.write(
        `[SessionManager] Stagehand initialized with Browserbase session: ${browserbaseSessionId}\n`,
      );
      process.stderr.write(
        `[SessionManager] Browserbase Live Debugger URL: https://www.browserbase.com/sessions/${browserbaseSessionId}\n`,
      );
  
      // Set up disconnect handler
      browser.on("disconnected", () => {
        process.stderr.write(`[SessionManager] Disconnected: ${newSessionId}\n`);
        browsers.delete(newSessionId);
        if (defaultBrowserSession && defaultBrowserSession.browser === browser) {
          process.stderr.write(
            `[SessionManager] Disconnected (default): ${newSessionId}\n`,
          );
          defaultBrowserSession = null;
        }
        if (
          activeSessionId === newSessionId &&
          newSessionId !== defaultSessionId
        ) {
          process.stderr.write(
            `[SessionManager] WARN - Active session disconnected, resetting to default: ${newSessionId}\n`,
          );
          setActiveSessionId(defaultSessionId);
        }
      });
  
      // Add cookies to the context if they are provided in the config
      if (
        config.cookies &&
        Array.isArray(config.cookies) &&
        config.cookies.length > 0
      ) {
        await addCookiesToContext(
          page.context() as BrowserContext,
          config.cookies,
        );
      }
  
      const sessionObj: BrowserSession = {
        browser,
        page,
        sessionId: browserbaseSessionId!,
        stagehand,
      };
  
      browsers.set(newSessionId, sessionObj);
  
      if (newSessionId === defaultSessionId) {
        defaultBrowserSession = sessionObj;
      }
  
      setActiveSessionId(newSessionId);
      process.stderr.write(
        `[SessionManager] Session created and active: ${newSessionId}\n`,
      );
  
      return sessionObj;
    } catch (creationError) {
      const errorMessage =
        creationError instanceof Error
          ? creationError.message
          : String(creationError);
      process.stderr.write(
        `[SessionManager] Creating session ${newSessionId} failed: ${errorMessage}\n`,
      );
      throw new Error(
        `Failed to create/connect session ${newSessionId}: ${errorMessage}`,
      );
    }
  }