Browserbase MCP Server

Instructions

Implementation Reference

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

  The handler function that executes the tool: retrieves stagehand and active page, navigates to the URL, fetches Browserbase debug URL using SDK, returns content with navigation confirmation and session links.

  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)

  Tool schema definition including name, description, and Zod input schema for the URL parameter.

  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/navigate.ts:74-80 (registration)

  Tool object registration combining schema, capability, and handler function, exported for use in tools index.

  const navigateTool: Tool<typeof NavigateInputSchema> = {
    capability: "core",
    schema: navigateSchema,
    handle: handleNavigate,
  };
  
  export default navigateTool;

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

  Aggregates all tools including navigateTool into TOOLS array for server registration.

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

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

  Imports TOOLS and registers each tool with the MCP server using server.tool(), providing a wrapper handler that invokes 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}`,
      );
    }
  });