Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/multiSession.ts:216-235 (handler)

  The core handler function that retrieves the session by ID, removes it from the stagehandStore, and returns a confirmation message via ToolResult.

  handle: async (_context: Context, { sessionId }): Promise<ToolResult> => {
    const session = stagehandStore.get(sessionId);
    if (!session) {
      throw new Error(`Session ${sessionId} not found`);
    }
  
    await stagehandStore.remove(sessionId);
  
    return {
      action: async () => ({
        content: [
          {
            type: "text",
            text: `Closed session ${sessionId}`,
          },
        ],
      }),
      waitForNetwork: false,
    };
  },

• src/tools/multiSession.ts:204-215 (schema)

  The schema defining the tool's name, description, and input validation schema which requires a 'sessionId' string.

  schema: {
    name: "multi_browserbase_stagehand_session_close",
    description:
      "Cleanup parallel session for multi-session workflows. Properly terminates a browser session, ends the Browserbase session, and frees cloud resources. Always use this when finished with a session to avoid resource waste and billing charges. Critical for responsible multi-session automation - each unclosed session continues consuming resources!",
    inputSchema: z.object({
      sessionId: z
        .string()
        .describe(
          "Exact session ID to close (get from 'multi_browserbase_stagehand_session_list'). Double-check this ID - once closed, the session cannot be recovered!",
        ),
    }),
  },

• src/tools/multiSession.ts:202-236 (registration)

  The complete tool definition and registration using defineTool, exporting closeSessionTool which is later included in the main TOOLS array for MCP server registration.

  export const closeSessionTool = defineTool({
    capability: "close_session",
    schema: {
      name: "multi_browserbase_stagehand_session_close",
      description:
        "Cleanup parallel session for multi-session workflows. Properly terminates a browser session, ends the Browserbase session, and frees cloud resources. Always use this when finished with a session to avoid resource waste and billing charges. Critical for responsible multi-session automation - each unclosed session continues consuming resources!",
      inputSchema: z.object({
        sessionId: z
          .string()
          .describe(
            "Exact session ID to close (get from 'multi_browserbase_stagehand_session_list'). Double-check this ID - once closed, the session cannot be recovered!",
          ),
      }),
    },
    handle: async (_context: Context, { sessionId }): Promise<ToolResult> => {
      const session = stagehandStore.get(sessionId);
      if (!session) {
        throw new Error(`Session ${sessionId} not found`);
      }
  
      await stagehandStore.remove(sessionId);
  
      return {
        action: async () => ({
          content: [
            {
              type: "text",
              text: `Closed session ${sessionId}`,
            },
          ],
        }),
        waitForNetwork: false,
      };
    },
  });

• src/tools/index.ts:26-34 (registration)

  Inclusion of closeSessionTool in the multiSessionTools array, which is merged into the main TOOLS export used by the MCP server.

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

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

  Generic registration loop in the MCP server initialization that registers all tools from TOOLS array, including this one, by calling server.tool with the tool's schema and a wrapper handler that invokes the tool's original handle via context.run.

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