Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:30-125 (handler)

  Main handler function that orchestrates session creation or reuse via SessionManager, initializes Browserbase SDK for debug URLs, and returns session view and debugger links.

  async function handleCreateSession(
    context: Context,
    params: CreateSessionInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const sessionManager = context.getSessionManager();
        const config = context.config; // Get config from context
        let targetSessionId: string;
  
        // Session ID Strategy: Use raw sessionId for both internal tracking and Browserbase operations
        // Default session uses generated ID with timestamp/UUID, user sessions use provided ID as-is
        if (params.sessionId) {
          targetSessionId = params.sessionId;
          process.stderr.write(
            `[tool.createSession] Attempting to create/assign session with specified ID: ${targetSessionId}\n`,
          );
        } else {
          targetSessionId = sessionManager.getDefaultSessionId();
        }
  
        let session: BrowserSession;
        const defaultSessionId = sessionManager.getDefaultSessionId();
        if (targetSessionId === defaultSessionId) {
          session = await sessionManager.ensureDefaultSessionInternal(config);
        } else {
          // When user provides a sessionId, we want to resume that Browserbase session
          // Note: targetSessionId is used for internal tracking in SessionManager
          // while params.sessionId is the Browserbase session ID to resume
          session = await sessionManager.createNewBrowserSession(
            targetSessionId, // Internal session ID for tracking
            config,
            params.sessionId, // Browserbase session ID to resume
          );
        }
  
        if (
          !session ||
          !session.page ||
          !session.sessionId ||
          !session.stagehand
        ) {
          throw new Error(
            `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}`,
          );
        }
  
        // Note: No need to set context.currentSessionId - SessionManager handles this
        // and context.currentSessionId is a getter that delegates to SessionManager
        const bb = new Browserbase({
          apiKey: config.browserbaseApiKey,
        });
  
        const browserbaseSessionId = session.stagehand.browserbaseSessionId;
        if (!browserbaseSessionId) {
          throw new Error(
            "Browserbase session ID not found in Stagehand instance",
          );
        }
        const debugUrl = (await bb.sessions.debug(browserbaseSessionId))
          .debuggerFullscreenUrl;
  
        return {
          content: [
            {
              type: "text",
              text: `Browserbase Live Session View URL: https://www.browserbase.com/sessions/${browserbaseSessionId}`,
            },
            {
              type: "text",
              text: `Browserbase Live Debugger URL: ${debugUrl}`,
            },
            createUIResource({
              uri: "ui://analytics-dashboard/main",
              content: { type: "externalUrl", iframeUrl: debugUrl },
              encoding: "text",
            }) as unknown as TextContent,
          ],
        };
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : String(error);
        process.stderr.write(
          `[tool.createSession] Action failed: ${errorMessage}\n`,
        );
        // 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:10-27 (schema)

  Zod schema definition for the tool's input parameters and the ToolSchema object defining name, description, and inputSchema.

  // --- Tool: Create Session ---
  const CreateSessionInputSchema = z.object({
    // Keep sessionId optional
    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 Browserbase browser session and set it as active.",
    inputSchema: CreateSessionInputSchema,
  };

• src/index.ts:168-198 (registration)

  Registration loop that iterates over all tools from src/tools/index.ts TOOLS array and registers each with the MCP server using server.tool(), wrapping the tool handler via context.run.

  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/tools/index.ts:21-30 (registration)

  Aggregation of all tools into the TOOLS export array, importing and including sessionTools which contains browserbase_session_create.

  export const TOOLS = [
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
    agentTool,
  ];

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

  Helper function to create and initialize Stagehand instance used by SessionManager for browser sessions, configuring Browserbase parameters.

  export const createStagehandInstance = async (
    config: Config,
    params: CreateSessionParams = {},
    sessionId: string,
  ): Promise<Stagehand> => {
    const apiKey = params.apiKey || config.browserbaseApiKey;
    const projectId = params.projectId || config.browserbaseProjectId;
  
    if (!apiKey || !projectId) {
      throw new Error("Browserbase API Key and Project ID are required");
    }
  
    const modelName = params.modelName || config.modelName || "gemini-2.0-flash";
    const modelApiKey =
      config.modelApiKey ||
      process.env.GEMINI_API_KEY ||
      process.env.GOOGLE_API_KEY;
  
    const stagehand = new Stagehand({
      env: "BROWSERBASE",
      apiKey,
      projectId,
      model: modelApiKey
        ? {
            apiKey: modelApiKey,
            modelName: modelName,
          }
        : modelName,
      ...(params.browserbaseSessionID && {
        browserbaseSessionID: params.browserbaseSessionID,
      }),
      experimental: config.experimental ?? false,
      browserbaseSessionCreateParams: {
        projectId,
        proxies: config.proxies,
        keepAlive: config.keepAlive ?? false,
        browserSettings: {
          viewport: {
            width: config.viewPort?.browserWidth ?? 1288,
            height: config.viewPort?.browserHeight ?? 711,
          },
          context: config.context?.contextId
            ? {
                id: config.context?.contextId,
                persist: config.context?.persist ?? true,
              }
            : undefined,
          advancedStealth: config.advancedStealth ?? undefined,
        },
        userMetadata: {
          mcp: "true",
        },
      },
      logger: (logLine) => {
        console.error(`Stagehand[${sessionId}]: ${logLine.message}`);
      },
    });
  
    await stagehand.init();
    return stagehand;
  };