firecrawl-mcp 3.22.4 → 3.23.1

package/dist/index.js

@@ -3,17 +3,143 @@
 // src/index.ts
 import FirecrawlApp from "@mendable/firecrawl-js";
 import dotenv from "dotenv";
-import { FastMCP } from "fastmcp";
+import { FastMCP, UserError } from "fastmcp";
 import { readFile } from "fs/promises";
 import { createRequire } from "module";
+import { randomUUID } from "crypto";
 import path from "path";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
-// src/monitor.ts
+// src/developer.ts
 import { z } from "zod";
+var BASE = "/v2/developer/search";
+var ORIGIN_HEADERS = { "X-Origin": "mcp-fastmcp" };
+var MAX_PASSAGE_CHARS = 1200;
+function fmtDeveloper(results) {
+  if (!results || results.length === 0) return "(no results)";
+  return results.map((r) => {
+    const kind = r.type ? ` (${r.type})` : "";
+    const lines = [`## [${r.id ?? "?"}]${kind} ${r.title ?? "(untitled)"}`];
+    if (r.url) lines.push(r.url);
+    const body = (r.passages ?? []).map((p) => p.text ?? "").join("\n---\n").trim();
+    lines.push(body ? body.slice(0, MAX_PASSAGE_CHARS) : "(no content)");
+    return lines.join("\n");
+  }).join("\n\n");
+}
+function registerDeveloperTools(server2, getClient2) {
+  server2.addTool({
+    name: "firecrawl_developer_search",
+    annotations: {
+      title: "Search developer sources",
+      readOnlyHint: true,
+      // Semantic search over an indexed developer corpus; returns ranked results only.
+      openWorldHint: true,
+      // Searches the Firecrawl developer index of public GitHub and documentation content.
+      destructiveHint: false
+      // Query-only; no writes to external sources or the developer index.
+    },
+    description: `
+For a developer question \u2014 code behaviour, a library or framework, an API contract, an error message, or a known bug \u2014 search an index built for coding agents. The index covers GitHub issues, merged pull requests, repository READMEs, and curated documentation sites.
+
+Returns ranked results with an ID, source type, URL, title, and the matched passages in markdown.
+`,
+    parameters: z.object({
+      query: z.string().min(1).describe(
+        "Natural-language developer question or search phrase, including the library, error message, or API involved when relevant."
+      ),
+      k: z.number().int().min(1).max(100).optional().describe("Number of ranked results to return (default 20).")
+    }),
+    execute: async (args2, { session }) => {
+      const { query, k } = args2;
+      const params = new URLSearchParams();
+      params.append("query", query);
+      if (k != null) params.append("k", String(k));
+      const client = getClient2(session);
+      const res = await client.http.get(
+        `${BASE}?${params.toString()}`,
+        ORIGIN_HEADERS
+      );
+      return fmtDeveloper(res.data?.results);
+    }
+  });
+}
+
+// src/keyless-client-ip.ts
+import net from "net";
+function extractSingleTrustedClientIp(rawForwardedFor) {
+  if (Array.isArray(rawForwardedFor) && rawForwardedFor.length !== 1) {
+    return void 0;
+  }
+  const raw = Array.isArray(rawForwardedFor) ? rawForwardedFor[0] : rawForwardedFor;
+  if (typeof raw !== "string") return void 0;
+  const parts = raw.split(",").map((part) => part.trim()).filter(Boolean);
+  if (parts.length !== 1) return void 0;
+  const candidate = parts[0].replace(/^\[(.*)\]$/, "$1").toLowerCase();
+  return net.isIP(candidate) ? candidate : void 0;
+}
+
+// src/monitor.ts
+import { z as z2 } from "zod";
+
+// src/session-credential.ts
+import { createHmac } from "crypto";
+var managedOAuthApiKey = /* @__PURE__ */ Symbol("firecrawlManagedOAuthApiKey");
+var CredentialValidationUnavailableError = class extends Error {
+  constructor() {
+    super("Firecrawl credential validation is temporarily unavailable");
+    this.name = "CredentialValidationUnavailableError";
+  }
+};
+function delegationSecret() {
+  const secret = process.env.MCP_DELEGATED_CREDENTIAL_SECRET?.trim();
+  if (!secret) throw new CredentialValidationUnavailableError();
+  return secret;
+}
+function requireDelegatedCredentialSigning() {
+  delegationSecret();
+}
+function setManagedOAuthApiKey(session, apiKey) {
+  Object.defineProperty(session, managedOAuthApiKey, {
+    configurable: false,
+    enumerable: false,
+    value: apiKey,
+    writable: false
+  });
+  return session;
+}
+function copyManagedOAuthApiKey(source, target) {
+  const apiKey = source?.[managedOAuthApiKey];
+  if (apiKey) setManagedOAuthApiKey(target, apiKey);
+}
+function hasCredential(session) {
+  return Boolean(session?.firecrawlApiKey || session?.[managedOAuthApiKey]);
+}
+function hasManagedOAuthCredential(session) {
+  return Boolean(session?.[managedOAuthApiKey]);
+}
+function credentialForOutboundRequest(session) {
+  const managedApiKey = session?.[managedOAuthApiKey];
+  if (!managedApiKey) return session?.firecrawlApiKey;
+  const iat = Math.floor(Date.now() / 1e3);
+  const payload = {
+    v: 1,
+    aud: "firecrawl-core",
+    purpose: "hosted_mcp_oauth",
+    api_key: managedApiKey,
+    iat,
+    exp: iat + 60
+  };
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString(
+    "base64url"
+  );
+  const signature = createHmac("sha256", delegationSecret()).update(encodedPayload).digest("base64url");
+  return `fcmcp_${encodedPayload}.${signature}`;
+}
+
+// src/monitor.ts
 var DEFAULT_API_URL = "https://api.firecrawl.dev";
 function resolveAuth(session) {
-  const apiKey = session?.firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY;
+  const apiKey = session === void 0 ? process.env.FIRECRAWL_API_KEY : credentialForOutboundRequest(session);
   const baseUrl = (process.env.FIRECRAWL_API_URL ?? DEFAULT_API_URL).replace(
     /\/$/,
     ""
@@ -52,8 +178,8 @@ async function monitorRequest(session, path2, init = {}) {
 function asText(data) {
   return JSON.stringify(data, null, 2);
 }
-var pageStatusSchema = z.enum(["same", "new", "changed", "removed", "error"]);
-var checkStatusSchema = z.enum([
+var pageStatusSchema = z2.enum(["same", "new", "changed", "removed", "error"]);
+var checkStatusSchema = z2.enum([
   "queued",
   "running",
   "completed",
@@ -142,141 +268,26 @@ function registerMonitorTools(server2) {
       // Additive; creates a new monitor without deleting existing monitors or external content.
     },
     description: `
-Create a Firecrawl monitor \u2014 a recurring scrape, crawl, or search that diffs each result against the last retained snapshot.
-
-Prefer the simple path: pass \`page\` or \`pages\` plus \`goal\` to monitor specific URLs, OR pass \`queries\` plus \`goal\` to monitor web search results for new/changed hits. The tool will create the monitor with a 30-minute schedule and meaningful-change judging enabled by the API. Use \`body\` only for advanced requests such as crawl targets, JSON change tracking, custom retention, or manual \`judgeEnabled\` control.
-
-Meaningful-change judge: set \`goal\` to a plain-language description of what the user actually cares about. \`judgeEnabled\` defaults to true when \`goal\` is set, so providing \`goal\` is enough. Page webhooks expose \`isMeaningful\` and \`judgment\` on \`monitor.page\` events.
+Create a recurring scrape, crawl, or search monitor that compares each check with its retained predecessor. The simple form accepts \`page\`/\`pages\` or \`queries\` plus a plain-language \`goal\`; the advanced \`body\` form controls targets, schedule, change-tracking formats, judging, retention, webhook, and notifications.
 
-Simple fields:
-- \`page\`: one page URL to monitor.
-- \`pages\`: multiple page URLs to monitor.
-- \`queries\`: one or more search queries (1-12) to monitor instead of fixed URLs. Each check runs the searches and diffs the result set, so you get alerted when new or changed results appear. Mutually exclusive with \`page\`/\`pages\` in the simple path.
-- \`searchWindow\`: optional recency window for search targets \u2014 one of \`5m\`, \`15m\`, \`1h\`, \`6h\`, \`24h\`, \`7d\` (default \`24h\`).
-- \`maxResults\`: optional max results per search, 1-50 (default 10).
-- \`includeDomains\` / \`excludeDomains\`: optional domain allow/deny lists for search targets.
-- \`goal\`: plain-English instruction for what changes matter. Required for the simple path (and always required when \`queries\` are set \u2014 web monitors must have a goal).
-- \`scheduleText\`: optional natural-language schedule, default \`every 30 minutes\`.
-- \`email\`: optional email recipient for summaries.
-- \`webhookUrl\`: optional webhook URL. Configures \`monitor.page\` and \`monitor.check.completed\`.
-
-**Search-mode example:**
-
-\`\`\`json
-{
-  "name": "firecrawl_monitor_create",
-  "arguments": {
-    "queries": ["new LLM release", "frontier model launch"],
-    "goal": "Notify me about major new LLM model releases.",
-    "searchWindow": "24h",
-    "maxResults": 10
-  }
-}
-\`\`\`
-
-Goal guidance:
-- Expand the user's one-line monitoring intent into a concise 2-3 sentence monitor goal.
-- State what should trigger an alert, restate any scope the user gave, and include intent-specific exclusions only when obvious from the user's request.
-- Generic noise such as whitespace, formatting-only changes, request IDs, tracking params, generic metadata, and unrelated page chrome is already handled by the judge; do not repeat it in every goal.
-- If the user is vague, keep the goal broad rather than guessing exclusions. If the user asks for broad monitoring or "any change", preserve that and do not add exclusions that hide changes.
-- If the user says they do not care about something, include that explicitly. It is okay to ask whether they want to ignore specific noise when it is likely to matter.
-- Do not invent page-specific sections, thresholds, entities, or business rules unless the user mentioned them.
-
-Query guidance (web monitors): \`queries\` control recall (what search retrieves) and \`goal\` controls precision (which results alert) \u2014 tune both.
-- Write keywords, not sentences: \`OpenAI new model release\`, not \`tell me when OpenAI releases a new model\`.
-- Quote multi-word entities (\`"Llama 4"\`); group synonyms with \`OR\` (\`launch OR release OR announcement\`).
-- Keep each query tight (~2-6 terms). One broad query usually beats several narrow ones \u2014 extra queries split the \`maxResults\` budget. Use one query per distinct entity; do not emit one per facet of a single subject.
-- Keep \`site:\` operators out of queries \u2014 use \`includeDomains\` / \`excludeDomains\`.
-- A healthy web monitor mostly returns \`new: 0\` and alerts only on genuinely new, on-goal results. Many \`ignored\` results \u21D2 queries too broad (tighten them); nothing for long stretches \u21D2 queries too narrow or window too tight (broaden); dismissed alerts \u21D2 goal too broad (add an intent-specific Ignore). Aim for high precision with enough recall.
-
-Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\`, \`{ type: 'crawl', url: '...' }\`, or \`{ type: 'search', queries: [...], searchWindow?, maxResults?, includeDomains?, excludeDomains? }\`). Optional: \`goal\` (required when any search target is present), \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
-
-**Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
-
-\`\`\`json
-{
-  "name": "firecrawl_monitor_create",
-  "arguments": {
-    "page": "https://example.com/blog",
-    "goal": "Alert when a new blog post is published or an existing headline changes.",
-    "email": "alerts@example.com"
-  }
-}
-\`\`\`
-
-**Multiple pages:**
-
-\`\`\`json
-{
-  "name": "firecrawl_monitor_create",
-  "arguments": {
-    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
-    "goal": "Alert when pricing, packaging, or launch messaging changes.",
-    "webhookUrl": "https://example.com/webhooks/firecrawl"
-  }
-}
-\`\`\`
-
-**JSON-mode change tracking:** To detect changes in **specific structured fields** (price, headline, in-stock flag, list items) instead of the whole page, add a \`changeTracking\` format with \`modes: ["json"]\` and a JSON schema to the target's \`scrapeOptions.formats\`. The check response will then carry a per-field diff (keyed by JSON path, e.g. \`plans[0].price\`) and a \`snapshot.json\` with the full current extraction. See \`firecrawl_monitor_check\` for the response shape.
-
-\`\`\`json
-{
-  "name": "firecrawl_monitor_create",
-  "arguments": {
-    "body": {
-      "name": "Pricing watch",
-      "schedule": { "text": "hourly", "timezone": "UTC" },
-      "goal": "Alert when a pricing tier, price, billing period, limit, or headline feature changes. Ignore unrelated marketing copy unless it changes the pricing offer.",
-      "targets": [{
-        "type": "scrape",
-        "urls": ["https://example.com/pricing"],
-        "scrapeOptions": {
-          "formats": [{
-            "type": "changeTracking",
-            "modes": ["json"],
-            "prompt": "Extract pricing tiers and headline features for each plan.",
-            "schema": {
-              "type": "object",
-              "properties": {
-                "plans": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name":     { "type": "string" },
-                      "price":    { "type": "string" },
-                      "features": { "type": "array", "items": { "type": "string" } }
-                    }
-                  }
-                }
-              }
-            }
-          }]
-        }
-      }]
-    }
-  }
-}
-\`\`\`
-
-**Mixed mode (JSON + git-diff):** Use \`modes: ["json", "git-diff"]\` to get both per-field diffs and a markdown sidecar. The page is marked \`changed\` whenever either surface changed.
+In the simple form, a \`goal\` is required. If \`queries\` contains one or more non-empty values and is supplied with \`page\`/\`pages\`, \`queries\` create the search target and page targets are ignored. A monitor schedules future network checks and can send configured email or webhook notifications. Returns the created monitor.
 `,
-    parameters: z.object({
-      body: z.record(z.string(), z.any()).optional(),
-      page: z.string().optional(),
-      pages: z.array(z.string()).optional(),
-      queries: z.array(z.string()).optional(),
-      searchWindow: z.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
-      maxResults: z.number().int().min(1).max(50).optional(),
-      includeDomains: z.array(z.string()).optional(),
-      excludeDomains: z.array(z.string()).optional(),
-      goal: z.string().optional(),
-      name: z.string().optional(),
-      scheduleText: z.string().optional(),
-      timezone: z.string().optional(),
-      email: z.string().optional(),
-      includeDiffs: z.boolean().optional(),
-      webhookUrl: z.string().optional()
+    parameters: z2.object({
+      body: z2.record(z2.string(), z2.any()).optional(),
+      page: z2.string().optional(),
+      pages: z2.array(z2.string()).optional(),
+      queries: z2.array(z2.string()).optional(),
+      searchWindow: z2.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
+      maxResults: z2.number().int().min(1).max(50).optional(),
+      includeDomains: z2.array(z2.string()).optional(),
+      excludeDomains: z2.array(z2.string()).optional(),
+      goal: z2.string().optional(),
+      name: z2.string().optional(),
+      scheduleText: z2.string().optional(),
+      timezone: z2.string().optional(),
+      email: z2.string().optional(),
+      includeDiffs: z2.boolean().optional(),
+      webhookUrl: z2.string().optional()
     }),
     execute: async (args2, { session, log }) => {
       const body = buildMonitorCreateBody(args2);
@@ -300,16 +311,11 @@ Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\
       // Read-only listing.
     },
     description: `
-List all Firecrawl monitors for the authenticated account.
-
-**Usage Example:**
-\`\`\`json
-{ "name": "firecrawl_monitor_list", "arguments": { "limit": 20 } }
-\`\`\`
+List monitors for the authenticated account with optional pagination controls. Returns one page of monitor records and pagination metadata.
 `,
-    parameters: z.object({
-      limit: z.number().int().positive().optional(),
-      offset: z.number().int().nonnegative().optional()
+    parameters: z2.object({
+      limit: z2.number().int().positive().optional(),
+      offset: z2.number().int().nonnegative().optional()
     }),
     execute: async (args2, { session }) => {
       const { limit, offset } = args2;
@@ -331,14 +337,9 @@ List all Firecrawl monitors for the authenticated account.
       // Read-only retrieval.
     },
     description: `
-Get a single monitor by ID.
-
-**Usage Example:**
-\`\`\`json
-{ "name": "firecrawl_monitor_get", "arguments": { "id": "mon_abc123" } }
-\`\`\`
+Retrieve one monitor by ID, including its configuration and current state. This does not run or modify the monitor.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -360,22 +361,13 @@ Get a single monitor by ID.
       // Can pause, replace, or remove monitor configuration; changes overwrite prior settings.
     },
     description: `
-Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("active" | "paused"), \`schedule\`, \`targets\`, \`goal\`, \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
+Patch an existing monitor by ID. The body can change its name, active/paused status, schedule, targets, goal, judging, webhook, notifications, or retention; these changes affect future scheduled checks.
 
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_monitor_update",
-  "arguments": {
-    "id": "mon_abc123",
-    "body": { "status": "paused" }
-  }
-}
-\`\`\`
+Returns the updated monitor.
 `,
-    parameters: z.object({
-      id: z.string(),
-      body: z.record(z.string(), z.any())
+    parameters: z2.object({
+      id: z2.string(),
+      body: z2.record(z2.string(), z2.any())
     }),
     execute: async (args2, { session }) => {
       const { id, body } = args2;
@@ -399,14 +391,9 @@ Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("act
       // Irreversibly removes the monitor and stops its schedule.
     },
     description: `
-Permanently delete a monitor and stop its schedule. This cannot be undone.
-
-**Usage Example:**
-\`\`\`json
-{ "name": "firecrawl_monitor_delete", "arguments": { "id": "mon_abc123" } }
-\`\`\`
+Permanently delete a monitor by ID and stop its future schedule. This operation cannot be undone and returns deletion status.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session, log }) => {
       const { id } = args2;
       log.info("Deleting monitor", { id });
@@ -430,14 +417,9 @@ Permanently delete a monitor and stop its schedule. This cannot be undone.
       // Starts a read-only check job; does not delete the monitor or external sites.
     },
     description: `
-Trigger a monitor check immediately, outside its normal schedule. Returns the queued check.
-
-**Usage Example:**
-\`\`\`json
-{ "name": "firecrawl_monitor_run", "arguments": { "id": "mon_abc123" } }
-\`\`\`
+Queue an immediate check for a monitor outside its normal schedule. This starts network work for the monitor's configured targets and returns the queued check.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -460,17 +442,12 @@ Trigger a monitor check immediately, outside its normal schedule. Returns the qu
       // Read-only listing.
     },
     description: `
-List historical checks for a monitor.
-
-**Usage Example:**
-\`\`\`json
-{ "name": "firecrawl_monitor_checks", "arguments": { "id": "mon_abc123", "limit": 10, "status": "completed" } }
-\`\`\`
+List historical checks for a monitor, optionally filtered by status and bounded by a result limit. Returns one page of check summaries and pagination metadata.
 `,
-    parameters: z.object({
-      id: z.string(),
-      limit: z.number().int().positive().optional(),
-      offset: z.number().int().nonnegative().optional(),
+    parameters: z2.object({
+      id: z2.string(),
+      limit: z2.number().int().positive().optional(),
+      offset: z2.number().int().nonnegative().optional(),
       status: checkStatusSchema.optional()
     }),
     execute: async (args2, { session }) => {
@@ -495,66 +472,15 @@ List historical checks for a monitor.
       // Read-only retrieval of diff snapshots and judgments.
     },
     description: `
-Get a single check with page-level diff results. Filter \`pageStatus\` to surface only the pages that changed (or were new, removed, etc.).
-
-Each entry in \`data.pages[]\` has \`url\`, \`status\` (\`same\` | \`new\` | \`changed\` | \`removed\` | \`error\`), optional \`judgment\` when goal-based judging ran, and \u2014 when changed \u2014 a \`diff\` and possibly a \`snapshot\`. The shape of \`diff\` depends on the monitor's \`formats\` configuration:
+Retrieve one monitor check and its page-level results, optionally filtered by page status. Pages report \`same\`, \`new\`, \`changed\`, \`removed\`, or \`error\`; configured goal judging can add a meaningful-change decision.
 
-- **Markdown mode (default).** \`diff.text\` is the unified markdown diff; \`diff.json\` is a parse-diff AST (\`{ files: [...] }\`). No \`snapshot\`.
-- **JSON mode** (\`changeTracking\` with \`modes: ["json"]\`). \`diff.json\` is a per-field map keyed by JSON path into the extraction, e.g. \`plans[0].price\`, with each value being \`{ previous, current }\`. \`snapshot.json\` is the full current extraction. No \`diff.text\`.
-- **Mixed mode** (\`modes: ["json", "git-diff"]\`). Both \`diff.text\` (markdown sidecar) AND \`diff.json\` (per-field map) are present, plus \`snapshot.json\`.
-
-**Example JSON-mode response \`pages[]\` entry:**
-
-\`\`\`json
-{
-  "url": "https://example.com/pricing",
-  "status": "changed",
-  "diff": {
-    "json": {
-      "plans[0].price":       { "previous": "$19/mo",        "current": "$24/mo" },
-      "plans[1].features[2]": { "previous": "10 GB storage", "current": "25 GB storage" }
-    }
-  },
-  "snapshot": { "json": { "plans": [/* current full extraction matching the monitor's schema */] } },
-  "judgment": {
-    "meaningful": true,
-    "confidence": "high",
-    "reason": "The pricing changed, which matches the monitor goal.",
-    "meaningfulChanges": [
-      {
-        "type": "changed",
-        "before": "$19/mo",
-        "after": "$24/mo",
-        "reason": "The tracked plan price changed."
-      }
-    ]
-  }
-}
-\`\`\`
-
-When summarizing a check for the user, prefer \`diff.json\` paths (e.g. "plans[0].price changed from $19/mo to $24/mo") over re-printing the markdown diff \u2014 it's more concise and grounded in the schema fields they asked for.
-
-When \`judgment\` is present, use it to decide what to surface. \`judgment.meaningful: false\` means the change was classified as noise for the monitor's goal. When \`judgment.meaningfulChanges\` is present, prefer those goal-relevant changes over raw diff hunks; each item includes \`type\`, \`before\`, \`after\`, and \`reason\`.
-
-The endpoint paginates via a top-level \`next\` URL; this tool returns one page at a time. Increase \`limit\` (max 100) to fetch fewer pages.
-
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_monitor_check",
-  "arguments": {
-    "id": "mon_abc123",
-    "checkId": "chk_xyz",
-    "pageStatus": "changed"
-  }
-}
-\`\`\`
+Markdown tracking returns a unified text diff, JSON tracking returns field paths with previous/current values and a current snapshot, and mixed tracking returns both. Returns one page of results plus a \`next\` URL when more pages exist.
 `,
-    parameters: z.object({
-      id: z.string(),
-      checkId: z.string(),
-      limit: z.number().int().positive().optional(),
-      skip: z.number().int().nonnegative().optional(),
+    parameters: z2.object({
+      id: z2.string(),
+      checkId: z2.string(),
+      limit: z2.number().int().positive().optional(),
+      skip: z2.number().int().nonnegative().optional(),
       pageStatus: pageStatusSchema.optional()
     }),
     execute: async (args2, { session }) => {
@@ -570,9 +496,9 @@ The endpoint paginates via a top-level \`next\` URL; this tool returns one page
 }
 
 // src/research.ts
-import { z as z2 } from "zod";
-var BASE = "/v2/search/research";
-var ORIGIN_HEADERS = { "X-Origin": "mcp-fastmcp" };
+import { z as z3 } from "zod";
+var BASE2 = "/v2/search/research";
+var ORIGIN_HEADERS2 = { "X-Origin": "mcp-fastmcp" };
 function appendParam(params, key, value) {
   if (value == null) return;
   if (Array.isArray(value)) {
@@ -635,7 +561,7 @@ function fmtPaperMetadata(paper) {
   lines.push("");
   lines.push(`Paper ID: ${paper.paperId ?? "?"}`);
   const ids = Object.entries(paper.ids ?? {}).flatMap(
-    ([namespace, values]) => values.map((value) => `${namespace}:${value}`)
+    ([namespace, values2]) => values2.map((value) => `${namespace}:${value}`)
   ).join(", ");
   if (ids) lines.push(`IDs: ${ids}`);
   const authors = fmtAuthors(paper.authors);
@@ -689,22 +615,26 @@ function registerResearchTools(server2, getClient2) {
       destructiveHint: false
       // Query-only; no writes to external sources or the research index.
     },
-    description: "Primary entry point for finding research papers by topic across AI/ML, computer science, math, physics, biomedical, life sciences, and clinical literature. Semantic (HyDE) search over indexed paper metadata and abstracts; returns ranked papers with paper id, title, authors, and abstract. The query should be a natural-language research topic or question. Run SEVERAL distinct framings of the question (sibling domains, rival methods, dataset or benchmark names, conditions, populations, interventions, or outcomes) rather than one query \u2014 recall improves markedly with diverse framings.",
-    parameters: z2.object({
-      query: z2.string().min(1).describe(
+    description: `
+For topics represented in the indexed corpus, search paper metadata and abstracts with a natural-language query. Optional author, category, and date filters constrain results.
+
+Returns ranked papers with canonical IDs, titles, authors, and abstracts.
+`,
+    parameters: z3.object({
+      query: z3.string().min(1).describe(
         "Natural-language research topic or question, including methods, systems, conditions, populations, interventions, or outcomes when relevant."
       ),
-      k: z2.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
-      authors: z2.array(z2.string()).optional().describe(
+      k: z3.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
+      authors: z3.array(z3.string()).optional().describe(
         "Author substring filter(s); ALL must match (case-insensitive)."
       ),
-      categories: z2.array(z2.string()).optional().describe(
+      categories: z3.array(z3.string()).optional().describe(
         "Paper category filter(s) (e.g. `cs.LG`); ALL provided values must match."
       ),
-      from: z2.string().optional().describe(
+      from: z3.string().optional().describe(
         "Inclusive lower bound on created/updated date (`YYYY-MM-DD`)."
       ),
-      to: z2.string().optional().describe(
+      to: z3.string().optional().describe(
         "Inclusive upper bound on created/updated date (`YYYY-MM-DD`)."
       )
     }),
@@ -719,8 +649,8 @@ function registerResearchTools(server2, getClient2) {
       appendParam(params, "to", to);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/papers`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/papers`, params),
+        ORIGIN_HEADERS2
       );
       return fmtHits(res.data?.results);
     }
@@ -736,9 +666,11 @@ function registerResearchTools(server2, getClient2) {
       destructiveHint: false
       // Read-only metadata lookup.
     },
-    description: "Fetch canonical metadata for one paper by primaryId or canonical paperId. Use this after search/related results when you need the full title, abstract, authors, categories, source ids, and dates rendered as markdown.",
-    parameters: z2.object({
-      paperId: z2.string().min(1).describe(
+    description: `
+Retrieve canonical metadata for one paper ID, such as an arXiv, PMC, PMID, or DOI identifier. Returns the title, abstract, authors, categories, source IDs, and dates as markdown.
+`,
+    parameters: z3.object({
+      paperId: z3.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       )
     }),
@@ -746,8 +678,8 @@ function registerResearchTools(server2, getClient2) {
       const { paperId } = args2;
       const client = getClient2(session);
       const res = await client.http.get(
-        `${BASE}/papers/${encodeURIComponent(paperId)}`,
-        ORIGIN_HEADERS
+        `${BASE2}/papers/${encodeURIComponent(paperId)}`,
+        ORIGIN_HEADERS2
       );
       return fmtPaperMetadata(res.data?.paper);
     }
@@ -763,13 +695,17 @@ function registerResearchTools(server2, getClient2) {
       destructiveHint: false
       // Read-only graph query; no modifications.
     },
-    description: "Expand from anchor papers you have already found, via the citation graph, ranked and filtered to a natural-language `intent`. Pass arXiv ids of your strongest hits as `seed_ids`. Modes: `similar` (cocitation/coupling \u2014 papers in the same niche; the default), `citers` (papers that cite the anchors), `references` (papers the anchors cite). This reaches relevant papers that plain search misses, so use it on your best hits before finishing. A `similar` call already runs a DEEP multi-round expansion internally (re-seeding from each round\u2019s best finds), so one call reaches the wider neighborhood \u2014 no need to chain many. Returns the candidates plus the pool size.",
-    parameters: z2.object({
-      seed_ids: z2.array(z2.string()).min(1).max(10),
-      intent: z2.string().min(1),
-      mode: z2.enum(["similar", "citers", "references"]).optional(),
-      k: z2.number().int().min(1).max(500).optional(),
-      rerank: z2.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
+    description: `
+Find citation-graph candidates from one to ten \`seed_ids\`; the first ID is the primary seed and later IDs are anchors. \`mode\` defaults to \`similar\` (co-citation/bibliographic coupling); \`citers\` returns papers citing a seed and \`references\` papers cited by a seed. \`intent\` ranks candidates.
+
+Returns ranked candidates and the evaluated pool size.
+`,
+    parameters: z3.object({
+      seed_ids: z3.array(z3.string()).min(1).max(10),
+      intent: z3.string().min(1),
+      mode: z3.enum(["similar", "citers", "references"]).optional(),
+      k: z3.number().int().min(1).max(500).optional(),
+      rerank: z3.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
     }),
     execute: async (args2, { session }) => {
       const { seed_ids, intent, mode, k, rerank } = args2;
@@ -783,10 +719,10 @@ function registerResearchTools(server2, getClient2) {
       const client = getClient2(session);
       const res = await client.http.get(
         withQuery(
-          `${BASE}/papers/${encodeURIComponent(primary)}/similar`,
+          `${BASE2}/papers/${encodeURIComponent(primary)}/similar`,
           params
         ),
-        ORIGIN_HEADERS
+        ORIGIN_HEADERS2
       );
       const note = res.data?.note ? `
 note: ${res.data.note}` : "";
@@ -805,13 +741,17 @@ note: ${res.data.note}` : "";
       destructiveHint: false
       // Read-only passage retrieval.
     },
-    description: "Read the most relevant in-body (full-text) passages of ONE specific paper for a question. Use this to VERIFY whether a candidate actually satisfies a constraint before you include or reject it (e.g. 'does this paper actually use technique X / report a score on benchmark Y'). Returns the best-matching passages, or a notice if the paper's full text is unavailable.",
-    parameters: z2.object({
-      paperId: z2.string().min(1).describe(
+    description: `
+Retrieve in-body passages from one paper that are relevant to a specific question. Full text is available only for indexed papers; \`k\` controls the number of passages.
+
+Returns matching passages or a notice when full text is unavailable.
+`,
+    parameters: z3.object({
+      paperId: z3.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       ),
-      question: z2.string().min(1),
-      k: z2.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
+      question: z3.string().min(1),
+      k: z3.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
     }),
     execute: async (args2, { session }) => {
       const { paperId, question, k } = args2;
@@ -820,8 +760,8 @@ note: ${res.data.note}` : "";
       appendParam(params, "k", k);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(paperId)}`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/papers/${encodeURIComponent(paperId)}`, params),
+        ORIGIN_HEADERS2
       );
       const passages = res.data?.passages ?? [];
       return passages.length ? passages.map((p) => p.text).join("\n---\n") : "(no full-text passages available for this paper)";
@@ -838,10 +778,12 @@ note: ${res.data.note}` : "";
       destructiveHint: false
       // Query-only; does not create issues, PRs, or modify repositories.
     },
-    description: "Search GitHub issue/PR history and repository readmes. Returns ranked matches with repo, url, a short snippet, and (when available) the full matched content in markdown.",
-    parameters: z2.object({
-      query: z2.string().min(1),
-      k: z2.number().int().min(1).max(100).optional()
+    description: `
+Search indexed public GitHub issue, pull-request, and README content. Returns ranked matches with repository, URL, snippet, and full matched markdown when available.
+`,
+    parameters: z3.object({
+      query: z3.string().min(1),
+      k: z3.number().int().min(1).max(100).optional()
     }),
     execute: async (args2, { session }) => {
       const { query, k } = args2;
@@ -850,8 +792,8 @@ note: ${res.data.note}` : "";
       appendParam(params, "k", k);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/github`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/github`, params),
+        ORIGIN_HEADERS2
       );
       return fmtGithub(res.data?.results);
     }
@@ -878,6 +820,22 @@ function extractBearerToken(headers) {
 function isFirecrawlOAuthAccessToken(token) {
   return token.startsWith("fco_");
 }
+function isFirecrawlApiKey(token) {
+  return token.startsWith("fc-");
+}
+function isLegacyKeyPathRequest(request) {
+  return normalizeHeader(request?.headers?.["x-firecrawl-key-transport"]) === "path";
+}
+function requestShouldReceiveOAuthChallenge(request, profile) {
+  if (!profile.acceptApiKeys) return true;
+  if (!request?.headers) return true;
+  const headerApiKey = normalizeHeader(
+    request.headers["x-firecrawl-api-key"] ?? request.headers["x-api-key"]
+  );
+  if (headerApiKey) return false;
+  const bearer = extractBearerToken(request.headers);
+  return !bearer || isFirecrawlOAuthAccessToken(bearer);
+}
 function resolveCredentialFromEnv() {
   return normalizeHeader(process.env.FIRECRAWL_OAUTH_TOKEN) ?? normalizeHeader(process.env.FIRECRAWL_API_KEY);
 }
@@ -886,6 +844,9 @@ function isHttpStreamingTransport() {
 }
 var DEFAULT_OAUTH_ISSUER = "https://www.firecrawl.dev";
 var DEFAULT_MCP_RESOURCE_URL = "https://mcp.firecrawl.dev/v2/mcp";
+var DEFAULT_MCP_OAUTH_RESOURCE_URL = "https://mcp.firecrawl.dev/v2/mcp-oauth";
+var DEFAULT_MCP_SEARCH_RESOURCE_URL = "https://mcp.firecrawl.dev/v2/mcp-search";
+var DEFAULT_MCP_SEARCH_ENDPOINT = "/v2/mcp-search";
 function withoutTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
@@ -897,19 +858,40 @@ function getOAuthIssuer() {
 function getMcpResourceUrl() {
   return normalizeHeader(process.env.FIRECRAWL_MCP_RESOURCE_URL) ?? DEFAULT_MCP_RESOURCE_URL;
 }
-function getOAuthProtectedResourceMetadataUrl() {
-  return `${new URL(getMcpResourceUrl()).origin}/.well-known/oauth-protected-resource`;
+function getPrimaryEndpoint() {
+  const endpoint = normalizeHeader(process.env.FASTMCP_ENDPOINT) ?? "/v2/mcp";
+  if (endpoint === "/v2/mcp" || endpoint === "/v2/mcp-oauth" || endpoint === "/v2/mcp-search") {
+    return endpoint;
+  }
+  throw new Error(
+    `Unsupported FASTMCP_ENDPOINT: ${endpoint}. Expected /v2/mcp, /v2/mcp-oauth, or /v2/mcp-search.`
+  );
+}
+function getSearchMcpResourceUrl() {
+  return normalizeHeader(process.env.FIRECRAWL_MCP_SEARCH_RESOURCE_URL) ?? DEFAULT_MCP_SEARCH_RESOURCE_URL;
+}
+function getSearchMcpEndpoint() {
+  const configured = normalizeHeader(process.env.FIRECRAWL_MCP_SEARCH_ENDPOINT);
+  if (configured && configured.startsWith("/")) {
+    return configured;
+  }
+  return DEFAULT_MCP_SEARCH_ENDPOINT;
+}
+function getOAuthProtectedResourceMetadataUrl(profile) {
+  const resource = new URL(profile.resourceUrl);
+  const base = `${resource.origin}/.well-known/oauth-protected-resource`;
+  return profile.id === "full" ? base : `${base}${resource.pathname}`;
 }
 function escapeWWWAuthenticateValue(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
-function createOAuthChallengeResponse(error) {
+function createOAuthChallengeResponse(error, profile) {
   if (!isMcpOAuthEnabled()) {
     return void 0;
   }
   const errorMessage = error instanceof Error ? error.message : String(error || "Unauthorized");
   const wwwAuthenticate = [
-    `resource_metadata="${escapeWWWAuthenticateValue(getOAuthProtectedResourceMetadataUrl())}"`,
+    `resource_metadata="${escapeWWWAuthenticateValue(getOAuthProtectedResourceMetadataUrl(profile))}"`,
     'error="invalid_token"',
     `error_description="${escapeWWWAuthenticateValue(errorMessage)}"`
   ].join(", ");
@@ -927,6 +909,18 @@ function createOAuthChallengeResponse(error) {
     }
   );
 }
+function createInvalidCredentialResponse(error) {
+  return new Response(
+    JSON.stringify({
+      error: "invalid_api_key",
+      error_description: error.message
+    }),
+    {
+      headers: { "Content-Type": "application/json" },
+      status: 401
+    }
+  );
+}
 function getOAuthIntrospectionEndpoint() {
   return `${getOAuthIssuer()}/api/oauth/introspect`;
 }
@@ -936,63 +930,168 @@ function getOAuthIntrospectionSecret() {
 function isMcpOAuthEnabled() {
   return process.env.CLOUD_SERVICE === "true";
 }
-async function introspectOAuthAccessToken(token) {
+function isOAuthCredentialPurpose(value) {
+  return value === "general" || value === "hosted_mcp_oauth";
+}
+var InvalidFirecrawlCredentialError = class extends Error {
+  constructor() {
+    super("The supplied Firecrawl credential is invalid or revoked. Replace it and retry.");
+    this.name = "InvalidFirecrawlCredentialError";
+  }
+};
+var MCP_GLOBAL_SCOPE = "firecrawl:global";
+function values(value) {
+  if (typeof value === "string") return value.split(/\s+/).filter(Boolean);
+  return Array.isArray(value) ? value.flatMap((item) => item.split(/\s+/).filter(Boolean)) : [];
+}
+function audienceMatchesResource(aud, resourceUrl) {
+  const target = withoutTrailingSlash(resourceUrl);
+  return values(aud).some((entry) => withoutTrailingSlash(entry) === target);
+}
+function credentialMetadata(data) {
+  return {
+    teamId: typeof data.team_id === "string" ? data.team_id : void 0,
+    userId: typeof data.sub === "string" ? data.sub : void 0,
+    apiKeyId: typeof data.api_key_id === "string" ? data.api_key_id : void 0,
+    oauthClientId: typeof data.client_id === "string" ? data.client_id : void 0,
+    resource: typeof data.aud === "string" ? data.aud : void 0
+  };
+}
+async function introspectToken(token, expectedResource) {
   const introspectionSecret = getOAuthIntrospectionSecret();
-  if (!introspectionSecret) {
-    throw new Error("OAuth token introspection is not configured");
+  if (!introspectionSecret) throw new CredentialValidationUnavailableError();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1500);
+  let response;
+  try {
+    response = await fetch(getOAuthIntrospectionEndpoint(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Bearer ${introspectionSecret}`
+      },
+      body: new URLSearchParams({
+        resource: expectedResource,
+        token,
+        token_type_hint: "access_token"
+      }),
+      signal: controller.signal
+    });
+  } catch {
+    throw new CredentialValidationUnavailableError();
+  } finally {
+    clearTimeout(timeout);
   }
-  const response = await fetch(getOAuthIntrospectionEndpoint(), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Authorization: `Bearer ${introspectionSecret}`
-    },
-    body: new URLSearchParams({
-      token,
-      token_type_hint: "access_token"
-    })
-  });
-  if (!response.ok) {
-    throw new Error(`OAuth token introspection failed: ${response.status}`);
+  if (!response.ok) throw new CredentialValidationUnavailableError();
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  if (!contentType.includes("application/json")) {
+    throw new CredentialValidationUnavailableError();
   }
   const data = await response.json();
-  if (!data.active || !data.api_key) {
-    throw new Error("Invalid OAuth access token");
+  if (typeof data.active !== "boolean") {
+    throw new CredentialValidationUnavailableError();
+  }
+  if (data.active && (!data.api_key || !isOAuthCredentialPurpose(data.credential_purpose) || !values(data.scope).includes(MCP_GLOBAL_SCOPE))) {
+    throw new CredentialValidationUnavailableError();
   }
-  return data.api_key;
+  return data;
 }
-async function resolveCredentialFromHeaders(headers) {
+async function resolveCredentialFromHeaders(headers, profile) {
   const bearer = extractBearerToken(headers);
   const headerApiKey = normalizeHeader(
     headers["x-firecrawl-api-key"] ?? headers["x-api-key"]
   );
-  if (bearer && isFirecrawlOAuthAccessToken(bearer)) {
-    return introspectOAuthAccessToken(bearer);
+  const token = headerApiKey ?? bearer;
+  if (!token) return void 0;
+  if (!profile.acceptApiKeys && !isFirecrawlOAuthAccessToken(token)) {
+    throw new Error(
+      `OAuth access token required for the Firecrawl MCP resource ${profile.endpoint}`
+    );
+  }
+  if (!isFirecrawlOAuthAccessToken(token) && !isFirecrawlApiKey(token)) {
+    return { invalid: true };
+  }
+  let data = await introspectToken(token, profile.resourceUrl);
+  if (isFirecrawlOAuthAccessToken(token) && !data.active && profile.acceptLegacyAudience) {
+    data = await introspectToken(token, DEFAULT_MCP_RESOURCE_URL);
+  }
+  if (!data.active || !data.api_key) {
+    if (isFirecrawlOAuthAccessToken(token)) {
+      throw new Error("Invalid OAuth access token");
+    }
+    return { invalid: true };
   }
-  if (headerApiKey) {
-    return headerApiKey;
+  if (isFirecrawlApiKey(token)) {
+    return data.credential_purpose === "general" ? {
+      credential: data.api_key,
+      source: "api-key",
+      metadata: credentialMetadata(data)
+    } : { invalid: true };
   }
-  if (bearer) {
-    return bearer;
+  const expectedAudience = profile.acceptLegacyAudience && audienceMatchesResource(data.aud, DEFAULT_MCP_RESOURCE_URL) ? DEFAULT_MCP_RESOURCE_URL : profile.resourceUrl;
+  if (!audienceMatchesResource(data.aud, expectedAudience)) {
+    throw new Error("OAuth token audience does not match this resource");
   }
-  return void 0;
+  if (profile.requireManagedOAuth && data.credential_purpose !== "hosted_mcp_oauth") {
+    throw new Error("OAuth token is not a managed Firecrawl MCP credential");
+  }
+  if (data.credential_purpose === "hosted_mcp_oauth") {
+    requireDelegatedCredentialSigning();
+    return {
+      managedOAuthApiKey: data.api_key,
+      source: "oauth",
+      metadata: credentialMetadata(data)
+    };
+  }
+  return {
+    credential: data.api_key,
+    source: "oauth",
+    metadata: credentialMetadata(data)
+  };
 }
-async function authenticateRequest(request) {
-  const headerCred = request?.headers ? await resolveCredentialFromHeaders(request.headers) : void 0;
+async function authenticateRequest(request, profile) {
+  const resolved = request?.headers ? await resolveCredentialFromHeaders(request.headers, profile) : void 0;
+  const headerCred = resolved?.credential;
+  const managedCred = resolved?.managedOAuthApiKey;
   const envCred = resolveCredentialFromEnv();
   if (process.env.CLOUD_SERVICE === "true") {
-    if (!headerCred) {
-      const clientIp = extractClientIp(request);
-      if (process.env.KEYLESS_PROXY_SECRET && clientIp && await keylessEligible(clientIp)) {
-        return { firecrawlApiKey: void 0, keylessClientIp: clientIp };
+    if (!headerCred && !managedCred) {
+      if (resolved?.invalid) {
+        if (!profile.acceptApiKeys) {
+          throw new Error(
+            `OAuth access token required for the Firecrawl MCP resource ${profile.endpoint}`
+          );
+        }
+        if (isLegacyKeyPathRequest(request)) {
+          throw new InvalidFirecrawlCredentialError();
+        }
+        return { authType: "none", credentialError: "CREDENTIAL_INVALID" };
+      }
+      if (profile.allowKeyless) {
+        return {
+          authType: "keyless",
+          firecrawlApiKey: void 0,
+          keylessClientIp: extractClientIp(request)
+        };
+      }
+      if (!profile.acceptApiKeys) {
+        throw new Error(
+          `OAuth access token required for the Firecrawl MCP resource ${profile.endpoint}`
+        );
       }
       throw new Error(
         "Firecrawl credentials required: OAuth access token (Authorization: Bearer fco_...) or API key (x-firecrawl-api-key)"
       );
     }
-    return { firecrawlApiKey: headerCred };
+    const session2 = {
+      authType: resolved?.source === "oauth" ? "oauth" : "api-key",
+      firecrawlApiKey: headerCred,
+      ...isLegacyKeyPathRequest(request) ? { keyTransport: "path" } : {},
+      ...resolved?.metadata
+    };
+    return managedCred ? setManagedOAuthApiKey(session2, managedCred) : session2;
   }
-  const credential = headerCred ?? envCred;
+  const credential = headerCred ?? managedCred ?? envCred;
   const httpStreaming = isHttpStreamingTransport();
   if (!httpStreaming && !process.env.FIRECRAWL_API_KEY && !process.env.FIRECRAWL_API_URL) {
     console.error(
@@ -1005,23 +1104,103 @@ async function authenticateRequest(request) {
     );
     process.exit(1);
   }
-  return { firecrawlApiKey: credential };
+  const session = {
+    authType: resolved?.source === "oauth" ? "oauth" : credential ? "env" : "none",
+    firecrawlApiKey: headerCred ?? envCred,
+    ...resolved?.metadata
+  };
+  return managedCred ? setManagedOAuthApiKey(session, managedCred) : session;
 }
-async function authenticateWithOAuthChallenge(request) {
-  if (request?.[authResultByRequest]) {
-    return request[authResultByRequest];
-  }
-  const authResult = authenticateRequest(request).catch((error) => {
-    const oauthChallenge = createOAuthChallengeResponse(error);
-    if (oauthChallenge) {
-      throw oauthChallenge;
+function searchCompanionAuthMode(request, session) {
+  if (session?.authType === "oauth") return "oauth";
+  if (session?.authType === "api-key") return "api-key";
+  const headerApiKey = normalizeHeader(
+    request?.headers?.["x-firecrawl-api-key"] ?? request?.headers?.["x-api-key"]
+  );
+  if (headerApiKey) return "api-key";
+  const bearer = request?.headers ? extractBearerToken(request.headers) : void 0;
+  if (bearer?.startsWith("fco_")) return "oauth";
+  if (bearer) return "api-key";
+  return "none";
+}
+function emitSearchCompanionAuthTelemetry(profile, request, outcome, session) {
+  if (process.env.CLOUD_SERVICE !== "true" || profile.id !== "search" || profile.primary === true) {
+    return;
+  }
+  console.log(
+    "[MCP_SEARCH_AUTH]",
+    JSON.stringify({
+      auth_mode: searchCompanionAuthMode(request, session),
+      outcome,
+      profile: "companion",
+      // Unique only to this telemetry record; it is not a cross-service
+      // correlation ID and does not accept client-controlled identifiers.
+      event_id: randomUUID(),
+      route: DEFAULT_MCP_SEARCH_ENDPOINT
+    })
+  );
+}
+function emitLegacyKeyPathTelemetry(profile, request, outcome, session) {
+  if (profile.id !== "full" || !isLegacyKeyPathRequest(request)) return;
+  console.log(
+    "[MCP_LEGACY_KEY_PATH]",
+    JSON.stringify({
+      auth_type: session?.authType ?? "none",
+      key_transport: "path",
+      outcome,
+      resource: profile.resourceUrl
+    })
+  );
+}
+function makeAuthenticate(profile) {
+  return async function authenticateWithOAuthChallenge(request) {
+    if (request?.[authResultByRequest]) {
+      return request[authResultByRequest];
     }
-    throw error;
-  });
-  if (request) {
-    request[authResultByRequest] = authResult;
-  }
-  return authResult;
+    const authResult = authenticateRequest(request, profile).then((session) => {
+      emitSearchCompanionAuthTelemetry(
+        profile,
+        request,
+        session.credentialError ? "rejected" : "accepted",
+        session
+      );
+      emitLegacyKeyPathTelemetry(
+        profile,
+        request,
+        session.credentialError ? "rejected" : "accepted",
+        session
+      );
+      return session;
+    }).catch((error) => {
+      emitSearchCompanionAuthTelemetry(profile, request, "rejected");
+      emitLegacyKeyPathTelemetry(profile, request, "rejected");
+      if (error instanceof InvalidFirecrawlCredentialError) {
+        throw createInvalidCredentialResponse(error);
+      }
+      if (error instanceof CredentialValidationUnavailableError) {
+        throw new Response(
+          JSON.stringify({
+            error: "temporarily_unavailable",
+            error_description: error.message
+          }),
+          {
+            headers: { "Content-Type": "application/json" },
+            status: 503
+          }
+        );
+      }
+      const shouldChallenge = requestShouldReceiveOAuthChallenge(request, profile);
+      const oauthChallenge = shouldChallenge ? createOAuthChallengeResponse(error, profile) : void 0;
+      if (oauthChallenge) {
+        throw oauthChallenge;
+      }
+      throw error;
+    });
+    if (request) {
+      request[authResultByRequest] = authResult;
+    }
+    return authResult;
+  };
 }
 function removeEmptyTopLevel(obj) {
   const out = {};
@@ -1035,7 +1214,7 @@ function removeEmptyTopLevel(obj) {
   }
   return out;
 }
-var searchDomainSchema = z3.string().trim().toLowerCase().min(1).max(253).regex(
+var searchDomainSchema = z4.string().trim().toLowerCase().min(1).max(253).regex(
   /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/,
   "Domain must be a valid hostname without protocol or path"
 );
@@ -1048,6 +1227,27 @@ function buildSearchQueryWithDomains(query, includeDomains, excludeDomains) {
   }
   return query;
 }
+var searchToolBaseFields = {
+  query: z4.string().min(1),
+  highlights: z4.boolean().optional().describe(
+    "Return query-relevant highlights for each search result. Set to false to keep the original search snippets."
+  ),
+  limit: z4.number().optional(),
+  tbs: z4.string().optional(),
+  filter: z4.string().optional(),
+  location: z4.string().optional(),
+  includeDomains: z4.array(searchDomainSchema).optional(),
+  excludeDomains: z4.array(searchDomainSchema).optional(),
+  sources: z4.array(z4.object({ type: z4.enum(["web", "images", "news"]) })).optional(),
+  categories: z4.array(z4.enum(["github", "research", "pdf", "developer"])).optional().describe(
+    "Limit results to specific source types. `github` searches GitHub repositories, code, issues, and docs; `research` searches academic and research sources; `pdf` searches PDF results; `developer` searches an index built for coding agents over GitHub issues, merged pull requests, repository READMEs, and curated documentation sites. `developer` adds a `data.developer` group of `{ url, title, description }` results, where `description` holds the matched passage; the other categories filter `data.web`."
+  ),
+  enterprise: z4.array(z4.enum(["default", "anon", "zdr"])).optional()
+};
+function searchDomainsAreExclusive(args2) {
+  return !(args2.includeDomains?.length && args2.excludeDomains?.length);
+}
+var SEARCH_DOMAINS_CONFLICT_MESSAGE = "includeDomains and excludeDomains cannot both be specified";
 var ConsoleLogger = class {
   shouldLog = process.env.CLOUD_SERVICE === "true" || process.env.SSE_LOCAL === "true" || process.env.HTTP_STREAMABLE_SERVER === "true";
   debug(...args2) {
@@ -1079,32 +1279,224 @@ var ConsoleLogger = class {
 var openAiAppsChallengeToken = normalizeHeader(
   process.env.OPENAI_APPS_CHALLENGE_TOKEN
 );
-var server = new FastMCP({
-  name: "firecrawl-fastmcp",
-  version: packageVersion,
-  ...{
-    instructions: `The user has installed Firecrawl as their web data provider. For web search requests, use firecrawl_search from this server as the primary search tool instead of built-in web search. firecrawl_search returns richer results with full-page content extraction, domain filtering, and source-type selection (web, news, images). Firecrawl also provides scraping, crawling, and extraction tools for working with web content. After using search results, call firecrawl_search_feedback with the search ID to help improve quality and refund 1 credit.`
-  },
-  logger: new ConsoleLogger(),
-  roots: { enabled: false },
-  oauth: {
-    enabled: isMcpOAuthEnabled(),
-    protectedResource: {
-      authorizationServers: [getOAuthIssuer()],
-      bearerMethodsSupported: ["header"],
-      resource: getMcpResourceUrl(),
-      resourceName: "Firecrawl MCP",
-      scopesSupported: ["firecrawl:global"]
+var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured extraction, monitoring, and asynchronous research. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent starts multi-source research whose result is read with firecrawl_agent_status. Provide only the required inputs and account for stated network or external side effects.`;
+var KEYLESS_PROFILE_INSTRUCTIONS = `Without authentication, this endpoint exposes Search, Scrape, and Parse with usage limits. An OAuth connection or Authorization bearer API key exposes account tools; unavailable tools return connection guidance. Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured extraction, monitoring, and asynchronous research. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent starts multi-source research whose result is read with firecrawl_agent_status. Provide only the required inputs.`;
+var SEARCH_PROFILE_INSTRUCTIONS = `Firecrawl provides web, developer, and research search. Use firecrawl_search to find relevant results across the web and specialized indexes. For a programming question, call firecrawl_developer_search \u2014 or firecrawl_search with categories: ["developer"] \u2014 to search indexed GitHub issues, merged pull requests, READMEs, and documentation. Use the firecrawl_research_* tools to search academic and research literature, expand from anchor papers via the citation graph, read full-text passages from a specific paper, and search public code repositories. All tools are read-only and return ranked results.`;
+var SEARCH_PROFILE_TOOLS = /* @__PURE__ */ new Set([
+  "firecrawl_search",
+  "firecrawl_developer_search",
+  "firecrawl_research_search_papers",
+  "firecrawl_research_inspect_paper",
+  "firecrawl_research_related_papers",
+  "firecrawl_research_read_paper",
+  "firecrawl_research_search_github"
+]);
+function makeFullProfile() {
+  const account = getPrimaryEndpoint() === "/v2/mcp-oauth";
+  return {
+    id: account ? "account" : "full",
+    resourceName: account ? "Firecrawl MCP Account" : "Firecrawl MCP",
+    instructions: account ? FULL_PROFILE_INSTRUCTIONS : KEYLESS_PROFILE_INSTRUCTIONS,
+    resourceUrl: account ? normalizeHeader(process.env.FIRECRAWL_MCP_RESOURCE_URL) ?? DEFAULT_MCP_OAUTH_RESOURCE_URL : getMcpResourceUrl(),
+    endpoint: account ? "/v2/mcp-oauth" : void 0,
+    port: Number(process.env.PORT || 3e3),
+    allowKeyless: !account,
+    acceptApiKeys: true,
+    acceptLegacyAudience: account && process.env.MCP_OAUTH_ACCEPT_LEGACY_V2_MCP_AUD !== "false",
+    primary: true
+  };
+}
+function searchOAuthOnly() {
+  return process.env.FIRECRAWL_MCP_SEARCH_OAUTH_ONLY === "true";
+}
+function makeSearchProfile({ primary = false } = {}) {
+  const oauthOnly = searchOAuthOnly();
+  if (primary && !oauthOnly) {
+    throw new Error(
+      "FASTMCP_ENDPOINT=/v2/mcp-search requires FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true"
+    );
+  }
+  return {
+    id: "search",
+    resourceName: "Firecrawl Search",
+    instructions: SEARCH_PROFILE_INSTRUCTIONS,
+    resourceUrl: getSearchMcpResourceUrl(),
+    endpoint: primary ? DEFAULT_MCP_SEARCH_ENDPOINT : getSearchMcpEndpoint(),
+    port: primary ? Number(process.env.PORT || 3e3) : Number(process.env.FIRECRAWL_MCP_SEARCH_PORT || 3001),
+    toolAllowlist: SEARCH_PROFILE_TOOLS,
+    allowKeyless: false,
+    // This is deliberately default-false because the image auto-deploys: the
+    // existing in-process companion remains API-key compatible unless its
+    // deployment explicitly enables the same profile flag used by primary.
+    acceptApiKeys: !oauthOnly,
+    requireManagedOAuth: oauthOnly,
+    primary
+  };
+}
+function makePrimaryProfile() {
+  return getPrimaryEndpoint() === "/v2/mcp-search" ? makeSearchProfile({ primary: true }) : makeFullProfile();
+}
+function createServer(profile) {
+  return new FastMCP({
+    name: "firecrawl-fastmcp",
+    version: packageVersion,
+    instructions: profile.instructions,
+    logger: new ConsoleLogger(),
+    roots: { enabled: false },
+    oauth: {
+      enabled: isMcpOAuthEnabled(),
+      protectedResource: {
+        authorizationServers: [getOAuthIssuer()],
+        bearerMethodsSupported: ["header"],
+        resource: profile.resourceUrl,
+        resourceName: profile.resourceName,
+        scopesSupported: ["firecrawl:global"]
+      }
+    },
+    authenticate: makeAuthenticate(profile),
+    // Lightweight health endpoint for LB checks
+    health: {
+      enabled: true,
+      message: "ok",
+      path: "/health",
+      status: 200
     }
-  },
-  authenticate: authenticateWithOAuthChallenge,
-  // Lightweight health endpoint for LB checks
-  health: {
-    enabled: true,
-    message: "ok",
-    path: "/health",
-    status: 200
+  });
+}
+var primaryProfile = makePrimaryProfile();
+var server = createServer(primaryProfile);
+var KEYLESS_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "firecrawl_scrape",
+  "firecrawl_search",
+  "firecrawl_parse"
+]);
+function isHostedKeylessSession(session) {
+  return process.env.CLOUD_SERVICE === "true" && session?.authType === "keyless" && !session.firecrawlApiKey;
+}
+function isLocalKeylessStartup() {
+  return process.env.CLOUD_SERVICE !== "true" && !isHttpStreamingTransport() && !resolveCredentialFromEnv() && !normalizeHeader(process.env.FIRECRAWL_API_URL);
+}
+function recoveryPayload(code, requestId = randomUUID(), options = {}) {
+  const retryAfterSeconds = options.retryAfterSeconds;
+  const isQuotaExhausted = code === "KEYLESS_QUOTA_EXHAUSTED" || code === "KEYLESS_LIMIT_REACHED";
+  const isToolUnavailable = code === "KEYLESS_TOOL_NOT_AVAILABLE";
+  const isKeylessAccessUnavailable = code === "KEYLESS_ACCESS_NOT_AVAILABLE";
+  const isKeylessEligibilityUnavailable = code === "KEYLESS_ELIGIBILITY_UNAVAILABLE";
+  const oauthUrl = "https://mcp.firecrawl.dev/v2/mcp-oauth";
+  return {
+    code,
+    request_id: requestId,
+    auth_mode: code === "CREDENTIAL_INVALID" ? "credential_error" : "keyless",
+    message: code === "CREDENTIAL_INVALID" ? "The supplied Firecrawl credential is invalid or revoked. Replace it or reconnect the account, then retry." : isQuotaExhausted ? `The free daily limit for this network has been reached${retryAfterSeconds ? `; try again in about ${retryAfterSeconds} seconds` : ""}. To continue now, connect a Firecrawl account via OAuth or configure an API key.` : isToolUnavailable ? "The free tier includes Search, Scrape, and Parse. This tool needs a connected account; Search, Scrape, and Parse still work, so no action is required." : isKeylessAccessUnavailable ? "Anonymous keyless access is unavailable for this request. To continue, connect a Firecrawl account via OAuth or configure an API key." : isKeylessEligibilityUnavailable ? "The anonymous keyless eligibility check is temporarily unavailable. Retry shortly." : "This tool requires a Firecrawl account or API key. Connect an account or configure Authorization: Bearer <FIRECRAWL_API_KEY>, then retry.",
+    ...isKeylessAccessUnavailable ? {} : { available_tools: [...KEYLESS_TOOL_NAMES] },
+    docs_url: "https://docs.firecrawl.dev/mcp-server",
+    ...retryAfterSeconds ? { retry_after_seconds: retryAfterSeconds } : {},
+    next_actions: isKeylessEligibilityUnavailable ? [{ kind: "retry_later", after_seconds: 30 }] : isQuotaExhausted || isKeylessAccessUnavailable ? [
+      { kind: "connect_oauth", url: oauthUrl, client_commands: [{ client: "claude-code", command: "claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp-oauth" }] },
+      { kind: "configure_api_key", header: "Authorization: Bearer <FIRECRAWL_API_KEY>" }
+    ] : isToolUnavailable ? [{ kind: "continue_keyless", tools: [...KEYLESS_TOOL_NAMES] }] : [
+      { kind: "connect_oauth", url: oauthUrl },
+      { kind: "configure_api_key", header: "Authorization: Bearer <FIRECRAWL_API_KEY>" }
+    ]
+  };
+}
+function emitActionLog(toolName, status, session, error, requestId = randomUUID(), code) {
+  if (process.env.CLOUD_SERVICE !== "true") return;
+  const payload = {
+    team_id: session?.teamId,
+    user_id: session?.userId,
+    api_key_id: session?.apiKeyId,
+    oauth_client_id: session?.oauthClientId,
+    auth_type: session?.authType ?? "none",
+    tool_name: toolName,
+    status,
+    request_id: requestId,
+    resource: primaryProfile.resourceUrl,
+    ...error ? { error_class: error instanceof Error ? error.name : typeof error } : {},
+    ...code ? { code } : {}
+  };
+  console.error("[MCP_ACTION]", JSON.stringify(payload));
+  const secret = normalizeHeader(process.env.FIRECRAWL_MCP_ACTION_LOG_SECRET);
+  const apiUrl = normalizeHeader(process.env.FIRECRAWL_API_URL);
+  const endpoint = normalizeHeader(process.env.FIRECRAWL_MCP_ACTION_LOG_URL) ?? (apiUrl ? `${withoutTrailingSlash(apiUrl)}/v2/mcp/action-logs` : void 0);
+  if (!secret || !endpoint || !payload.team_id || status === "started") return;
+  const actionLogPayload = { ...payload };
+  delete actionLogPayload.code;
+  void fetch(endpoint, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${secret}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(actionLogPayload),
+    signal: AbortSignal.timeout(1500)
+  }).catch(() => void 0);
+}
+function guardHostedTool(tool, { logActions }) {
+  const keylessTool = KEYLESS_TOOL_NAMES.has(tool.name);
+  const execute = tool.execute;
+  return {
+    ...tool,
+    canList: (session) => !session?.credentialError && (!isHostedKeylessSession(session) || keylessTool),
+    beforeValidate: (_args, session) => {
+      const code = session?.credentialError ? "CREDENTIAL_INVALID" : isHostedKeylessSession(session) && !keylessTool ? "KEYLESS_TOOL_NOT_AVAILABLE" : void 0;
+      if (!code) return void 0;
+      const requestId = randomUUID();
+      const payload = recoveryPayload(code, requestId);
+      if (logActions) {
+        emitActionLog(tool.name, "error", session, new UserError(String(payload.message), payload), requestId, code);
+      }
+      return {
+        content: [{ type: "text", text: String(payload.message) }],
+        isError: true,
+        structuredContent: payload
+      };
+    },
+    execute: async (args2, context) => {
+      const requestId = randomUUID();
+      const invocationSession = {
+        ...context.session,
+        requestId
+      };
+      copyManagedOAuthApiKey(context.session, invocationSession);
+      const invocationContext = {
+        ...context,
+        session: invocationSession
+      };
+      if (invocationSession.credentialError) {
+        const code = "CREDENTIAL_INVALID";
+        const payload = recoveryPayload(code, requestId);
+        if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError(String(payload.message), payload), requestId, code);
+        throw new UserError(String(payload.message), payload);
+      }
+      if (isHostedKeylessSession(invocationSession) && !keylessTool) {
+        const code = "KEYLESS_TOOL_NOT_AVAILABLE";
+        const payload = recoveryPayload(code, requestId);
+        if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError(String(payload.message), payload), requestId, code);
+        throw new UserError(String(payload.message), payload);
+      }
+      if (!logActions) return execute(args2, invocationContext);
+      emitActionLog(tool.name, "started", invocationSession, void 0, requestId);
+      try {
+        const result = await execute(args2, invocationContext);
+        emitActionLog(tool.name, "success", invocationSession, void 0, requestId);
+        return result;
+      } catch (error) {
+        emitActionLog(tool.name, "error", invocationSession, error, requestId);
+        throw error;
+      }
+    }
+  };
+}
+var addTool = server.addTool.bind(server);
+server.addTool = ((tool) => {
+  if (primaryProfile.toolAllowlist && !primaryProfile.toolAllowlist.has(tool.name)) {
+    return;
   }
+  if (primaryProfile.id === "search" && tool.name === "firecrawl_search") {
+    return;
+  }
+  addTool(guardHostedTool(tool, { logActions: primaryProfile.id !== "search" }));
 });
 if (openAiAppsChallengeToken) {
   server.getApp().get(
@@ -1112,6 +1504,31 @@ if (openAiAppsChallengeToken) {
     (context) => context.text(openAiAppsChallengeToken)
   );
 }
+server.getApp().get("/ready", (context) => {
+  if (process.env.CLOUD_SERVICE !== "true") {
+    return context.json({ ok: true }, 200);
+  }
+  const searchPrimary = primaryProfile.id === "search";
+  const required = [
+    "FIRECRAWL_API_URL",
+    "FIRECRAWL_OAUTH_INTROSPECT_SECRET",
+    "MCP_DELEGATED_CREDENTIAL_SECRET"
+  ];
+  if (primaryProfile.allowKeyless) {
+    required.push("KEYLESS_PROXY_SECRET");
+  }
+  const missing = required.filter((name) => !normalizeHeader(process.env[name]));
+  const configuredEndpoint = getPrimaryEndpoint();
+  const resourceMatchesEndpoint = searchPrimary ? withoutTrailingSlash(primaryProfile.resourceUrl) === DEFAULT_MCP_SEARCH_RESOURCE_URL : withoutTrailingSlash(primaryProfile.resourceUrl).endsWith(
+    configuredEndpoint
+  );
+  if (!resourceMatchesEndpoint) {
+    missing.push(
+      searchPrimary ? "FIRECRAWL_MCP_SEARCH_RESOURCE_URL (endpoint mismatch)" : "FIRECRAWL_MCP_RESOURCE_URL (endpoint mismatch)"
+    );
+  }
+  return missing.length ? context.json({ ok: false, missing }, 503) : context.json({ ok: true }, 200);
+});
 function createClient(apiKey) {
   const config = {
     ...process.env.FIRECRAWL_API_URL && {
@@ -1124,21 +1541,35 @@ function createClient(apiKey) {
   return new FirecrawlApp(config);
 }
 var ORIGIN = "mcp-fastmcp";
-var ORIGIN_HEADERS2 = { "X-Origin": ORIGIN };
+var ORIGIN_HEADERS3 = { "X-Origin": ORIGIN };
 var SAFE_MODE = process.env.CLOUD_SERVICE === "true";
 function getClient(session) {
-  if (process.env.CLOUD_SERVICE === "true") {
-    if (!session || !session.firecrawlApiKey) {
-      throw new Error("Unauthorized");
-    }
-    return createClient(session.firecrawlApiKey);
+  if (process.env.CLOUD_SERVICE === "true" && !hasCredential(session)) {
+    throw new Error("Unauthorized");
   }
-  if (!process.env.FIRECRAWL_API_URL && (!session || !session.firecrawlApiKey)) {
+  if (!process.env.FIRECRAWL_API_URL && !hasCredential(session)) {
     throw new Error(
       "Unauthorized: API key is required when not using a self-hosted instance"
     );
   }
-  return createClient(session?.firecrawlApiKey);
+  if (!hasManagedOAuthCredential(session)) {
+    return createClient(credentialForOutboundRequest(session));
+  }
+  const client = createClient("request-scoped-hosted-oauth");
+  const axiosInstance = client.http?.instance;
+  if (!axiosInstance?.interceptors?.request?.use) {
+    throw new CredentialValidationUnavailableError();
+  }
+  axiosInstance.interceptors.request.use((config) => {
+    const credential = credentialForOutboundRequest(session);
+    if (!credential) throw new CredentialValidationUnavailableError();
+    config.headers = {
+      ...config.headers ?? {},
+      Authorization: `Bearer ${credential}`
+    };
+    return config;
+  });
+  return client;
 }
 function asText2(data) {
   return JSON.stringify(data, null, 2);
@@ -1208,10 +1639,10 @@ function transformScrapeParams(args2) {
   delete out.pdfOptions;
   return out;
 }
-var scrapeParamsSchema = z3.object({
-  url: z3.string().url(),
-  formats: z3.array(
-    z3.enum([
+var scrapeParamsSchema = z4.object({
+  url: z4.string().url(),
+  formats: z4.array(
+    z4.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -1225,62 +1656,62 @@ var scrapeParamsSchema = z3.object({
       "audio"
     ])
   ).optional(),
-  jsonOptions: z3.object({
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  jsonOptions: z4.object({
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }).optional(),
-  queryOptions: z3.object({
-    prompt: z3.string().max(1e4),
-    mode: z3.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z4.object({
+    prompt: z4.string().max(1e4),
+    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  screenshotOptions: z3.object({
-    fullPage: z3.boolean().optional(),
-    quality: z3.number().optional(),
-    viewport: z3.object({ width: z3.number(), height: z3.number() }).optional()
+  screenshotOptions: z4.object({
+    fullPage: z4.boolean().optional(),
+    quality: z4.number().optional(),
+    viewport: z4.object({ width: z4.number(), height: z4.number() }).optional()
   }).optional(),
-  parsers: z3.array(z3.enum(["pdf"])).optional(),
-  pdfOptions: z3.object({
-    maxPages: z3.number().int().min(1).max(1e4).optional()
+  parsers: z4.array(z4.enum(["pdf"])).optional(),
+  pdfOptions: z4.object({
+    maxPages: z4.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z3.boolean().optional(),
-  redactPII: z3.boolean().optional(),
-  includeTags: z3.array(z3.string()).optional(),
-  excludeTags: z3.array(z3.string()).optional(),
-  waitFor: z3.number().optional(),
+  onlyMainContent: z4.boolean().optional(),
+  redactPII: z4.boolean().optional(),
+  includeTags: z4.array(z4.string()).optional(),
+  excludeTags: z4.array(z4.string()).optional(),
+  waitFor: z4.number().optional(),
   ...SAFE_MODE ? {} : {
-    actions: z3.array(
-      z3.object({
-        type: z3.enum(allowedActionTypes),
-        selector: z3.string().optional(),
-        milliseconds: z3.number().optional(),
-        text: z3.string().optional(),
-        key: z3.string().optional(),
-        direction: z3.enum(["up", "down"]).optional(),
-        script: z3.string().optional(),
-        fullPage: z3.boolean().optional()
+    actions: z4.array(
+      z4.object({
+        type: z4.enum(allowedActionTypes),
+        selector: z4.string().optional(),
+        milliseconds: z4.number().optional(),
+        text: z4.string().optional(),
+        key: z4.string().optional(),
+        direction: z4.enum(["up", "down"]).optional(),
+        script: z4.string().optional(),
+        fullPage: z4.boolean().optional()
       })
     ).optional()
   },
-  mobile: z3.boolean().optional(),
-  skipTlsVerification: z3.boolean().optional(),
-  removeBase64Images: z3.boolean().optional(),
-  location: z3.object({
-    country: z3.string().optional(),
-    languages: z3.array(z3.string()).optional()
+  mobile: z4.boolean().optional(),
+  skipTlsVerification: z4.boolean().optional(),
+  removeBase64Images: z4.boolean().optional(),
+  location: z4.object({
+    country: z4.string().optional(),
+    languages: z4.array(z4.string()).optional()
   }).optional(),
-  storeInCache: z3.boolean().optional(),
-  zeroDataRetention: z3.boolean().optional(),
-  maxAge: z3.number().optional(),
-  lockdown: z3.boolean().optional(),
-  proxy: z3.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
-  profile: z3.object({
-    name: z3.string(),
-    saveChanges: z3.boolean().optional()
+  storeInCache: z4.boolean().optional(),
+  zeroDataRetention: z4.boolean().optional(),
+  maxAge: z4.number().optional(),
+  lockdown: z4.boolean().optional(),
+  proxy: z4.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
+  profile: z4.object({
+    name: z4.string(),
+    saveChanges: z4.boolean().optional()
   }).optional()
 });
-var parseOptionParamsSchema = z3.object({
-  formats: z3.array(
-    z3.enum([
+var parseOptionParamsSchema = z4.object({
+  formats: z4.array(
+    z4.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -1290,48 +1721,48 @@ var parseOptionParamsSchema = z3.object({
       "query"
     ])
   ).optional(),
-  jsonOptions: z3.object({
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  jsonOptions: z4.object({
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }).optional(),
-  queryOptions: z3.object({
-    prompt: z3.string().max(1e4),
-    mode: z3.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z4.object({
+    prompt: z4.string().max(1e4),
+    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  parsers: z3.array(z3.enum(["pdf"])).optional(),
-  pdfOptions: z3.object({
-    maxPages: z3.number().int().min(1).max(1e4).optional()
+  parsers: z4.array(z4.enum(["pdf"])).optional(),
+  pdfOptions: z4.object({
+    maxPages: z4.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z3.boolean().optional(),
-  redactPII: z3.boolean().optional(),
-  includeTags: z3.array(z3.string()).optional(),
-  excludeTags: z3.array(z3.string()).optional(),
-  removeBase64Images: z3.boolean().optional(),
-  skipTlsVerification: z3.boolean().optional(),
-  storeInCache: z3.boolean().optional(),
-  zeroDataRetention: z3.boolean().optional(),
-  maxAge: z3.number().optional(),
-  proxy: z3.enum(["basic", "auto"]).optional()
+  onlyMainContent: z4.boolean().optional(),
+  redactPII: z4.boolean().optional(),
+  includeTags: z4.array(z4.string()).optional(),
+  excludeTags: z4.array(z4.string()).optional(),
+  removeBase64Images: z4.boolean().optional(),
+  skipTlsVerification: z4.boolean().optional(),
+  storeInCache: z4.boolean().optional(),
+  zeroDataRetention: z4.boolean().optional(),
+  maxAge: z4.number().optional(),
+  proxy: z4.enum(["basic", "auto"]).optional()
 });
 var localParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z3.string().min(1).describe(
+  filePath: z4.string().min(1).describe(
     "Absolute or relative path to a local file to parse. Supported: .html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls"
   ),
-  contentType: z3.string().optional().describe(
+  contentType: z4.string().optional().describe(
     "Optional MIME type override. If omitted, the server infers the file kind from the extension."
   )
 });
 var hostedParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z3.string().min(1).optional().describe(
+  filePath: z4.string().min(1).optional().describe(
     "Phase 1 only: path to the local file on the caller/harness machine. Hosted MCP will not read or stat this path; it is used only to produce upload instructions."
   ),
-  uploadRef: z3.string().min(1).optional().describe(
+  uploadRef: z4.string().min(1).optional().describe(
     "Phase 2 only: short-lived upload reference returned by phase 1 after the local PUT upload completes."
   ),
-  contentType: z3.string().optional().describe(
+  contentType: z4.string().optional().describe(
     "Phase 1 MIME type override. If omitted, the server infers it from the file extension without reading the file."
   ),
-  declaredSizeBytes: z3.number().int().positive().optional().describe(
+  declaredSizeBytes: z4.number().int().positive().optional().describe(
     "Optional phase 1 size declaration. Hosted MCP does not stat the file; provide this only if the caller already knows it."
   )
 }).superRefine((value, ctx) => {
@@ -1339,7 +1770,7 @@ var hostedParseParamsSchema = parseOptionParamsSchema.extend({
   const hasUploadRef = typeof value.uploadRef === "string" && value.uploadRef.length > 0;
   if (hasFilePath === hasUploadRef) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
+      code: z4.ZodIssueCode.custom,
       message: "Hosted firecrawl_parse requires exactly one of filePath (phase 1) or uploadRef (phase 2).",
       path: hasFilePath && hasUploadRef ? ["uploadRef"] : ["filePath"]
     });
@@ -1412,8 +1843,9 @@ async function apiPostJson(pathName, body, apiKey) {
   return parsed;
 }
 async function apiPostJsonForSession(pathName, body, session) {
-  if (session?.firecrawlApiKey) {
-    return apiPostJson(pathName, body, session.firecrawlApiKey);
+  const credential = credentialForOutboundRequest(session);
+  if (credential) {
+    return apiPostJson(pathName, body, credential);
   }
   if (isKeylessMode(session)) {
     return keylessPost(pathName, body, session);
@@ -1456,13 +1888,21 @@ async function executeHostedParse(args2, session, log) {
       "Hosted firecrawl_parse requires exactly one of filePath or uploadRef."
     );
   }
-  if (!session?.firecrawlApiKey && !isKeylessMode(session)) {
+  if (!hasCredential(session) && !isKeylessMode(session)) {
     return asText2({
       success: false,
       mode: "hosted-upload-ref-auth-required",
       message: "Hosted firecrawl_parse requires an authenticated Firecrawl session or keyless eligibility before a local file upload URL can be minted. Connect a Firecrawl account, provide an API key, or use keyless hosted MCP while eligible, then call firecrawl_parse again."
     });
   }
+  if (isHostedKeylessSession(session) && args2.zeroDataRetention === true) {
+    const payload = {
+      ...recoveryPayload("KEYLESS_OPTION_NOT_AVAILABLE", session?.requestId),
+      option: "zeroDataRetention",
+      message: "Zero Data Retention is not available in anonymous keyless mode. Omit zeroDataRetention to parse with keyless access, or connect an account or configure an API key for a team where Zero Data Retention is enabled, then retry."
+    };
+    throw new UserError(String(payload.message), payload);
+  }
   const options = extractParseOptions(args2);
   if (hasFilePath && args2.filePath) {
     const filename = path.basename(args2.filePath);
@@ -1535,106 +1975,11 @@ server.addTool({
     // Does not modify, delete, or write to external websites.
   },
   description: `
-Scrape content from a single URL with advanced options.
-This is the most powerful, fastest and most reliable scraper tool, if available you should always default to using this tool for any web scraping needs.
-
-**Best for:** Single page content extraction, when you know exactly which page contains the information.
-**Not recommended for:** Multiple pages (call scrape multiple times or use crawl), unknown page location (use search).
-**Common mistakes:** Using markdown format when extracting specific data points (use JSON instead).
-**Other Features:** Use 'branding' format to extract brand identity (colors, fonts, typography, spacing, UI components) for design analysis or style replication.
-
-**CRITICAL - Format Selection (you MUST follow this):**
-When the user asks for SPECIFIC data points, you MUST use JSON format with a schema. Only use markdown when the user needs the ENTIRE page content.
-
-**Use JSON format when user asks for:**
-- Parameters, fields, or specifications (e.g., "get the header parameters", "what are the required fields")
-- Prices, numbers, or structured data (e.g., "extract the pricing", "get the product details")
-- API details, endpoints, or technical specs (e.g., "find the authentication endpoint")
-- Lists of items or properties (e.g., "list the features", "get all the options")
-- Any specific piece of information from a page
-
-**Use markdown format ONLY when:**
-- User wants to read/summarize an entire article or blog post
-- User needs to see all content on a page without specific extraction
-- User explicitly asks for the full page content
-
-**Handling JavaScript-rendered pages (SPAs):**
-If JSON extraction returns empty, minimal, or just navigation content, the page is likely JavaScript-rendered or the content is on a different URL. Try these steps IN ORDER:
-1. **Add waitFor parameter:** Set \`waitFor: 5000\` to \`waitFor: 10000\` to allow JavaScript to render before extraction
-2. **Try a different URL:** If the URL has a hash fragment (#section), try the base URL or look for a direct page URL
-3. **Use firecrawl_map to find the correct page:** Large documentation sites or SPAs often spread content across multiple URLs. Use \`firecrawl_map\` with a \`search\` parameter to discover the specific page containing your target content, then scrape that URL directly.
-   Example: If scraping "https://docs.example.com/reference" fails to find webhook parameters, use \`firecrawl_map\` with \`{"url": "https://docs.example.com/reference", "search": "webhook"}\` to find URLs like "/reference/webhook-events", then scrape that specific page.
-4. **Use firecrawl_agent:** As a last resort for heavily dynamic pages where map+scrape still fails, use the agent which can autonomously navigate and research
-
-**Usage Example (JSON format - REQUIRED for specific data extraction):**
-\`\`\`json
-{
-  "name": "firecrawl_scrape",
-  "arguments": {
-    "url": "https://example.com/api-docs",
-    "formats": ["json"],
-    "jsonOptions": {
-      "prompt": "Extract the header parameters for the authentication endpoint",
-      "schema": {
-        "type": "object",
-        "properties": {
-          "parameters": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "properties": {
-                "name": { "type": "string" },
-                "type": { "type": "string" },
-                "required": { "type": "boolean" },
-                "description": { "type": "string" }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-\`\`\`
+Retrieve and extract content from one supplied URL through Firecrawl. Use this when the request identifies a page and needs its content or defined fields. It can return markdown, HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema; JSON is useful when the requested result has defined fields, while markdown preserves readable page content.
 
-**Prefer markdown format by default.** You can read and reason over the full page content directly \u2014 no need for an intermediate query step. Use markdown for questions about page content, factual lookups, and any task where you need to understand the page.
+This tool operates on a known page. For a set of pages use \`firecrawl_crawl\`, and to discover page URLs use \`firecrawl_map\` or \`firecrawl_search\`. Options include JavaScript render delay, cache age, main-content filtering, PII redaction, and lockdown cache-only retrieval. Browser actions may change the live page when interactive actions are enabled.
 
-**Use JSON format when user needs:**
-- Structured data with specific fields (extract all products with name, price, description)
-- Data in a specific schema for downstream processing
-
-**Use query format only when:**
-- The page is extremely long and you need a single targeted answer without processing the full content
-- You want a quick factual answer and don't need to retain the page content
-- Set \`queryOptions.mode\` to \`"directQuote"\` when you need verbatim page text; otherwise it defaults to \`"freeform"\`
-
-**Usage Example (markdown format - default for most tasks):**
-\`\`\`json
-{
-  "name": "firecrawl_scrape",
-  "arguments": {
-    "url": "https://example.com/article",
-    "formats": ["markdown"],
-    "onlyMainContent": true
-  }
-}
-\`\`\`
-**Usage Example (branding format - extract brand identity):**
-\`\`\`json
-{
-  "name": "firecrawl_scrape",
-  "arguments": {
-    "url": "https://example.com",
-    "formats": ["branding"]
-  }
-}
-\`\`\`
-**Branding format:** Extracts comprehensive brand identity (colors, fonts, typography, spacing, logo, UI components) for design analysis or style replication.
-**Performance:** Add maxAge parameter for 500% faster scrapes using cached data.
-**Lockdown mode:** Set \`lockdown: true\` to serve the request only from the existing index/cache without any outbound network request. For air-gapped or compliance-constrained use where the request URL itself is considered sensitive. Errors on cache miss. Billed at 5 credits.
-**Privacy:** Set \`redactPII: true\` to return content with personally identifiable information redacted.
-**Returns:** JSON structured data, markdown, branding profile, or other formats as specified.
-${SAFE_MODE ? "**Safe Mode:** Read-only content extraction. Interactive actions (click, write, executeJavascript) are disabled for security." : ""}
+Returns the selected content formats and page metadata.
 `,
   parameters: scrapeParamsSchema,
   execute: async (args2, { session, log }) => {
@@ -1680,43 +2025,17 @@ server.addTool({
     // Read-only discovery; no deletion or destructive updates.
   },
   description: `
-Map a website to discover all indexed URLs on the site.
-
-**Best for:** Discovering URLs on a website before deciding what to scrape; finding specific sections or pages within a large site; locating the correct page when scrape returns empty or incomplete results.
-**Not recommended for:** When you already know which specific URL you need (use scrape); when you need the content of the pages (use scrape after mapping).
-**Common mistakes:** Using crawl to discover URLs instead of map; jumping straight to firecrawl_agent when scrape fails instead of using map first to find the right page.
+Enumerate URLs indexed under one website through Firecrawl without fetching each page's content. Use this when the request asks for a site's URL inventory, when several relevant pages must be located, or when the desired page URL is unknown. An optional \`search\` term narrows the URL list, while sitemap, subdomain, query-parameter, and result-limit options control coverage.
 
-**IMPORTANT - Use map before agent:** If \`firecrawl_scrape\` returns empty, minimal, or irrelevant content, use \`firecrawl_map\` with the \`search\` parameter to find the specific page URL containing your target content. This is faster and cheaper than using \`firecrawl_agent\`. Only use the agent as a last resort after map+scrape fails.
-
-**Prompt Example:** "Find the webhook documentation page on this API docs site."
-**Usage Example (discover all URLs):**
-\`\`\`json
-{
-  "name": "firecrawl_map",
-  "arguments": {
-    "url": "https://example.com"
-  }
-}
-\`\`\`
-**Usage Example (search for specific content - RECOMMENDED when scrape fails):**
-\`\`\`json
-{
-  "name": "firecrawl_map",
-  "arguments": {
-    "url": "https://docs.example.com/api",
-    "search": "webhook events"
-  }
-}
-\`\`\`
-**Returns:** Array of URLs found on the site, filtered by search query if provided.
+Returns matching URLs rather than page bodies. Retrieve one page with \`firecrawl_scrape\`; collect content across multiple pages with \`firecrawl_crawl\`.
 `,
-  parameters: z3.object({
-    url: z3.string().url(),
-    search: z3.string().optional(),
-    sitemap: z3.enum(["include", "skip", "only"]).optional(),
-    includeSubdomains: z3.boolean().optional(),
-    limit: z3.number().optional(),
-    ignoreQueryParameters: z3.boolean().optional()
+  parameters: z4.object({
+    url: z4.string().url(),
+    search: z4.string().optional(),
+    sitemap: z4.enum(["include", "skip", "only"]).optional(),
+    includeSubdomains: z4.boolean().optional(),
+    limit: z4.number().optional(),
+    ignoreQueryParameters: z4.boolean().optional()
   }),
   execute: async (args2, { session, log }) => {
     const { url, ...options } = args2;
@@ -1742,92 +2061,16 @@ server.addTool({
     // Query-only; no destructive side effects on external entities.
   },
   description: `
-Search the web and optionally extract content from search results. This is the most powerful web search tool available, and if available you should always default to using this tool for any web search needs.
-
-The query also supports search operators, that you can use if needed to refine the search:
-| Operator | Functionality | Examples |
----|-|-|
-| \`"\` | Non-fuzzy matches a string of text | \`"Firecrawl"\`
-| \`-\` | Excludes certain keywords or negates other operators | \`-bad\`, \`-site:firecrawl.dev\`
-| \`site:\` | Only returns results from a specified website | \`site:firecrawl.dev\`
-| \`inurl:\` | Only returns results that include a word in the URL | \`inurl:firecrawl\`
-| \`allinurl:\` | Only returns results that include multiple words in the URL | \`allinurl:git firecrawl\`
-| \`intitle:\` | Only returns results that include a word in the title of the page | \`intitle:Firecrawl\`
-| \`allintitle:\` | Only returns results that include multiple words in the title of the page | \`allintitle:firecrawl playground\`
-| \`related:\` | Only returns results that are related to a specific domain | \`related:firecrawl.dev\`
-| \`imagesize:\` | Only returns images with exact dimensions | \`imagesize:1920x1080\`
-| \`larger:\` | Only returns images larger than specified dimensions | \`larger:1920x1080\`
+Search web, news, or image sources and return ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit results to GitHub, research, PDF, or developer sources.
 
-**Best for:** Finding specific information across multiple websites, when you don't know which website has the information; when you need the most relevant content for a query.
-**Not recommended for:** When you need to search the filesystem. When you already know which website to scrape (use scrape); when you need comprehensive coverage of a single website (use map or crawl.
-**Common mistakes:** Using crawl or map for open-ended questions (use search instead).
-**Prompt Example:** "Find the latest research papers on AI published in 2023."
-**Sources:** web, images, news, default to web unless needed images or news.
-**Categories:** Optional filter to limit result types: \`github\` (GitHub repositories, code, issues, and docs), \`research\` (academic and research sources), \`pdf\` (PDF results). Example: \`categories: ["github", "research"]\`.
-**Domain filters:** Use includeDomains to restrict results to specific domains, or excludeDomains to remove domains. Do not use both in the same request. Domains must be hostnames only, without protocol or path.
-**Scrape Options:** Only use scrapeOptions when you think it is absolutely necessary. When you do so default to a lower limit to avoid timeouts, 5 or lower.
-**Optimal Workflow:** Search first using firecrawl_search without formats, then after fetching the results, use the scrape tool to get the content of the relevantpage(s) that you want to scrape
-**After the search:** Once you have processed the results (or decided they were not useful), call \`firecrawl_search_feedback\` with the \`id\` from this response. The first feedback per search refunds 1 credit and helps Firecrawl improve search quality.
+For a programming question, add \`categories: ["developer"]\`. It searches an index of GitHub issues, merged pull requests, repository READMEs, and curated documentation sites, and returns the hits in \`data.developer\` beside the web results.
 
-**Usage Example without formats (Preferred):**
-\`\`\`json
-{
-  "name": "firecrawl_search",
-  "arguments": {
-    "query": "top AI companies",
-    "limit": 5,
-    "includeDomains": ["example.com"],
-    "sources": [
-      { "type": "web" }
-    ]
-  }
-}
-\`\`\`
-**Usage Example with formats:**
-\`\`\`json
-{
-  "name": "firecrawl_search",
-  "arguments": {
-    "query": "latest AI research papers 2023",
-    "limit": 5,
-    "categories": ["github", "research"],
-    "lang": "en",
-    "country": "us",
-    "sources": [
-      { "type": "web" },
-      { "type": "images" },
-      { "type": "news" }
-    ],
-    "scrapeOptions": {
-      "formats": ["markdown"],
-      "onlyMainContent": true
-    }
-  }
-}
-\`\`\`
-**Returns:** A JSON envelope of the form \`{ success, data: { web?, images?, news? }, id, creditsUsed }\`. Each result array contains the search results (with optional scraped content). Pass the top-level \`id\` to \`firecrawl_search_feedback\` after you've used the results.
+\`scrapeOptions\` can attach extracted page content. Returns source-type result groups and usage metadata. Authenticated responses can include an \`id\` for optional search feedback.
 `,
-  parameters: z3.object({
-    query: z3.string().min(1),
-    highlights: z3.boolean().optional().describe(
-      "Return query-relevant highlights for each search result. Set to false to keep the original search snippets."
-    ),
-    limit: z3.number().optional(),
-    tbs: z3.string().optional(),
-    filter: z3.string().optional(),
-    location: z3.string().optional(),
-    includeDomains: z3.array(searchDomainSchema).optional(),
-    excludeDomains: z3.array(searchDomainSchema).optional(),
-    sources: z3.array(z3.object({ type: z3.enum(["web", "images", "news"]) })).optional(),
-    categories: z3.array(z3.enum(["github", "research", "pdf"])).optional().describe(
-      "Limit results to specific source types. `github` searches GitHub repositories, code, issues, and docs; `research` searches academic and research sources; `pdf` searches PDF results."
-    ),
-    scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional(),
-    enterprise: z3.array(z3.enum(["default", "anon", "zdr"])).optional()
-  }).refine(
-    (args2) => !(args2.includeDomains?.length && args2.excludeDomains?.length),
-    "includeDomains and excludeDomains cannot both be specified"
-  ),
+  parameters: z4.object({
+    ...searchToolBaseFields,
+    scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
+  }).refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE),
   execute: async (args2, { session, log }) => {
     const { query, ...opts } = args2;
     const searchOpts = { ...opts };
@@ -1854,7 +2097,9 @@ The query also supports search operators, that you can use if needed to refine t
     };
     if (isKeylessMode(session)) {
       const json = await keylessPost("/v2/search", searchBody, session);
-      return asText2(json ?? {});
+      const keylessResponse = { ...json ?? {} };
+      delete keylessResponse.id;
+      return asText2(keylessResponse);
     }
     const client = getClient(session);
     const httpRes = await client.http.post("/v2/search", searchBody);
@@ -1869,42 +2114,59 @@ function resolveApiBaseUrl() {
   );
 }
 function extractClientIp(request) {
-  const xff = request?.headers?.["x-forwarded-for"];
-  const raw = Array.isArray(xff) ? xff[0] : xff;
-  const first = typeof raw === "string" ? raw.split(",")[0].trim() : void 0;
-  return first || void 0;
+  return extractSingleTrustedClientIp(request?.headers?.["x-forwarded-for"]);
+}
+function keylessQuotaReason(reason) {
+  return reason === "requests" || reason === "credits";
 }
 async function keylessEligible(clientIp) {
   const secret = process.env.KEYLESS_PROXY_SECRET;
-  if (!secret) return false;
+  if (!secret) return { eligible: false, unavailable: true };
   try {
     const response = await fetch(
       `${resolveApiBaseUrl()}/v2/keyless/eligibility`,
       {
         headers: {
-          ...ORIGIN_HEADERS2,
+          ...ORIGIN_HEADERS3,
           "x-firecrawl-keyless-ip": clientIp,
           "x-firecrawl-keyless-secret": secret
         }
       }
     );
-    if (!response.ok) return false;
-    const json = await response.json().catch(() => ({}));
-    return json?.eligible === true;
+    if (!response.ok) return { eligible: false, unavailable: true };
+    const json = await response.json().catch(() => null);
+    if (typeof json?.eligible !== "boolean") {
+      return { eligible: false, unavailable: true };
+    }
+    return {
+      eligible: json?.eligible === true,
+      ...typeof json?.reason === "string" ? { reason: json.reason } : {},
+      ...Number.isFinite(json?.retryAfterSeconds) && json.retryAfterSeconds > 0 ? { retryAfterSeconds: json.retryAfterSeconds } : {}
+    };
   } catch {
-    return false;
+    return { eligible: false, unavailable: true };
   }
 }
 function isKeylessMode(session) {
-  if (session?.firecrawlApiKey) return false;
+  if (hasCredential(session) || session?.credentialError) return false;
   if (process.env.CLOUD_SERVICE === "true") {
-    return !!session?.keylessClientIp;
+    return session?.authType === "keyless";
   }
   return !process.env.FIRECRAWL_API_URL;
 }
 async function keylessPost(path2, body, session) {
+  if (isHostedKeylessSession(session)) {
+    const eligibility = session?.keylessClientIp ? await keylessEligible(session.keylessClientIp) : { eligible: false };
+    if (!eligibility.eligible) {
+      const code = eligibility.unavailable ? "KEYLESS_ELIGIBILITY_UNAVAILABLE" : keylessQuotaReason(eligibility.reason) ? "KEYLESS_QUOTA_EXHAUSTED" : "KEYLESS_ACCESS_NOT_AVAILABLE";
+      const payload = recoveryPayload(code, session?.requestId, {
+        retryAfterSeconds: eligibility.retryAfterSeconds
+      });
+      throw new UserError(String(payload.message), payload);
+    }
+  }
   const headers = {
-    ...ORIGIN_HEADERS2,
+    ...ORIGIN_HEADERS3,
     "Content-Type": "application/json"
   };
   if (session?.keylessClientIp && process.env.KEYLESS_PROXY_SECRET) {
@@ -1918,6 +2180,13 @@ async function keylessPost(path2, body, session) {
   });
   const json = await response.json().catch(() => ({}));
   if (!response.ok) {
+    if (isKeylessMode(session) && response.status === 429) {
+      const code = keylessQuotaReason(json?.reason) ? "KEYLESS_QUOTA_EXHAUSTED" : "KEYLESS_LIMIT_REACHED";
+      const payload = recoveryPayload(code, session?.requestId, {
+        retryAfterSeconds: Number.isFinite(json?.retry_after_seconds) && json.retry_after_seconds > 0 ? json.retry_after_seconds : void 0
+      });
+      throw new UserError(String(payload.message), payload);
+    }
     throw new Error(
       json?.error || `Firecrawl request failed (HTTP ${response.status})`
     );
@@ -1927,7 +2196,7 @@ async function keylessPost(path2, body, session) {
 async function getCrawlStatusWithOrigin(client, jobId) {
   const res = await client.http.get(
     `/v2/crawl/${encodeURIComponent(jobId)}`,
-    ORIGIN_HEADERS2
+    ORIGIN_HEADERS3
   );
   const body = res?.data ?? {};
   const initialDocs = Array.isArray(body.data) ? body.data : [];
@@ -1946,7 +2215,7 @@ async function getCrawlStatusWithOrigin(client, jobId) {
   const docs = initialDocs.slice();
   let current = body.next;
   while (current) {
-    const pageRes = await client.http.get(current, ORIGIN_HEADERS2);
+    const pageRes = await client.http.get(current, ORIGIN_HEADERS3);
     const payload = pageRes?.data ?? {};
     if (!payload.success) break;
     const pageData = Array.isArray(payload.data) ? payload.data : payload.data?.pages || [];
@@ -1979,17 +2248,17 @@ async function waitForCrawlCompletionWithOrigin(client, jobId, pollInterval = 2,
     );
   }
 }
-var feedbackIssueSchema = z3.string().trim().min(1).max(80).regex(
+var feedbackIssueSchema = z4.string().trim().min(1).max(80).regex(
   /^[a-z0-9][a-z0-9_-]*$/,
   "Issue codes must use lowercase letters, numbers, underscores, or hyphens"
 );
-var valuableSourceSchema = z3.object({
-  url: z3.string().url(),
-  reason: z3.string().max(1e3).optional()
+var valuableSourceSchema = z4.object({
+  url: z4.string().url(),
+  reason: z4.string().max(1e3).optional()
 });
-var missingContentSchema = z3.object({
-  topic: z3.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-  description: z3.string().max(2e3).optional()
+var missingContentSchema = z4.object({
+  topic: z4.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+  description: z4.string().max(2e3).optional()
 });
 var FEEDBACK_DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
 function feedbackEnvEnabled(...keys) {
@@ -2010,7 +2279,7 @@ if (SEARCH_FEEDBACK_DISABLED) {
     "[firecrawl-mcp] Search feedback tool disabled by FIRECRAWL_NO_SEARCH_FEEDBACK; firecrawl_search_feedback will not be registered."
   );
 }
-if (!SEARCH_FEEDBACK_DISABLED) {
+if (!SEARCH_FEEDBACK_DISABLED && !isLocalKeylessStartup()) {
   server.addTool({
     name: "firecrawl_search_feedback",
     annotations: {
@@ -2023,84 +2292,28 @@ if (!SEARCH_FEEDBACK_DISABLED) {
       // Additive only; records feedback and may refund credits, does not delete data.
     },
     description: `
-Send structured feedback on a previous \`firecrawl_search\` result. **Call this immediately after a search where you used the results** so we can improve search quality and refund 1 credit (search costs 2).
-
-Pass the \`searchId\` returned by \`firecrawl_search\` (the \`id\` field on the response) and tell us:
-
-- **rating** \u2014 overall result quality: \`good\`, \`partial\`, or \`bad\`.
-- **valuableSources** \u2014 which result URLs were actually useful, and a short reason why.
-- **missingContent** \u2014 **the most important field.** An ARRAY of specific pieces of content you expected to find but didn't. One entry per missing piece, each with a short \`topic\` and an optional longer \`description\`. Examples: \`{"topic":"enterprise pricing","description":"no pricing tier table for the Enterprise plan was returned"}\`, \`{"topic":"API rate limits"}\`, \`{"topic":"comparison vs competitors"}\`. **Be specific** \u2014 these aggregate across teams and tell us what to index next. Do not pack multiple topics into one entry.
-- **querySuggestions** \u2014 how the query or response shape could be improved (e.g. "would have liked official docs first", "should boost github.com").
-
-**Substantive-feedback requirement** (zero-effort feedback is rejected with HTTP 400):
-- \`good\` \u2014 must include at least one \`valuableSources\` entry
-- \`partial\` \u2014 must include \`valuableSources\` or at least one \`missingContent\` entry
-- \`bad\` \u2014 must include at least one \`missingContent\` entry or \`querySuggestions\`
+Records schema-validated quality feedback for a prior \`firecrawl_search\` UUID \`searchId\`. A \`good\` rating requires a valuable source, \`partial\` a valuable source or at least one \`missingContent\` entry, and \`bad\` at least one \`missingContent\` entry or a query suggestion; caps are 50 \`valuableSources\` and 20 \`missingContent\` entries.
 
-**Time window:** Feedback must be submitted within ~2 minutes of the search. Beyond that, the call returns HTTP 409 with \`feedbackErrorCode: "FEEDBACK_WINDOW_EXPIRED"\` \u2014 do not retry, just move on. Same goes for any 4xx response: do not retry-loop.
-
-**Behaviors:**
-- Idempotent per \`searchId\`. Re-submitting for the same id returns \`alreadySubmitted: true\` with \`creditsRefunded: 0\`.
-- Refund only applies to billable searches; preview teams are blocked.
-- Failed searches cannot receive feedback (the search itself already returned an error you can act on).
-- **Daily refund cap (per team, per UTC day, default 100 credits).** Once a team's \`creditsRefundedToday\` reaches \`dailyRefundCap\`, the response returns \`dailyCapReached: true\` with \`creditsRefunded: 0\`. The feedback is still recorded for search-quality improvement \u2014 only the credit refund is gated. **Stop calling this tool for the rest of the UTC day** when you see \`dailyCapReached: true\`.
-
-**When to call:** Right after processing a search result. If the result didn't help, send rating \`bad\` with a clear \`missingContent\` \u2014 that is just as valuable as a \`good\` rating.
-
-**Usage Example (good rating with valuable sources + missing content):**
-\`\`\`json
-{
-  "name": "firecrawl_search_feedback",
-  "arguments": {
-    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
-    "rating": "good",
-    "valuableSources": [
-      { "url": "https://docs.firecrawl.dev/features/search", "reason": "Most up-to-date description of /search." }
-    ],
-    "missingContent": [
-      { "topic": "Pricing for the search endpoint", "description": "No pricing tier table for /search specifically." },
-      { "topic": "Rate limits", "description": "Per-team RPS for /search not documented." }
-    ],
-    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
-  }
-}
-\`\`\`
-
-**Usage Example (bad rating, what was missing):**
-\`\`\`json
-{
-  "name": "firecrawl_search_feedback",
-  "arguments": {
-    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
-    "rating": "bad",
-    "missingContent": [
-      { "topic": "Recent benchmarks", "description": "All results were >12 months old." },
-      { "topic": "Comparison vs Algolia" }
-    ]
-  }
-}
-\`\`\`
-
-**Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
+Eligibility is limited to successful searches within the feedback age window. The record is idempotent per search ID. Eligible first feedback for a search can refund 1 credit; refunds are subject to the team's daily cap. The response reports whether a refund was applied, along with submission and daily-cap status.
 `,
-    parameters: z3.object({
-      searchId: z3.string().uuid("searchId must be the UUID returned by firecrawl_search"),
-      rating: z3.enum(["good", "bad", "partial"]),
-      valuableSources: z3.array(
-        z3.object({
-          url: z3.string().url(),
-          reason: z3.string().max(1e3).optional()
+    parameters: z4.object({
+      searchId: z4.string().uuid("searchId must be the UUID returned by firecrawl_search"),
+      rating: z4.enum(["good", "bad", "partial"]),
+      valuableSources: z4.array(
+        z4.object({
+          url: z4.string().url(),
+          reason: z4.string().max(1e3).optional()
         })
       ).max(50).optional(),
-      missingContent: z3.array(
-        z3.object({
-          topic: z3.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-          description: z3.string().max(2e3).optional()
+      missingContent: z4.array(
+        z4.object({
+          topic: z4.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+          description: z4.string().max(2e3).optional()
         })
       ).max(20).optional().describe(
         "Array of specific pieces of content the agent expected to find but did not. One entry per distinct topic. Each entry has a short `topic` and optional longer `description`."
       ),
-      querySuggestions: z3.string().max(2e3).optional()
+      querySuggestions: z4.string().max(2e3).optional()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -2126,12 +2339,12 @@ Pass the \`searchId\` returned by \`firecrawl_search\` (the \`id\` field on the
       }
       if (querySuggestions) body.querySuggestions = querySuggestions;
       const headers = {
-        ...ORIGIN_HEADERS2,
+        ...ORIGIN_HEADERS3,
         "Content-Type": "application/json"
       };
-      const apiKey = session?.firecrawlApiKey;
-      if (apiKey) {
-        headers["Authorization"] = `Bearer ${apiKey}`;
+      const credential = credentialForOutboundRequest(session);
+      if (credential) {
+        headers["Authorization"] = `Bearer ${credential}`;
       } else if (process.env.CLOUD_SERVICE === "true") {
         throw new Error("Unauthorized: missing API key for search feedback.");
       }
@@ -2170,7 +2383,7 @@ if (ENDPOINT_FEEDBACK_DISABLED) {
     "[firecrawl-mcp] Endpoint feedback tool disabled by FIRECRAWL_NO_ENDPOINT_FEEDBACK; firecrawl_feedback will not be registered."
   );
 }
-if (!ENDPOINT_FEEDBACK_DISABLED) {
+if (!ENDPOINT_FEEDBACK_DISABLED && !isLocalKeylessStartup()) {
   server.addTool({
     name: "firecrawl_feedback",
     annotations: {
@@ -2183,35 +2396,23 @@ if (!ENDPOINT_FEEDBACK_DISABLED) {
       // Additive only; submits ratings and notes, does not delete jobs or external content.
     },
     description: `
-Send structured feedback for a completed Firecrawl v2 job. Use this for endpoint-level feedback on \`scrape\`, \`parse\`, \`map\`, or \`search\` jobs when the job result was useful, partially useful, or failed to meet expectations.
-
-For search-result quality specifically, prefer \`firecrawl_search_feedback\` when available because it has search-focused guidance. This generic tool posts to \`/v2/feedback\` and accepts endpoint-wide signals:
-
-- **endpoint** \u2014 one of \`search\`, \`scrape\`, \`parse\`, or \`map\`.
-- **jobId** \u2014 the id returned by that endpoint.
-- **rating** \u2014 overall result quality: \`good\`, \`partial\`, or \`bad\`.
-- **issues** \u2014 stable lowercase issue codes such as \`missing_markdown\`, \`bad_pdf_parse\`, or \`wrong_links\`.
-- **tags** \u2014 optional lowercase tags for grouping feedback.
-- **note** \u2014 short human-readable context. Do not include huge page contents or raw scrape results.
-- **url**, **pageNumbers**, and **metadata** \u2014 small contextual fields that identify what the feedback refers to.
-
-Do not store multi-MB outputs in feedback. Use concise notes, issue codes, URLs, and page numbers.
+Submit concise quality feedback for a completed search, scrape, parse, or map job. Provide the endpoint, job ID, rating, and relevant issue codes or small contextual fields; omit large page contents and raw outputs.
 
-**Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
+Returns submission status, feedback ID, and accounting fields.
 `,
-    parameters: z3.object({
-      endpoint: z3.enum(["search", "scrape", "parse", "map"]),
-      jobId: z3.string().uuid("jobId must be the UUID returned by Firecrawl"),
-      rating: z3.enum(["good", "bad", "partial"]),
-      issues: z3.array(feedbackIssueSchema).max(20).optional(),
-      tags: z3.array(feedbackIssueSchema).max(20).optional(),
-      note: z3.string().max(4e3).optional(),
-      valuableSources: z3.array(valuableSourceSchema).max(50).optional(),
-      missingContent: z3.array(missingContentSchema).max(50).optional(),
-      querySuggestions: z3.string().max(2e3).optional(),
-      url: z3.string().url().optional(),
-      pageNumbers: z3.array(z3.number().int().positive()).max(100).optional(),
-      metadata: z3.record(z3.string(), z3.unknown()).optional()
+    parameters: z4.object({
+      endpoint: z4.enum(["search", "scrape", "parse", "map"]),
+      jobId: z4.string().uuid("jobId must be the UUID returned by Firecrawl"),
+      rating: z4.enum(["good", "bad", "partial"]),
+      issues: z4.array(feedbackIssueSchema).max(20).optional(),
+      tags: z4.array(feedbackIssueSchema).max(20).optional(),
+      note: z4.string().max(4e3).optional(),
+      valuableSources: z4.array(valuableSourceSchema).max(50).optional(),
+      missingContent: z4.array(missingContentSchema).max(50).optional(),
+      querySuggestions: z4.string().max(2e3).optional(),
+      url: z4.string().url().optional(),
+      pageNumbers: z4.array(z4.number().int().positive()).max(100).optional(),
+      metadata: z4.record(z4.string(), z4.unknown()).optional()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -2230,12 +2431,12 @@ Do not store multi-MB outputs in feedback. Use concise notes, issue codes, URLs,
       } = args2;
       const apiBase = resolveApiBaseUrl();
       const headers = {
-        ...ORIGIN_HEADERS2,
+        ...ORIGIN_HEADERS3,
         "Content-Type": "application/json"
       };
-      const apiKey = session?.firecrawlApiKey;
-      if (apiKey) {
-        headers["Authorization"] = `Bearer ${apiKey}`;
+      const credential = credentialForOutboundRequest(session);
+      if (credential) {
+        headers["Authorization"] = `Bearer ${credential}`;
       } else if (process.env.CLOUD_SERVICE === "true") {
         throw new Error("Unauthorized: missing API key for feedback.");
       }
@@ -2296,49 +2497,29 @@ server.addTool({
     // Reads pages from target sites; does not delete or alter external websites.
   },
   description: `
- Starts a crawl job on a website, polls until it reaches a terminal state, and returns the final crawl status/data.
- 
- **Best for:** Extracting content from multiple related pages, when you need comprehensive coverage.
- **Not recommended for:** Extracting content from a single page (use scrape); when token limits are a concern (use map + scrape for tighter control); when you need fast results (crawling can be slow).
- **Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + scrape for tighter control.
- **Common mistakes:** Setting limit or maxDiscoveryDepth too high (causes token overflow) or too low (causes missing pages); using crawl for a single page (use scrape instead). Using a /* wildcard is not recommended.
- **Prompt Example:** "Get all blog posts from the first two levels of example.com/blog."
- **Usage Example:**
- \`\`\`json
- {
-   "name": "firecrawl_crawl",
-   "arguments": {
-     "url": "https://example.com/blog/*",
-     "maxDiscoveryDepth": 5,
-     "limit": 20,
-     "allowExternalLinks": false,
-     "deduplicateSimilarURLs": true,
-     "sitemap": "include"
-   }
- }
- \`\`\`
- **Returns:** Final crawl status and data after internal polling, including the crawl id. Use firecrawl_check_crawl_status only when you need to re-check an existing crawl ID later.
- ${SAFE_MODE ? "**Safe Mode:** Read-only crawling. Webhooks and interactive actions are disabled for security." : ""}
- `,
-  parameters: z3.object({
-    url: z3.string(),
-    prompt: z3.string().optional(),
-    excludePaths: z3.array(z3.string()).optional(),
-    includePaths: z3.array(z3.string()).optional(),
-    maxDiscoveryDepth: z3.number().optional(),
-    sitemap: z3.enum(["skip", "include", "only"]).optional(),
-    limit: z3.number().optional(),
-    allowExternalLinks: z3.boolean().optional(),
-    allowSubdomains: z3.boolean().optional(),
-    crawlEntireDomain: z3.boolean().optional(),
-    delay: z3.number().optional(),
-    maxConcurrency: z3.number().optional(),
+Start a multi-page crawl at a website URL, poll it to a terminal state, and return the final status and collected data. Scope can be bounded with include/exclude paths, depth, page limit, subdomain/external-link controls, sitemap handling, delay, and scrape options.
+
+Crawl results can be large; use conservative limits when full-site coverage is unnecessary. Webhooks and interactive scrape actions are unavailable in safe mode. Returns the crawl ID, status, and page data.
+`,
+  parameters: z4.object({
+    url: z4.string(),
+    prompt: z4.string().optional(),
+    excludePaths: z4.array(z4.string()).optional(),
+    includePaths: z4.array(z4.string()).optional(),
+    maxDiscoveryDepth: z4.number().optional(),
+    sitemap: z4.enum(["skip", "include", "only"]).optional(),
+    limit: z4.number().optional(),
+    allowExternalLinks: z4.boolean().optional(),
+    allowSubdomains: z4.boolean().optional(),
+    crawlEntireDomain: z4.boolean().optional(),
+    delay: z4.number().optional(),
+    maxConcurrency: z4.number().optional(),
     ...SAFE_MODE ? {} : {
-      webhook: z3.string().optional(),
-      webhookHeaders: z3.record(z3.string(), z3.string()).optional()
+      webhook: z4.string().optional(),
+      webhookHeaders: z4.record(z4.string(), z4.string()).optional()
     },
-    deduplicateSimilarURLs: z3.boolean().optional(),
-    ignoreQueryParameters: z3.boolean().optional(),
+    deduplicateSimilarURLs: z4.boolean().optional(),
+    ignoreQueryParameters: z4.boolean().optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }),
   execute: async (args2, { session, log }) => {
@@ -2389,20 +2570,9 @@ server.addTool({
     // Status lookup only; no deletes or updates.
   },
   description: `
-Check the status of a crawl job.
-
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_check_crawl_status",
-  "arguments": {
-    "id": "550e8400-e29b-41d4-a716-446655440000"
-  }
-}
-\`\`\`
-**Returns:** Status and progress of the crawl job, including results if available.
+Retrieve the current status, progress, and available results for an existing crawl ID. This only reads Firecrawl job state and does not start or modify the crawl.
 `,
-  parameters: z3.object({ id: z3.string() }),
+  parameters: z4.object({ id: z4.string() }),
   execute: async (args2, { session }) => {
     const client = getClient(session);
     const id = args2.id;
@@ -2422,49 +2592,17 @@ server.addTool({
     // Read-only extraction; no destructive changes to external content.
   },
   description: `
-Extract structured information from web pages using LLM capabilities. Supports both cloud AI and self-hosted LLM extraction.
+Extract structured information from one or more URLs with an optional natural-language prompt and JSON schema. It can include subdomains, follow external links, or use web search when those options are enabled.
 
-**Best for:** Extracting specific structured data like prices, names, details from web pages.
-**Not recommended for:** When you need the full content of a page (use scrape); when you're not looking for specific structured data.
-**Arguments:**
-- urls: Array of URLs to extract information from
-- prompt: Custom prompt for the LLM extraction
-- schema: JSON schema for structured data extraction
-- allowExternalLinks: Allow extraction from external links
-- enableWebSearch: Enable web search for additional context
-- includeSubdomains: Include subdomains in extraction
-**Prompt Example:** "Extract the product name, price, and description from these product pages."
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_extract",
-  "arguments": {
-    "urls": ["https://example.com/page1", "https://example.com/page2"],
-    "prompt": "Extract product information including name, price, and description",
-    "schema": {
-      "type": "object",
-      "properties": {
-        "name": { "type": "string" },
-        "price": { "type": "number" },
-        "description": { "type": "string" }
-      },
-      "required": ["name", "price"]
-    },
-    "allowExternalLinks": false,
-    "enableWebSearch": false,
-    "includeSubdomains": false
-  }
-}
-\`\`\`
-**Returns:** Extracted structured data as defined by your schema.
+Use this for a defined structured result rather than full page content. Returns data shaped by the supplied schema or prompt.
 `,
-  parameters: z3.object({
-    urls: z3.array(z3.string()),
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional(),
-    allowExternalLinks: z3.boolean().optional(),
-    enableWebSearch: z3.boolean().optional(),
-    includeSubdomains: z3.boolean().optional()
+  parameters: z4.object({
+    urls: z4.array(z4.string()),
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional(),
+    allowExternalLinks: z4.boolean().optional(),
+    enableWebSearch: z4.boolean().optional(),
+    includeSubdomains: z4.boolean().optional()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2497,78 +2635,14 @@ server.addTool({
     // Gathers information only; does not delete external data or user resources.
   },
   description: `
-Autonomous web research agent. This is a separate AI agent layer that independently browses the internet, searches for information, navigates through pages, and extracts structured data based on your query. You describe what you need, and the agent figures out where to find it.
-
-**How it works:** The agent performs web searches, follows links, reads pages, and gathers data autonomously. This runs **asynchronously** - it returns a job ID immediately, and you poll \`firecrawl_agent_status\` to check when complete and retrieve results.
-
-**IMPORTANT - Async workflow with patient polling:**
-1. Call \`firecrawl_agent\` with your prompt/schema \u2192 returns job ID immediately
-2. Poll \`firecrawl_agent_status\` with the job ID to check progress
-3. **Keep polling for at least 2-3 minutes** - agent research typically takes 1-5 minutes for complex queries
-4. Poll every 15-30 seconds until status is "completed" or "failed"
-5. Do NOT give up after just a few polling attempts - the agent needs time to research
-
-**Expected wait times:**
-- Simple queries with provided URLs: 30 seconds - 1 minute
-- Complex research across multiple sites: 2-5 minutes
-- Deep research tasks: 5+ minutes
+Start an asynchronous web research job from a prompt, optional seed URLs, and an optional JSON schema. Use this for a requested synthesis across multiple sources when the task can wait for asynchronous completion. The agent can search, navigate, read pages, and assemble a structured result.
 
-**Best for:** Complex research tasks where you don't know the exact URLs; multi-source data gathering; finding information scattered across the web; extracting data from JavaScript-heavy SPAs that fail with regular scrape.
-**Not recommended for:**
-- Single-page extraction when you have a URL (use firecrawl_scrape, faster and cheaper)
-- Web search (use firecrawl_search first)
-- Interactive page tasks like clicking, filling forms, login, or navigating JS-heavy SPAs (use firecrawl_scrape + firecrawl_interact)
-- Extracting specific data from a known page (use firecrawl_scrape with JSON format)
-
-**Arguments:**
-- prompt: Natural language description of the data you want (required, max 10,000 characters)
-- urls: Optional array of URLs to focus the agent on specific pages
-- schema: Optional JSON schema for structured output
-
-**Prompt Example:** "Find the founders of Firecrawl and their backgrounds"
-**Usage Example (start agent, then poll patiently for results):**
-\`\`\`json
-{
-  "name": "firecrawl_agent",
-  "arguments": {
-    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
-    "schema": {
-      "type": "object",
-      "properties": {
-        "startups": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "name": { "type": "string" },
-              "funding": { "type": "string" },
-              "founded": { "type": "string" }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-\`\`\`
-Then poll with \`firecrawl_agent_status\` every 15-30 seconds for at least 2-3 minutes.
-
-**Usage Example (with URLs - agent focuses on specific pages):**
-\`\`\`json
-{
-  "name": "firecrawl_agent",
-  "arguments": {
-    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
-    "prompt": "Compare the features and pricing information from these pages"
-  }
-}
-\`\`\`
-**Returns:** Job ID for status checking. Use \`firecrawl_agent_status\` to poll for results.
+This call returns only a job ID, not the research result. Read the job with \`firecrawl_agent_status\` until it reaches \`completed\` or \`failed\`; research commonly takes several minutes. If the job cannot finish within the task's available time, \`firecrawl_search\` and \`firecrawl_scrape\` can gather evidence synchronously.
 `,
-  parameters: z3.object({
-    prompt: z3.string().min(1).max(1e4),
-    urls: z3.array(z3.string().url()).optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  parameters: z4.object({
+    prompt: z4.string().min(1).max(1e4),
+    urls: z4.array(z4.string().url()).optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2601,38 +2675,18 @@ server.addTool({
     // Read-only status check.
   },
   description: `
-Check the status of an agent job and retrieve results when complete. Use this to poll for results after starting an agent with \`firecrawl_agent\`.
-
-**IMPORTANT - Be patient with polling:**
-- Poll every 15-30 seconds
-- **Keep polling for at least 2-3 minutes** before considering the request failed
-- Complex research can take 5+ minutes - do not give up early
-- Only stop polling when status is "completed" or "failed"
+Retrieve progress or final results for a \`firecrawl_agent\` job ID. A \`processing\` response is non-terminal and does not contain the final research result. Check again after 15\u201330 seconds until the status is \`completed\` or \`failed\`; complex jobs can take several minutes. If the job cannot finish within the task's available time, use \`firecrawl_search\` and \`firecrawl_scrape\` to complete the requested output.
 
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_agent_status",
-  "arguments": {
-    "id": "550e8400-e29b-41d4-a716-446655440000"
-  }
-}
-\`\`\`
-**Possible statuses:**
-- processing: Agent is still researching - keep polling, do not give up
-- completed: Research finished - response includes the extracted data
-- failed: An error occurred (only stop polling on this status)
-
-**Returns:** Status, progress, and results (if completed) of the agent job.
+Returns job status, progress information, and result data when completed.
 `,
-  parameters: z3.object({ id: z3.string() }),
+  parameters: z4.object({ id: z4.string() }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
     const { id } = args2;
     log.info("Checking agent status", { id });
     const res = await client.http.get(
       `/v2/agent/${encodeURIComponent(id)}`,
-      ORIGIN_HEADERS2
+      ORIGIN_HEADERS3
     );
     return asText2(res?.data ?? {});
   }
@@ -2649,53 +2703,17 @@ server.addTool({
     // Transient page interactions only; does not delete monitors, jobs, or external sites.
   },
   description: `
-Interact with a page in a live browser session: click buttons, fill forms, extract dynamic content, or navigate deeper.
-
-**Best for:** Multi-step workflows on a single page \u2014 searching a site, clicking through results, filling forms, extracting data that requires interaction.
-**Two ways to target a page:**
-- Pass a \`url\` to interact directly. The session is opened for you in one call (use this for a fresh page).
-- Pass a \`scrapeId\` from a previous firecrawl_scrape to reuse that already-loaded page (cheaper when you just scraped it).
+Open or reuse a live browser session to navigate a page, click controls, fill fields, or run browser code. Provide either \`url\` or \`scrapeId\`, and either a natural-language \`prompt\` or executable \`code\`; code can run as Bash, Python, or Node with a bounded timeout.
 
-**Arguments:**
-- url: Page to interact with; opens a session for you (use this OR scrapeId)
-- scrapeId: Scrape job ID from a previous scrape, found in its metadata (use this OR url)
-- prompt: Natural language instruction describing the action to take (use this OR code)
-- code: Code to execute in the browser session (use this OR prompt)
-- language: "bash", "python", or "node" (optional, defaults to "node", only used with code)
-- timeout: Interact execution timeout in seconds, 1-300 (optional, defaults to 30)
-- scrapeOptions: Optional scrape controls used only with url mode, such as waitFor, maxAge, proxy, or zeroDataRetention
-
-**Usage Example (prompt, direct via url):**
-\`\`\`json
-{
-  "name": "firecrawl_interact",
-  "arguments": {
-    "url": "https://example.com/products",
-    "prompt": "Click on the first product and tell me its price"
-  }
-}
-\`\`\`
-
-**Usage Example (code):**
-\`\`\`json
-{
-  "name": "firecrawl_interact",
-  "arguments": {
-    "scrapeId": "scrape-id-from-previous-scrape",
-    "code": "agent-browser click @e5",
-    "language": "bash"
-  }
-}
-\`\`\`
-**Returns:** Execution result including output, stdout, stderr, exit code, and live view URLs.
+This acts on the live site, so actions such as form submission can create persistent external side effects. Returns execution output, stdout/stderr, exit status, and session viewing URLs.
 `,
-  parameters: z3.object({
-    scrapeId: z3.string().trim().min(1).optional(),
-    url: z3.string().trim().url().optional(),
-    prompt: z3.string().trim().min(1).optional(),
-    code: z3.string().trim().min(1).optional(),
-    language: z3.enum(["bash", "python", "node"]).optional(),
-    timeout: z3.number().min(1).max(300).optional(),
+  parameters: z4.object({
+    scrapeId: z4.string().trim().min(1).optional(),
+    url: z4.string().trim().url().optional(),
+    prompt: z4.string().trim().min(1).optional(),
+    code: z4.string().trim().min(1).optional(),
+    language: z4.enum(["bash", "python", "node"]).optional(),
+    timeout: z4.number().min(1).max(300).optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }).refine((data) => Boolean(data.scrapeId) !== Boolean(data.url), {
     message: "Provide either 'url' (interact directly) or 'scrapeId' (reuse a previous scrape), not both."
@@ -2770,21 +2788,10 @@ server.addTool({
     // Terminates the live browser session; this end state cannot be resumed.
   },
   description: `
-Stop an interact session for a scraped page. Call this when you are done interacting to free resources.
-
-**Usage Example:**
-\`\`\`json
-{
-  "name": "firecrawl_interact_stop",
-  "arguments": {
-    "scrapeId": "scrape-id-here"
-  }
-}
-\`\`\`
-**Returns:** Success confirmation.
+Stop the live interact session associated with a \`scrapeId\` and release its resources. Returns a success confirmation.
 `,
-  parameters: z3.object({
-    scrapeId: z3.string()
+  parameters: z4.object({
+    scrapeId: z4.string()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2792,7 +2799,7 @@ Stop an interact session for a scraped page. Call this when you are done interac
     log.info("Stopping interact session", { scrapeId });
     const res = await client.http.delete(
       `/v2/scrape/${encodeURIComponent(scrapeId)}/interact`,
-      ORIGIN_HEADERS2
+      ORIGIN_HEADERS3
     );
     return asText2(res?.data ?? {});
   }
@@ -2809,56 +2816,11 @@ server.addTool({
     // Read-only parsing; no deletion or writes to the source file.
   },
   description: `
-Parse a file using Firecrawl's /v2/parse endpoint.
-
-In local/non-cloud MCP mode, this tool reads filePath from the MCP server filesystem and posts multipart data to the configured self-hosted FIRECRAWL_API_URL, preserving the existing direct-read behavior.
-
-In hosted CLOUD_SERVICE mode, this tool is a two-call flow because hosted MCP cannot read your local filesystem:
-1. Call with filePath, contentType, parse options, and optional declaredSizeBytes. The hosted server mints a short-lived upload URL and returns a safe local curl PUT command plus nextToolCall.
-2. Run the returned curl command locally, then call firecrawl_parse again with uploadRef and the desired parse options. The hosted server calls /v2/parse server-side with your session credential.
-
-**Best for:** Extracting content from a local document (PDF, Word, Excel, HTML, etc.); pulling structured data out of a file with JSON format; converting binary documents into markdown for downstream reasoning.
-**Not recommended for:** Remote URLs (use firecrawl_scrape); multiple files at once (call parse multiple times); documents that require interactive actions, screenshots, or change tracking \u2014 those aren't supported by the parse endpoint.
-**Common mistakes:** In hosted mode, do not pass both filePath and uploadRef. Phase 1 uses filePath only to generate upload instructions; phase 2 uses uploadRef only to parse server-side.
-
-**Supported file types:** .html, .htm, .xhtml, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls
-**Unsupported options:** actions, screenshot/branding/changeTracking formats, waitFor > 0, location, mobile, proxy values other than "auto" or "basic".
-**Privacy:** Set \`redactPII: true\` to return content with personally identifiable information redacted.
+Parse one supported document into markdown, HTML, links, summary, targeted answers, or JSON matching a schema. Supported inputs include common HTML, PDF, Word, RTF, OpenDocument, and spreadsheet files; PDF parsing can be bounded with \`pdfOptions.maxPages\`.
 
-**CRITICAL - Format Selection (same rules as firecrawl_scrape):**
-When the user asks for SPECIFIC data points from a document, you MUST use JSON format with a schema. Only use markdown when the user needs the ENTIRE document content.
+Local MCP reads \`filePath\` from the server filesystem. Hosted MCP uses two calls: first provide \`filePath\` to receive upload instructions, upload locally, then call again with the returned \`uploadRef\`; do not send both fields together. Remote web URLs belong in \`firecrawl_scrape\`.
 
-**Handling PDFs:**
-Add \`"parsers": ["pdf"]\` (optionally with \`pdfOptions.maxPages\`) when parsing a PDF so the PDF engine is invoked explicitly. For very long documents, cap \`maxPages\` to keep the response within token limits.
-
-**Hosted phase 1 example:**
-\`\`\`json
-{
-  "name": "firecrawl_parse",
-  "arguments": {
-    "filePath": "/absolute/path/to/document.pdf",
-    "contentType": "application/pdf",
-    "formats": ["markdown"],
-    "parsers": ["pdf"],
-    "zeroDataRetention": true
-  }
-}
-\`\`\`
-
-**Hosted phase 2 example:**
-\`\`\`json
-{
-  "name": "firecrawl_parse",
-  "arguments": {
-    "uploadRef": "upload-ref-from-phase-1",
-    "formats": ["markdown"],
-    "parsers": ["pdf"],
-    "zeroDataRetention": true
-  }
-}
-\`\`\`
-
-**Returns:** Phase 1 hosted upload instructions or a parsed document with markdown, html, links, summary, json, or query results depending on the requested formats.
+Set \`redactPII\` to request redaction of personally identifiable information in the returned content. \`zeroDataRetention\` requires an eligible authenticated account; omit it for anonymous keyless use. Returns upload instructions for hosted phase one or parsed document content for the final call.
 `,
   parameters: parseParamsSchema,
   execute: async (args2, { session, log }) => {
@@ -2889,10 +2851,10 @@ Add \`"parsers": ["pdf"]\` (optionally with \`pdfOptions.maxPages\`) when parsin
     });
     form.append("file", blob, filename);
     form.append("options", JSON.stringify(optionsPayload));
-    const headers = { ...ORIGIN_HEADERS2 };
-    const apiKey = session?.firecrawlApiKey;
-    if (apiKey) {
-      headers["Authorization"] = `Bearer ${apiKey}`;
+    const headers = { ...ORIGIN_HEADERS3 };
+    const credential = credentialForOutboundRequest(session);
+    if (credential) {
+      headers["Authorization"] = `Bearer ${credential}`;
     }
     const endpoint = `${apiUrl.replace(/\/$/, "")}/v2/parse`;
     log.info("Parsing local file", {
@@ -2918,6 +2880,63 @@ Add \`"parsers": ["pdf"]\` (optionally with \`pdfOptions.maxPages\`) when parsin
     }
   }
 });
+function registerMarketplaceSearchTool(registrar, getClientFn) {
+  registrar.addTool({
+    name: "firecrawl_search",
+    annotations: {
+      title: "Search the web",
+      readOnlyHint: true,
+      openWorldHint: true,
+      destructiveHint: false
+    },
+    description: `
+Search web and specialized indexes, returning ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit result types to \`github\`, \`research\`, \`pdf\`, or \`developer\`.
+
+For a programming question, add \`categories: ["developer"]\`. It searches an index of GitHub issues, merged pull requests, repository READMEs, and curated documentation sites, and returns the hits in \`data.developer\` beside the web results.
+
+Returns \`{ success, data, id, creditsUsed }\`, with source arrays in \`data\`.
+`,
+    parameters: z4.object({ ...searchToolBaseFields }).strict().refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE),
+    execute: async (args2, { session, log }) => {
+      const {
+        query,
+        includeDomains,
+        excludeDomains,
+        limit,
+        tbs,
+        filter,
+        location,
+        sources,
+        categories,
+        highlights,
+        enterprise
+      } = args2;
+      const searchQuery = buildSearchQueryWithDomains(
+        query,
+        includeDomains,
+        excludeDomains
+      );
+      const searchBody = {
+        query: searchQuery,
+        ...removeEmptyTopLevel({
+          limit,
+          tbs,
+          filter,
+          location,
+          sources,
+          categories,
+          highlights,
+          enterprise
+        }),
+        origin: ORIGIN
+      };
+      log.info("Searching", { query: searchQuery });
+      const client = getClientFn(session);
+      const httpRes = await client.http.post("/v2/search", searchBody);
+      return asText2(httpRes?.data ?? {});
+    }
+  });
+}
 var PORT = Number(process.env.PORT || 3e3);
 var HOST = process.env.CLOUD_SERVICE === "true" ? "0.0.0.0" : process.env.HOST || "localhost";
 var args;
@@ -2927,6 +2946,7 @@ if (process.env.CLOUD_SERVICE === "true" || process.env.SSE_LOCAL === "true" ||
     httpStream: {
       port: PORT,
       host: HOST,
+      endpoint: primaryProfile.endpoint,
       stateless: true
     }
   };
@@ -2937,4 +2957,53 @@ if (process.env.CLOUD_SERVICE === "true" || process.env.SSE_LOCAL === "true" ||
 }
 registerMonitorTools(server);
 registerResearchTools(server, getClient);
+registerDeveloperTools(server, getClient);
+if (process.env.CLOUD_SERVICE === "true" && primaryProfile.allowKeyless && !normalizeHeader(process.env.KEYLESS_PROXY_SECRET)) {
+  console.warn(
+    "[firecrawl-mcp] KEYLESS_PROXY_SECRET is missing; keyless requests will be unavailable and /ready will fail."
+  );
+}
+if (primaryProfile.id === "search") {
+  const primarySearchRegistrar = {
+    addTool: ((tool) => {
+      if (primaryProfile.toolAllowlist?.has(tool.name)) {
+        addTool(guardHostedTool(tool, { logActions: false }));
+      }
+    })
+  };
+  registerMarketplaceSearchTool(primarySearchRegistrar, getClient);
+}
 await server.start(args);
+var searchProfileEnabled = process.env.CLOUD_SERVICE === "true" && primaryProfile.id === "full" && process.env.FIRECRAWL_MCP_SEARCH_ENABLED !== "false";
+if (searchProfileEnabled) {
+  const searchProfile = makeSearchProfile();
+  const searchServer = createServer(searchProfile);
+  const searchRegistrar = {
+    addTool: ((tool) => {
+      if (searchProfile.toolAllowlist?.has(tool.name)) {
+        searchServer.addTool(
+          guardHostedTool(tool, { logActions: false })
+        );
+      }
+    })
+  };
+  registerResearchTools(searchRegistrar, getClient);
+  registerDeveloperTools(searchRegistrar, getClient);
+  registerMarketplaceSearchTool(searchRegistrar, getClient);
+  try {
+    await searchServer.start({
+      transportType: "httpStream",
+      httpStream: {
+        port: searchProfile.port,
+        host: HOST,
+        endpoint: searchProfile.endpoint,
+        stateless: true
+      }
+    });
+  } catch (error) {
+    console.error(
+      `[search-profile] failed to start on port ${searchProfile.port}; the full surface is unaffected`,
+      error
+    );
+  }
+}