multi_browserbase_stagehand_session_create

Instructions

Implementation Reference

• src/tools/multiSession.ts:104-146 (handler)

  The handler function that executes the tool logic: creates a new session using stagehandStore.create, retrieves the Browserbase session ID and debug URL, and returns a success message with session details.

  handle: async (
    context: Context,
    { name, browserbaseSessionID },
  ): Promise<ToolResult> => {
    try {
      const params: CreateSessionParams = {
        browserbaseSessionID,
        meta: name ? { name } : undefined,
      };
  
      const session = await stagehandStore.create(context.config, params);
  
      const bbSessionId = session.metadata?.bbSessionId;
      if (!bbSessionId) {
        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(bbSessionId))
        .debuggerFullscreenUrl;
  
      return {
        action: async () => ({
          content: [
            {
              type: "text",
              text: `Created session ${session.id}${name ? ` (${name})` : ""}\nBrowserbase session: ${bbSessionId}\nBrowserbase Live Session View URL: https://www.browserbase.com/sessions/${bbSessionId}\nBrowserbase Live Debugger URL: ${debugUrl}`,
            },
          ],
        }),
        waitForNetwork: false,
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      throw new Error(
        `Failed to create browser session: ${errorMessage}. Please check your Browserbase credentials and try again.`,
      );
    }
  },

• src/tools/multiSession.ts:85-102 (schema)

  The input schema and description for the tool, defining optional 'name' and 'browserbaseSessionID' parameters.

  schema: {
    name: "multi_browserbase_stagehand_session_create",
    description:
      "Create parallel browser session for multi-session workflows. Use this when you need multiple browser instances running simultaneously: parallel data scraping, concurrent automation, A/B testing, multiple user accounts, cross-site operations, batch processing, or any task requiring more than one browser. Creates an isolated browser session with independent cookies, authentication, and state. Always pair with session-specific tools (those ending with '_session'). Perfect for scaling automation tasks that require multiple browsers working in parallel.",
    inputSchema: z.object({
      name: z
        .string()
        .optional()
        .describe(
          "Highly recommended: Descriptive name for tracking multiple sessions (e.g. 'amazon-scraper', 'user-login-flow', 'checkout-test-1'). Makes debugging and session management much easier!",
        ),
      browserbaseSessionID: z
        .string()
        .optional()
        .describe(
          "Resume an existing Browserbase session by providing its session ID. Use this to continue work in a previously created browser session that may have been paused or disconnected.",
        ),
    }),

• src/tools/index.ts:42-52 (registration)

  The tool is included in the TOOLS array via multiSessionTools, which is used for MCP server registration.

  // Export all tools as array
  export const TOOLS = [
    ...multiSessionTools,
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
  ];

• src/index.ts:196-226 (registration)

  Final MCP server registration: all tools from TOOLS are registered using server.tool() with a wrapper handler that calls context.run(tool, params). This makes the tool available via MCP.

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