Browserbase MCP Server

Instructions

Implementation Reference

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

  The main handler function `handleCreateSession` that executes the tool's logic: creates or reuses a Browserbase session using SessionManager, connects Stagehand, updates context, and returns session view/debug 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 (CreateSessionInputSchema) and tool schema definition (createSessionSchema) including name, description, and inputSchema for the browserbase_session_create tool.

  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/session.ts:125-129 (registration)

  Tool object definition `createSessionTool` that registers the schema and handler for browserbase_session_create, exported as part of sessionTools array.

  const createSessionTool: Tool<typeof CreateSessionInputSchema> = {
    capability: "core", // Add capability
    schema: createSessionSchema,
    handle: handleCreateSession,
  };

• src/tools/index.ts:37-45 (registration)

  Main TOOLS export array in tools index that includes `...sessionTools` (containing browserbase_session_create), used for MCP server tool registration.

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

• src/types/types.ts:15-23 (schema)

  TypeScript type definition for CreateSessionParams used in session creation, related to browserbase_session_create parameters.

  export type CreateSessionParams = {
    apiKey?: string;
    projectId?: string;
    modelName?: string;
    modelApiKey?: string;
    browserbaseSessionID?: string;
    browserbaseSessionCreateParams?: any;
    meta?: Record<string, any>;
  };