Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/multiSession.ts:56-78 (handler)

  Wrapper handler for all multi-session tools. Loads the specific session by ID, creates a session-scoped context, and delegates to the original tool's handler.

  handle: async (
    context: Context,
    params: z.infer<typeof newInputSchema>,
  ): Promise<ToolResult> => {
    const { sessionId, ...originalParams } = params;
  
    // Get the session
    const session = stagehandStore.get(sessionId);
    if (!session) {
      throw new Error(`Session ${sessionId} not found`);
    }
  
    // Create a temporary context that points to the specific session
    const sessionContext = Object.create(context);
    sessionContext.currentSessionId =
      session.metadata?.bbSessionId || sessionId;
    sessionContext.getStagehand = async () => session.stagehand;
    sessionContext.getActivePage = async () => session.page;
    sessionContext.getActiveBrowser = async () => session.browser;
  
    // Call the original tool's handler with the session-specific context
    return originalTool.handle(sessionContext, originalParams);
  },

• src/tools/multiSession.ts:240-246 (registration)

  Registers/exports the specific tool 'multi_browserbase_stagehand_navigate_session' by applying multi-session wrapper to the base navigateTool.

  export const navigateWithSessionTool = createMultiSessionAwareTool(
    navigateTool,
    {
      namePrefix: "multi_",
      nameSuffix: "_session",
    },
  );

• src/tools/navigate.ts:20-72 (handler)

  Core navigation handler delegated to by the wrapper. Navigates the page to the given URL using Puppeteer page.goto and provides Browserbase session/debug URLs.

  async function handleNavigate(
    context: Context,
    params: NavigateInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
        const page = await context.getActivePage();
  
        if (!page) {
          throw new Error("No active page available");
        }
        await page.goto(params.url, { waitUntil: "domcontentloaded" });
  
        const sessionId = stagehand.browserbaseSessionID;
        if (!sessionId) {
          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(sessionId))
          .debuggerFullscreenUrl;
  
        return {
          content: [
            {
              type: "text",
              text: `Navigated to: ${params.url}`,
            },
            {
              type: "text",
              text: `View the live session here: https://www.browserbase.com/sessions/${sessionId}`,
            },
            {
              type: "text",
              text: `Browserbase Live Debugger URL: ${debugUrl}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to navigate: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/navigate.ts:13-18 (schema)

  Base schema for the navigate tool, which is extended by the multi-session wrapper to add sessionId.

  const navigateSchema: ToolSchema<typeof NavigateInputSchema> = {
    name: "browserbase_stagehand_navigate",
    description:
      "Navigate to a URL in the browser. Only use this tool with URLs you're confident will work and stay up to date. Otherwise, use https://google.com as the starting point",
    inputSchema: NavigateInputSchema,
  };

• src/tools/index.ts:30-40 (registration)

  Includes the multi-session navigate tool in the array of multi-session tools, which is then added to the full TOOLS array registered with the MCP server.

  export const multiSessionTools = [
    createSessionTool,
    listSessionsTool,
    closeSessionTool,
    navigateWithSessionTool,
    actWithSessionTool,
    extractWithSessionTool,
    observeWithSessionTool,
    getUrlWithSessionTool,
    getAllUrlsWithSessionTool,
  ];