Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/url.ts:68-121 (handler)

  The handler function that executes the tool logic: lists all active browser sessions using stagehandStore.list(), retrieves each page's URL, and returns a JSON mapping of session IDs to URLs.

  async function handleGetAllUrls(
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    context: Context,
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    params: GetAllUrlsInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const sessions = stagehandStore.list();
  
        if (sessions.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: "No active sessions found",
              },
            ],
          };
        }
  
        // Collect URLs from all sessions
        const sessionUrls: Record<string, string> = {};
  
        for (const session of sessions) {
          try {
            const url = session.page.url();
            sessionUrls[session.id] = url;
          } catch (error) {
            // If we can't get URL for a session, mark it as error
            sessionUrls[session.id] =
              `<error: ${error instanceof Error ? error.message : "unknown"}>`;
          }
        }
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(sessionUrls, null, 2),
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to get session URLs: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/url.ts:61-66 (schema)

  Tool schema defining the name, description, and empty input schema (z.object({})) for the browserbase_stagehand_get_all_urls tool.

  const getAllUrlsSchema: ToolSchema<typeof GetAllUrlsInputSchema> = {
    name: "browserbase_stagehand_get_all_urls",
    description:
      "Gets the current URLs of all active browser sessions. Returns a mapping of session IDs to their current URLs.",
    inputSchema: GetAllUrlsInputSchema,
  };

• src/tools/url.ts:123-127 (registration)

  Tool object definition exporting the schema and handler for registration in the MCP server's tool list.

  export const getAllUrlsTool: Tool<typeof GetAllUrlsInputSchema> = {
    capability: "core",
    schema: getAllUrlsSchema,
    handle: handleGetAllUrls,
  };

• src/stagehandStore.ts:135-137 (helper)

  stagehandStore.list() helper function that returns all active Stagehand sessions, used in the tool handler to iterate over sessions and get their URLs.

  export const list = (): StagehandSession[] => {
    return Array.from(store.values());
  };

• src/index.ts:192-222 (registration)

  Generic registration loop in MCP server creation that registers all tools from TOOLS array (including this one) using server.tool().

  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}`,
      );
    }
  });