Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/multiSession.ts:55-77 (handler)

  Handler for the multi-session navigate tool. Retrieves session by ID from stagehandStore, creates overridden context pointing to the session's resources, and delegates to the base navigate 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/navigate.ts:20-72 (handler)

  Base navigate tool handler invoked by the multi-session wrapper. Performs page.goto(url), retrieves Browserbase session details, and returns navigation confirmation with live view 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/multiSession.ts:239-245 (registration)

  Definition and export of the specific tool 'multi_browserbase_stagehand_navigate_session' by applying the multi-session wrapper factory to the base navigateTool, generating the exact name, schema, and handler.

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

• src/tools/multiSession.ts:34-46 (schema)

  Schema generation for session-aware tools: extends the original tool's input schema by adding a required 'sessionId' field.

  if (originalSchema instanceof z.ZodObject) {
    // If it's a ZodObject, we can spread its shape
    newInputSchema = z.object({
      sessionId: z.string().describe("The session ID to use"),
      ...originalSchema.shape,
    });
  } else {
    // For other schema types, create an intersection
    newInputSchema = z.intersection(
      z.object({ sessionId: z.string().describe("The session ID to use") }),
      originalSchema,
    );
  }

• src/index.ts:188-218 (registration)

  MCP server registration of all tools (including the target tool via TOOLS array) using server.tool() for each tool's name, description, input schema, and a wrapper handler that executes context.run(tool, params).

  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:26-34 (registration)

  Inclusion of navigateWithSessionTool in the multiSessionTools array, which is spread into the main TOOLS export used for MCP registration.

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