@browserless.io/mcp 1.6.2 → 1.7.1

package/README.md

@@ -22,18 +22,17 @@ No local install — see [Configuration](#configuration) for per-client snippets
 
 ## Tools
 
-| Tool                       | Description                                                                                                                                                                                                                                                                          |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `browserless_smartscraper` | Scrape any webpage using cascading strategies (HTTP fetch, proxy, headless browser, captcha solving). Returns content in requested formats: `markdown`, `html`, `screenshot`, `pdf`, `links`.                                                                                        |
-| `browserless_search`       | Search the web using Browserless and optionally scrape each result. Supports web, news, and image search with geo-targeting and time filters.                                                                                                                                        |
-| `browserless_map`          | Discover and map all URLs on a website. Crawls via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.                                                                                                   |
-| `browserless_crawl`        | Crawl a website and scrape every discovered page. Supports depth control, path filtering, sitemap strategies, and configurable scrape options. Returns scraped content and metadata for each page.                                                                                   |
-| `browserless_performance`  | Run Lighthouse audits on any URL. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets.                                                                                              |
-| `browserless_function`     | Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a `page` object and optional `context`; return `{ data, type }` to control the payload and Content-Type.                                                                                         |
-| `browserless_download`     | Run custom Puppeteer code and return the file Chrome downloads during execution (e.g. after clicking a download link). The downloaded file is streamed back to the caller.                                                                                                           |
-| `browserless_export`       | Export a webpage via the Browserless `/export` API. Fetches the URL and returns its native content (HTML, PDF, image, etc.) with automatic content-type detection.                                                                                                                   |
-| `browserless_agent`        | Drive a persistent browser session via a ReAct loop: snapshot the page, plan, batch interactions (click, type, scroll, evaluate, etc.), and re-snapshot. Uses ref-based selectors derived from snapshots, supports multi-tab workflows, screenshots, captcha solving, and live URLs. |
-| `browserless_skill`        | Load an on-demand recipe for a non-trivial page mechanic (shadow DOM, cookie consent, modals, captchas, dynamic content, snapshot misses, screenshots, tabs). Companion to `browserless_agent`.                                                                                      |
+| Tool                       | Description                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browserless_smartscraper` | Scrape a single webpage and return its content as markdown or HTML. Handles JavaScript-heavy pages and anti-bot measures automatically. For content across multiple pages, use `browserless_crawl`; to list a site's URLs, use `browserless_map`.                                                                                                                                  |
+| `browserless_search`       | Search the web using Browserless and optionally scrape each result. Supports web, news, and image search with geo-targeting and time filters.                                                                                                                                                                                                                                      |
+| `browserless_map`          | Discover and map all URLs on a website. Scans via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.                                                                                                                                                                                                  |
+| `browserless_crawl`        | Crawl a website and scrape every discovered page. Supports depth control, path filtering, sitemap strategies, and configurable scrape options. Returns scraped content and metadata for each page.                                                                                                                                                                                 |
+| `browserless_performance`  | Run Lighthouse audits on any URL. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets.                                                                                                                                                                                            |
+| `browserless_function`     | Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a `page` object and optional `context`; return `{ data, type }` to control the payload and Content-Type.                                                                                                                                                                                       |
+| `browserless_export`       | Export a webpage via the Browserless `/export` API. Fetches the URL and returns its native content (HTML, PDF, image, etc.) with automatic content-type detection.                                                                                                                                                                                                                 |
+| `browserless_agent`        | Drive a persistent browser session via a ReAct loop: snapshot the page, plan, batch interactions (click, type, scroll, evaluate, etc.), and re-snapshot. Uses ref-based selectors derived from snapshots, supports multi-tab workflows, screenshots, captcha solving, live URLs, and file upload/download (captured downloads auto-surface as handles; bytes never enter context). |
+| `browserless_skill`        | Load an on-demand recipe for a non-trivial page mechanic (shadow DOM, cookie consent, modals, captchas, dynamic content, snapshot misses, screenshots, tabs). Companion to `browserless_agent`.                                                                                                                                                                                    |
 
 ## Skills
 
@@ -103,6 +102,8 @@ The `proxy` object is read once at session creation. To change it, call `close`
 
 The server is hosted at `https://mcp.browserless.io/mcp`. Authenticate via headers (preferred) or a `?token=` query parameter.
 
+Installing via an AI agent? See [install.md](install.md) for agent-readable setup instructions.
+
 **Using headers** (recommended for clients that support them):
 
 ```json

package/build/src/@types/types.d.ts

@@ -6,7 +6,6 @@ import type {
   SmartScraperResponseSchema,
 } from '../tools/smartscraper.js';
 import type { FunctionParamsSchema } from '../tools/function.js';
-import type { DownloadParamsSchema } from '../tools/download.js';
 import type { ExportParamsSchema } from '../tools/export.js';
 import type {
   SearchSourceSchema,
@@ -27,6 +26,7 @@ import type {
   CrawlParamsSchema,
 } from '../tools/crawl.js';
 import type { AgentParamsSchema } from '../tools/agent.js';
+import type { CreateProfileParams } from '../tools/schemas.js';
 import type { ProxyOptionsSchema } from '../lib/agent-client.js';
 
 /* ------------------------------------------------------------------ */
@@ -36,6 +36,13 @@ import type { ProxyOptionsSchema } from '../lib/agent-client.js';
 export interface BrowserlessSession extends Record<string, unknown> {
   token: string;
   apiUrl: string;
+  /**
+   * A pre-created browser session id to ATTACH to (via /chromium/agent?sessionId),
+   * threaded by the caller through the `x-browserless-session-id` header. Used by
+   * the autologin runner, which does POST /profile itself and hands the agent the
+   * resulting id instead of letting the model open a `createProfile` session.
+   */
+  attachSessionId?: string;
 }
 
 export interface SupabaseJwtPayload {
@@ -133,6 +140,7 @@ export interface SnapshotElement {
   focused?: boolean;
   required?: boolean;
   ariaLabel?: string;
+  frameId?: string;
 }
 
 export interface TabInfo {
@@ -142,6 +150,13 @@ export interface TabInfo {
   active: boolean;
 }
 
+// for iframe handling
+export interface FrameInfo {
+  frameId: string;
+  url: string;
+  crossOrigin: boolean;
+}
+
 export interface SnapshotResult {
   url: string;
   title: string;
@@ -150,6 +165,7 @@ export interface SnapshotResult {
   tabs?: TabInfo[];
   activeTargetId?: string | null;
   detectedChallenges?: string[];
+  frames?: FrameInfo[];
 }
 
 export interface ActiveSession {
@@ -161,6 +177,13 @@ export interface ActiveSession {
   readonly token: string;
   readonly proxy?: ProxyOptions;
   readonly profile?: string;
+  // When set, this session was opened in profile-creation mode: the WS is bound
+  // to a creation session from POST /profile rather than a fresh launch. Feeds
+  // the session-cache key (see getSessionKey), so it's readonly.
+  readonly createProfile?: CreateProfileParams;
+  // The creation session id returned by POST /profile. Reconnects attach to it
+  // via /chromium/agent?sessionId rather than launching a new browser.
+  creationSessionId?: string;
   reconnecting?: Promise<WebSocket>;
   skillState: SkillFireState;
   lastUsedAt: number;
@@ -208,7 +231,9 @@ export type SkillId =
   | 'dynamic-content'
   | 'screenshots'
   | 'tabs'
-  | 'autonomous-login';
+  | 'autonomous-login'
+  | 'auth-profile'
+  | 'file-transfers';
 
 export interface DetectContext {
   snapshot?: SnapshotResult;
@@ -269,7 +294,6 @@ export type ScrapeFormat = z.infer<typeof ScrapeFormatSchema>;
 export type SmartScraperParams = z.infer<typeof SmartScraperParamsSchema>;
 export type SmartScraperResponse = z.infer<typeof SmartScraperResponseSchema>;
 export type FunctionParams = z.infer<typeof FunctionParamsSchema>;
-export type DownloadParams = z.infer<typeof DownloadParamsSchema>;
 export type ExportParams = z.infer<typeof ExportParamsSchema>;
 export type ProxyOptions = z.infer<typeof ProxyOptionsSchema>;
 export type SearchSource = z.infer<typeof SearchSourceSchema>;

package/build/src/index.js

@@ -6,7 +6,6 @@ import { OAuthProxy } from 'fastmcp/auth';
 import { getConfig } from './config.js';
 import { registerSmartScraperTool } from './tools/smartscraper.js';
 import { registerFunctionTool } from './tools/function.js';
-import { registerDownloadTool } from './tools/download.js';
 import { registerExportTool } from './tools/export.js';
 import { registerAgentTools } from './tools/agent.js';
 import { registerSearchTool } from './tools/search.js';
@@ -15,10 +14,14 @@ import { registerCrawlTool } from './tools/crawl.js';
 import { registerPerformanceTool } from './tools/performance.js';
 import { registerApiDocsResource } from './resources/api-docs.js';
 import { registerStatusResource } from './resources/status.js';
+import { registerUploadRoute } from './resources/upload-route.js';
+import { registerDownloadRoute } from './resources/download-route.js';
+import { clearSession } from './lib/download-store.js';
 import { registerScrapeUrlPrompt } from './prompts/scrape-url.js';
 import { registerExtractContentPrompt } from './prompts/extract-content.js';
 import { AnalyticsHelper } from './lib/analytics.js';
-import { resolveApiKey, installSupabaseTokenTtlPatch, } from './lib/account-resolver.js';
+import { installSupabaseTokenTtlPatch } from './lib/account-resolver.js';
+import { resolveBrowserlessAuth } from './lib/http-auth.js';
 import { BoundedEventStore } from './lib/bounded-event-store.js';
 import { RedisOAuthProxy } from './lib/redis-oauth-proxy.js';
 import { Redis } from 'ioredis';
@@ -78,32 +81,14 @@ const oauthProvider = config.oauthEnabled && config.transport === 'httpStream'
 const hybridAuthenticate = config.transport === 'httpStream'
     ? async (request) => {
         const params = new URLSearchParams(request.url?.split('?')[1] ?? '');
-        const authHeader = request.headers.authorization;
-        const headerToken = authHeader?.startsWith('Bearer ')
-            ? authHeader.slice(7)
-            : authHeader;
-        const apiUrl = request.headers['x-browserless-api-url'] ??
-            params.get('browserlessUrl') ??
-            config.browserlessApiUrl;
-        // JWTs have 3 dot-separated base64url segments; plain API keys do not.
-        const isJwt = headerToken ? headerToken.split('.').length === 3 : false;
-        // 1. Authorization header with plain API key
-        if (headerToken && !isJwt) {
-            return { token: headerToken, apiUrl };
-        }
-        // 2. ?token= query param
-        const directToken = params.get('token') || undefined;
-        if (directToken) {
-            return { token: directToken, apiUrl };
-        }
-        // 3. Authorization header with JWT → decode Supabase token directly
-        if (isJwt && headerToken) {
-            const { apiKey } = await resolveApiKey(config.supabaseUrl, config.supabaseServiceRoleKey, headerToken);
-            return { token: apiKey, apiUrl };
-        }
-        throw new Error('No Browserless API token provided. ' +
-            'Pass it as Authorization: Bearer <token> header, ' +
-            '?token= query parameter, or authenticate via OAuth.');
+        return (await resolveBrowserlessAuth({
+            authHeader: request.headers.authorization,
+            tokenQuery: params.get('token') || undefined,
+            apiUrlHeader: request.headers['x-browserless-api-url'],
+            browserlessUrlQuery: params.get('browserlessUrl') || undefined,
+            sessionIdHeader: request.headers['x-browserless-session-id'],
+            sessionIdQuery: params.get('browserlessSessionId') || undefined,
+        }, config));
     }
     : undefined;
 const server = new FastMCP({
@@ -114,7 +99,6 @@ const server = new FastMCP({
 });
 registerSmartScraperTool(server, config, analytics);
 registerFunctionTool(server, config, analytics);
-registerDownloadTool(server, config, analytics);
 registerExportTool(server, config, analytics);
 registerAgentTools(server, config, analytics);
 registerSearchTool(server, config, analytics);
@@ -131,6 +115,8 @@ server.on('connect', (event) => {
 });
 server.on('disconnect', (event) => {
     const id = event.session.sessionId ?? 'stdio';
+    // Drop any files staged/captured for this session (TTL is the backstop).
+    clearSession(event.session.sessionId);
     console.error(`[browserless-mcp] Client disconnected: ${id}`);
 });
 if (config.transport === 'httpStream') {
@@ -143,6 +129,12 @@ if (config.transport === 'httpStream') {
             stateless: false,
         },
     });
+    // Out-of-band file staging for uploads (the LLM curls a file here and gets a
+    // handle, instead of base64-ing it through the conversation). httpStream only.
+    registerUploadRoute(server, config);
+    // Single-use, out-of-band fetch for captured downloads (the LLM GETs the file
+    // instead of pulling bytes through the conversation). httpStream only.
+    registerDownloadRoute(server, config);
     console.error(`[browserless-mcp] HTTP Streamable server listening on port ${config.port}`);
 }
 else {

package/build/src/lib/agent-client.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { CreateProfileParams } from '../tools/schemas.js';
 import type { ActiveSession, AgentResponse, ProxyOptions } from '../@types/types.js';
 export type { ProxyOptions, ActiveSession, AgentMessage, AgentResponse, AgentError, } from '../@types/types.js';
 export declare const ProxyOptionsSchema: z.ZodObject<{
@@ -46,13 +47,13 @@ export declare const proxyFingerprint: (proxy?: ProxyOptions) => string;
  * swap http(s)→ws(s), and append `token` plus proxy params. Boolean proxy
  * flags follow the API's presence-only contract (set only when truthy).
  */
-export declare const buildAgentWsUrl: (apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string) => string;
-export declare const getOrCreateSession: (mcpSessionId: string | undefined, apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string) => Promise<ActiveSession>;
+export declare const buildAgentWsUrl: (apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string, sessionId?: string) => string;
+export declare const getOrCreateSession: (mcpSessionId: string | undefined, apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string, createProfile?: CreateProfileParams, attachSessionId?: string) => Promise<ActiveSession>;
 export declare const send: (session: ActiveSession, method: string, params?: Record<string, unknown>, timeoutMs?: number) => Promise<AgentResponse>;
-export declare const closeSession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string) => void;
+export declare const closeSession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string, createProfile?: CreateProfileParams, attachSessionId?: string) => void;
 /**
  * Force-destroy a session after a browser crash or unrecoverable state, so
  * the next call reconnects fresh. Unlike `closeSession`, it also drops any
  * in-flight connect for the key so a concurrent caller can't reuse a dead WS.
  */
-export declare const destroySession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string) => void;
+export declare const destroySession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string, createProfile?: CreateProfileParams, attachSessionId?: string) => void;

package/build/src/lib/agent-client.js

@@ -99,11 +99,16 @@ export class ProfileNotFoundError extends UpgradeError {
     }
 }
 // Upgrade statuses where a one-shot retry cannot help: bad request (400),
-// bad auth (401), forbidden by plan/policy (403), or missing resource (404).
-// Retrying just wastes time and emits a misleading "second attempt failed".
-const NON_RETRYABLE_UPGRADE_STATUSES = new Set([400, 401, 403, 404]);
+// bad auth (401), forbidden by plan/policy (403), missing resource (404), or
+// concurrency limit (429). Retrying a 429 just opens another session and
+// stacks more lingering sessions against the same limit, so stop instead.
+const NON_RETRYABLE_UPGRADE_STATUSES = new Set([400, 401, 403, 404, 429]);
 export const isRetryableUpgradeError = (err) => {
     if (err instanceof UpgradeError) {
+        // A 2xx UpgradeError is a structurally-bad success response — retrying
+        // can't fix the shape (and may duplicate side effects), so don't.
+        if (err.statusCode >= 200 && err.statusCode < 300)
+            return false;
         return !NON_RETRYABLE_UPGRADE_STATUSES.has(err.statusCode);
     }
     return true;
@@ -172,18 +177,26 @@ export const proxyFingerprint = (proxy) => {
 // Hash the profile rather than serialize it raw: like externalProxyServer,
 // the eviction-logged session key may otherwise leak a user-identifying
 // profile name. Hashing keeps per-profile distinctness without that leak.
-const getSessionKey = (mcpSessionId, token, proxy, profile) => (mcpSessionId ?? `stdio:${hashToken(token)}`) +
+const getSessionKey = (mcpSessionId, token, proxy, profile, createProfile, attachSessionId) => (mcpSessionId ?? `stdio:${hashToken(token)}`) +
     proxyFingerprint(proxy) +
-    (profile ? KEY_SEP + 'profile#' + hashToken(profile) : '');
+    (profile ? KEY_SEP + 'profile#' + hashToken(profile) : '') +
+    (createProfile ? KEY_SEP + 'create#' + hashToken(createProfile.name) : '') +
+    (attachSessionId ? KEY_SEP + 'attach#' + attachSessionId : '');
 /**
  * Build the WebSocket URL for `/chromium/agent`: normalize trailing slashes,
  * swap http(s)→ws(s), and append `token` plus proxy params. Boolean proxy
  * flags follow the API's presence-only contract (set only when truthy).
  */
-export const buildAgentWsUrl = (apiUrl, token, proxy, profile) => {
+export const buildAgentWsUrl = (apiUrl, token, proxy, profile, sessionId) => {
     const base = apiUrl.replace(/^http/i, 'ws').replace(/\/+$/, '');
     const url = new URL(base + '/chromium/agent');
     url.searchParams.set('token', token);
+    // A creation session already owns its proxy/profile (baked in at POST /profile);
+    // the WS only needs to attach to it by id, so proxy/profile params are skipped.
+    if (sessionId) {
+        url.searchParams.set('sessionId', sessionId);
+        return url.toString();
+    }
     if (proxy?.proxy)
         url.searchParams.set('proxy', proxy.proxy);
     if (proxy?.proxyCountry)
@@ -322,8 +335,50 @@ const readUpgradeError = (res, profile) => new Promise((resolve) => {
     // `res.destroy()` can fire 'close' without 'end' or 'error'; settle here too.
     res.on('close', finish);
 });
-const connect = (apiUrl, token, proxy, profile) => new Promise((resolve, reject) => {
-    const wsUrl = buildAgentWsUrl(apiUrl, token, proxy, profile);
+// POST /profile launches a non-headless browser, which can take several seconds.
+const CREATE_PROFILE_TIMEOUT_MS = 60_000;
+/**
+ * Open a profile-creation session via POST /profile. Returns the tracked
+ * session id the agent WS then attaches to with `?sessionId`. Non-2xx responses
+ * throw UpgradeError so the tool layer's retry/4xx classification applies
+ * uniformly with the WS-upgrade path.
+ */
+const postCreateProfile = async (apiUrl, token, createProfile) => {
+    const base = apiUrl.replace(/\/+$/, '');
+    const url = new URL(base + '/profile');
+    url.searchParams.set('token', token);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CREATE_PROFILE_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(url.toString(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(createProfile),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new Error(`POST /profile failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new UpgradeError(res.status, res.statusText, body);
+    }
+    const json = await res.json();
+    if (typeof json !== 'object' ||
+        json === null ||
+        typeof json.id !== 'string' ||
+        !json.id) {
+        throw new UpgradeError(res.status, res.statusText, `POST /profile returned a malformed response (missing or invalid "id")`);
+    }
+    return json;
+};
+const connect = (apiUrl, token, proxy, profile, sessionId) => new Promise((resolve, reject) => {
+    const wsUrl = buildAgentWsUrl(apiUrl, token, proxy, profile, sessionId);
     const ws = new WebSocket(wsUrl);
     let settled = false;
     const settle = (err, value) => {
@@ -411,9 +466,9 @@ const sendMessage = (ws, msg, timeoutMs = DEFAULT_TIMEOUT) => new Promise((resol
     ws.on('close', closeHandler);
     ws.send(JSON.stringify(msg));
 });
-export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, profile) => {
+export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, profile, createProfile, attachSessionId) => {
     sweepSessions();
-    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+    const key = getSessionKey(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
     const existing = sessions.get(key);
     if (existing && existing.ws.readyState === WebSocket.OPEN) {
         existing.lastUsedAt = Date.now();
@@ -434,7 +489,19 @@ export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, pro
         sessions.delete(key);
     }
     const creation = (async () => {
-        const ws = await connect(apiUrl, token, proxy, profile);
+        // Three modes for the session to attach to:
+        //  - attachSessionId: a session the caller already created (autologin
+        //    runner did POST /profile itself) — attach by id, no POST here.
+        //  - createProfile: open a tracked session via POST /profile, then attach.
+        //  - neither: launch a fresh agent browser.
+        let creationSessionId;
+        if (attachSessionId) {
+            creationSessionId = attachSessionId;
+        }
+        else if (createProfile) {
+            creationSessionId = (await postCreateProfile(apiUrl, token, createProfile)).id;
+        }
+        const ws = await connect(apiUrl, token, proxy, profile, creationSessionId);
         const session = {
             ws,
             msgId: 0,
@@ -442,6 +509,8 @@ export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, pro
             token,
             proxy,
             profile,
+            createProfile,
+            creationSessionId,
             skillState: createSkillState(),
             lastUsedAt: Date.now(),
         };
@@ -473,7 +542,9 @@ export const getOrCreateSession = async (mcpSessionId, apiUrl, token, proxy, pro
 export const send = async (session, method, params = {}, timeoutMs) => {
     if (session.ws.readyState !== WebSocket.OPEN) {
         if (!session.reconnecting) {
-            session.reconnecting = connect(session.apiUrl, session.token, session.proxy, session.profile).finally(() => {
+            // A creation session must re-attach to the same browser by id — a fresh
+            // connect() would launch a new one and lose all auth progress.
+            session.reconnecting = connect(session.apiUrl, session.token, session.proxy, session.profile, session.creationSessionId).finally(() => {
                 session.reconnecting = undefined;
             });
         }
@@ -496,8 +567,8 @@ export const send = async (session, method, params = {}, timeoutMs) => {
     session.lastUsedAt = Date.now();
     return sendMessage(session.ws, { id: session.msgId, method, params }, timeoutMs);
 };
-export const closeSession = (mcpSessionId, token, proxy, profile) => {
-    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+export const closeSession = (mcpSessionId, token, proxy, profile, createProfile, attachSessionId) => {
+    const key = getSessionKey(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
     const session = sessions.get(key);
     if (session) {
         try {
@@ -514,8 +585,8 @@ export const closeSession = (mcpSessionId, token, proxy, profile) => {
  * the next call reconnects fresh. Unlike `closeSession`, it also drops any
  * in-flight connect for the key so a concurrent caller can't reuse a dead WS.
  */
-export const destroySession = (mcpSessionId, token, proxy, profile) => {
-    const key = getSessionKey(mcpSessionId, token, proxy, profile);
+export const destroySession = (mcpSessionId, token, proxy, profile, createProfile, attachSessionId) => {
+    const key = getSessionKey(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
     const session = sessions.get(key);
     if (session) {
         try {

package/build/src/lib/agent-format.d.ts

@@ -1,5 +1,5 @@
 import type { SnapshotResult } from '../@types/types.js';
-export type { SnapshotResult, SnapshotElement, TabInfo, } from '../@types/types.js';
+export type { SnapshotResult, SnapshotElement, TabInfo, FrameInfo, } from '../@types/types.js';
 /**
  * Build the cross-origin notice shown above a snapshot when the page changed
  * origin (protocol + host + port) since the last snapshot. Returns '' when

package/build/src/lib/agent-format.js

@@ -84,7 +84,7 @@ export const formatConnectError = (err) => {
             case 403:
                 return `Forbidden (403) — your plan does not include this feature${detail ? ` (server says: ${detail})` : ''}.`;
             case 429:
-                return `Concurrency limit reached (429)${detail ? `: ${detail}` : ''}. Wait for in-flight sessions to finish, or upgrade the plan.`;
+                return `Concurrency limit reached (429)${detail ? `: ${detail}` : ''}. Stop retrying — each new attempt opens another session and stacks more against the limit. Close any sessions you still have open (call browserless_agent with method "close"), wait for in-flight sessions to finish, or upgrade the plan, then start over.`;
             default: {
                 const fallback = detail || err.statusMessage || '';
                 return `Failed to connect to browser agent (HTTP ${err.statusCode})${fallback ? `: ${fallback}` : ''}.`;
@@ -98,10 +98,13 @@ export const formatConnectError = (err) => {
 };
 /**
  * Format a single snapshot element as a compact one-liner:
- *   [ref] tag role "name" ref=selector value="…" (state)
+ *   [ref] tag role "name" ref=selector value="…" (state) [frame#N]
  *   e.g. [7] input checkbox "Remember me" ref=input#remember (checked, required)
+ * `frameLabels` maps a frameId to its display label (frame#1, …); when an
+ * element carries a frameId, the label is appended so the agent sees which
+ * iframe it lives in.
  */
-const formatElement = (el) => {
+const formatElement = (el, frameLabels) => {
     const parts = [`[${el.ref}]`, el.tag, el.role];
     const name = el.name || el.text || '';
     if (name)
@@ -125,6 +128,9 @@ const formatElement = (el) => {
         flags.push('required');
     if (flags.length)
         parts.push(`(${flags.join(', ')})`);
+    const frameLabel = el.frameId && frameLabels?.get(el.frameId);
+    if (frameLabel)
+        parts.push(`[${frameLabel}]`);
     return parts.join(' ');
 };
 export const formatSnapshot = (snapshot) => {
@@ -146,9 +152,21 @@ export const formatSnapshot = (snapshot) => {
             lines.push(`! Detected challenge: ${type}`);
         }
     }
+    // Label cross-origin iframes (frame#1, …) and list them so the agent knows
+    // which elements live in a frame and that their deep-ref selectors pierce it.
+    const frameLabels = new Map();
+    if (snapshot.frames?.length) {
+        snapshot.frames.forEach((frame, i) => frameLabels.set(frame.frameId, `frame#${i + 1}`));
+        lines.push(`Frames (${snapshot.frames.length} iframes):`);
+        for (const frame of snapshot.frames) {
+            const origin = frame.crossOrigin ? 'cross-origin' : 'same-origin';
+            lines.push(`  ${frameLabels.get(frame.frameId)} ${frame.url} (${origin})`);
+        }
+        lines.push('Elements tagged [frame#N] live in that iframe; their deep-ref selectors pierce it — pass as-is to click/type/hover.');
+    }
     lines.push('');
     for (const el of snapshot.elements) {
-        lines.push(formatElement(el));
+        lines.push(formatElement(el, frameLabels));
     }
     lines.push('--- END SNAPSHOT ---');
     return lines.join('\n');

package/build/src/lib/define-tool.d.ts

@@ -37,6 +37,11 @@ export interface ToolRunContext<P> {
     }) => Promise<void>;
     /** MCP session id (httpStream transport) or undefined for stdio — used by agent tool. */
     sessionId: string | undefined;
+    /**
+     * Pre-created browser session id to attach to (from the `x-browserless-session-id`
+     * header). When set, the agent tool attaches to it instead of opening its own.
+     */
+    attachSessionId?: string;
 }
 export interface ToolDefinition<P, R> {
     name: string;

package/build/src/lib/define-tool.js

@@ -47,6 +47,7 @@ export function defineTool(server, config, analytics, def) {
                     apiUrl,
                     reportProgress,
                     sessionId,
+                    attachSessionId: s?.attachSessionId,
                 });
             }
             catch (err) {

package/build/src/lib/download-store.d.ts

@@ -0,0 +1,17 @@
+export interface StoredDownload {
+    id: string;
+    path: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    sessionId?: string;
+}
+export declare const DOWNLOAD_URI_SCHEME = "browserless-download";
+export declare const FILE_TRANSFER_MAX_BYTES: number;
+/** Build the handle URI for a stored download id. */
+export declare const downloadUri: (id: string) => string;
+export declare const storeDownload: (filename: string, mimeType: string, data: Buffer, sessionId?: string) => Promise<StoredDownload>;
+export declare const getDownload: (handle: string) => StoredDownload | undefined;
+export declare const consumeDownload: (handle: string) => StoredDownload | undefined;
+/** Drop every file owned by an MCP session (called when the session ends). */
+export declare const clearSession: (sessionId: string | undefined) => void;

package/build/src/lib/download-store.js

@@ -0,0 +1,84 @@
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+export const DOWNLOAD_URI_SCHEME = 'browserless-download';
+const TTL_MS = 15 * 60 * 1000;
+// Hard ceiling on a single file transfer (mirrors the enterprise cap).
+export const FILE_TRANSFER_MAX_BYTES = 50 * 1024 * 1024;
+const store = new Map();
+let counter = 0;
+// Where captured files land on the MCP server. Defaults to a temp dir; override
+// with BROWSERLESS_DOWNLOAD_DIR (e.g. a stable folder in local/stdio setups).
+const downloadsDir = () => process.env.BROWSERLESS_DOWNLOAD_DIR ||
+    join(tmpdir(), 'browserless-mcp-downloads');
+/** Build the handle URI for a stored download id. */
+export const downloadUri = (id) => `${DOWNLOAD_URI_SCHEME}://${id}`;
+const idFromHandle = (handle) => handle.startsWith(`${DOWNLOAD_URI_SCHEME}://`)
+    ? handle.slice(`${DOWNLOAD_URI_SCHEME}://`.length)
+    : handle;
+// Strip the internal timer handle before handing an entry to callers.
+const toRecord = (entry) => {
+    const { timer: _timer, ...record } = entry;
+    return record;
+};
+const dropEntry = (entry) => {
+    if (entry.timer)
+        clearTimeout(entry.timer);
+    store.delete(entry.id);
+    void rm(entry.path, { force: true }).catch(() => { });
+};
+// Persist bytes to disk under a fresh handle. `sessionId` ties the file to an
+// MCP session for cleanup on session end (no session → TTL only).
+export const storeDownload = async (filename, mimeType, data, sessionId) => {
+    const dir = downloadsDir();
+    await mkdir(dir, { recursive: true });
+    counter += 1;
+    const id = `${Date.now().toString(36)}-${counter}`;
+    const safe = basename(filename) || 'download';
+    // Prefix with the id so files that share a name don't collide.
+    const path = join(dir, `${id}-${safe}`);
+    await writeFile(path, data);
+    const timer = setTimeout(() => {
+        store.delete(id);
+        void rm(path, { force: true }).catch(() => { });
+    }, TTL_MS);
+    timer.unref?.();
+    const entry = {
+        id,
+        path,
+        filename: safe,
+        mimeType,
+        size: data.byteLength,
+        sessionId,
+        timer,
+    };
+    store.set(id, entry);
+    return toRecord(entry);
+};
+// Resolve a handle (id, URI, or stored path) WITHOUT removing it. Used by
+// uploadFile, which may reference the same file more than once.
+export const getDownload = (handle) => {
+    const entry = store.get(idFromHandle(handle)) ??
+        [...store.values()].find((r) => r.path === handle);
+    return entry && toRecord(entry);
+};
+// Resolve a handle and remove it (single-use): entry, TTL timer, and bytes.
+// Backs `GET /download/:id` so a download can only be fetched once.
+export const consumeDownload = (handle) => {
+    const entry = store.get(idFromHandle(handle));
+    if (!entry)
+        return undefined;
+    if (entry.timer)
+        clearTimeout(entry.timer);
+    store.delete(entry.id);
+    return toRecord(entry);
+};
+/** Drop every file owned by an MCP session (called when the session ends). */
+export const clearSession = (sessionId) => {
+    if (!sessionId)
+        return;
+    for (const entry of [...store.values()]) {
+        if (entry.sessionId === sessionId)
+            dropEntry(entry);
+    }
+};