firecrawl-mcp 3.23.6 → 3.23.8

package/README.md

@@ -35,11 +35,11 @@ Connect to the remote hosted server with no setup:
 https://mcp.firecrawl.dev/v2/mcp
 ```
 
-On the keyless free tier, `scrape`, `search`, and `interact` work without an API key (rate-limited). Other tools such as `crawl`, `map`, and `agent` still need a key.
+On the keyless free tier, `scrape`, `search`, and `parse` work without an API key (rate-limited). Other tools such as `crawl`, `map`, and `agent` still need a key.
 
 Prefer OAuth or an API key whenever the human can sign up. It unlocks the full tool set and higher limits.
 
-For an interactive account connection, use:
+For an interactive account connection, configure your MCP client to use this server URL. This is an MCP endpoint, **not a browser page**; use the client's account-connection flow and do not add a second Firecrawl server entry when reconnecting:
 
 ```
 https://mcp.firecrawl.dev/v2/mcp-oauth
@@ -57,7 +57,7 @@ Then configure the client's secure header or secret setting with:
 Authorization: Bearer <FIRECRAWL_API_KEY>
 ```
 
-Never put an API key in the server URL. See the [hosted MCP setup guide](https://docs.firecrawl.dev/developer-guides/mcp-setup-guides/oauth) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for client-specific instructions.
+Never put an API key in the server URL. Never put an API key in an agent chat. Configure it directly in the client or secret manager. See the [hosted MCP setup guide](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for client-specific instructions.
 
 #### Search-only endpoint
 

package/dist/index.js

@@ -802,6 +802,11 @@ Search indexed public GitHub issue, pull-request, and README content. Returns ra
   });
 }
 
+// src/www-authenticate.ts
+function escapeWWWAuthenticateValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
 // src/index.ts
 dotenv.config({ debug: false, quiet: true });
 var require2 = createRequire(import.meta.url);
@@ -849,6 +854,9 @@ 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";
+var MCP_CONNECTION_GUIDE_URL = "https://docs.firecrawl.dev/mcp-server";
+var MCP_OAUTH_SERVER_URL = "https://mcp.firecrawl.dev/v2/mcp-oauth";
+var API_KEY_SIGNUP_URL = "https://www.firecrawl.dev/app/api-keys";
 function withoutTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
@@ -884,23 +892,23 @@ function getOAuthProtectedResourceMetadataUrl(profile) {
   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, profile) {
+function createOAuthChallengeResponse(error, profile, details = {}) {
   if (!isMcpOAuthEnabled()) {
     return void 0;
   }
   const errorMessage = error instanceof Error ? error.message : String(error || "Unauthorized");
   const wwwAuthenticate = [
-    `resource_metadata="${escapeWWWAuthenticateValue(getOAuthProtectedResourceMetadataUrl(profile))}"`,
+    ...profile.advertiseOAuth ? [
+      `resource_metadata="${escapeWWWAuthenticateValue(getOAuthProtectedResourceMetadataUrl(profile))}"`
+    ] : [],
     'error="invalid_token"',
     `error_description="${escapeWWWAuthenticateValue(errorMessage)}"`
   ].join(", ");
   return new Response(
     JSON.stringify({
       error: "invalid_token",
-      error_description: errorMessage
+      error_description: errorMessage,
+      ...details
     }),
     {
       headers: {
@@ -911,11 +919,26 @@ function createOAuthChallengeResponse(error, profile) {
     }
   );
 }
-function createInvalidCredentialResponse(error) {
+function createInvalidCredentialResponse(_error) {
+  const recovery = invalidApiKeyRecoveryPayload();
   return new Response(
     JSON.stringify({
       error: "invalid_api_key",
-      error_description: error.message
+      error_description: recovery.message,
+      ...recovery
+    }),
+    {
+      headers: { "Content-Type": "application/json" },
+      status: 401
+    }
+  );
+}
+function createInvalidOAuthRecoveryResponse(recovery) {
+  return new Response(
+    JSON.stringify({
+      error: "invalid_token",
+      error_description: recovery.message,
+      ...recovery
     }),
     {
       headers: { "Content-Type": "application/json" },
@@ -941,6 +964,12 @@ var InvalidFirecrawlCredentialError = class extends Error {
     this.name = "InvalidFirecrawlCredentialError";
   }
 };
+var InvalidOAuthCredentialError = class extends Error {
+  constructor() {
+    super("Invalid OAuth access token");
+    this.name = "InvalidOAuthCredentialError";
+  }
+};
 var MCP_GLOBAL_SCOPE = "firecrawl:global";
 function values(value) {
   if (typeof value === "string") return value.split(/\s+/).filter(Boolean);
@@ -1019,7 +1048,7 @@ async function resolveCredentialFromHeaders(headers, profile) {
   }
   if (!data.active || !data.api_key) {
     if (isFirecrawlOAuthAccessToken(token)) {
-      throw new Error("Invalid OAuth access token");
+      throw new InvalidOAuthCredentialError();
     }
     return { invalid: true };
   }
@@ -1059,6 +1088,14 @@ async function authenticateRequest(request, profile) {
   if (process.env.CLOUD_SERVICE === "true") {
     if (!headerCred && !managedCred) {
       if (resolved?.invalid) {
+        if (profile.allowKeyless) {
+          return {
+            authType: "api-key",
+            credentialError: "CREDENTIAL_INVALID",
+            firecrawlApiKey: void 0,
+            keylessClientIp: extractClientIp(request)
+          };
+        }
         throw new InvalidFirecrawlCredentialError();
       }
       if (profile.allowKeyless) {
@@ -1171,6 +1208,15 @@ function makeAuthenticate(profile) {
       if (error instanceof InvalidFirecrawlCredentialError) {
         throw createInvalidCredentialResponse(error);
       }
+      if (error instanceof InvalidOAuthCredentialError) {
+        const recovery = invalidOAuthRecoveryPayload(profile);
+        const oauthChallenge2 = createOAuthChallengeResponse(
+          new Error(recovery.message),
+          profile,
+          recovery
+        );
+        throw oauthChallenge2 ?? createInvalidOAuthRecoveryResponse(recovery);
+      }
       if (error instanceof CredentialValidationUnavailableError) {
         throw new Response(
           JSON.stringify({
@@ -1296,6 +1342,7 @@ function makeFullProfile() {
     allowKeyless: !account,
     acceptApiKeys: true,
     acceptLegacyAudience: account && process.env.MCP_OAUTH_ACCEPT_LEGACY_V2_MCP_AUD !== "false",
+    advertiseOAuth: account,
     primary: true
   };
 }
@@ -1323,6 +1370,7 @@ function makeSearchProfile({ primary = false } = {}) {
     // deployment explicitly enables the same profile flag used by primary.
     acceptApiKeys: !oauthOnly,
     requireManagedOAuth: oauthOnly,
+    advertiseOAuth: true,
     primary
   };
 }
@@ -1337,7 +1385,7 @@ function createServer(profile) {
     logger: new ConsoleLogger(),
     roots: { enabled: false },
     oauth: {
-      enabled: isMcpOAuthEnabled(),
+      enabled: isMcpOAuthEnabled() && profile.advertiseOAuth,
       protectedResource: {
         authorizationServers: [getOAuthIssuer()],
         bearerMethodsSupported: ["header"],
@@ -1369,27 +1417,87 @@ function isHostedKeylessSession(session) {
 function isLocalKeylessStartup() {
   return process.env.CLOUD_SERVICE !== "true" && !isHttpStreamingTransport() && !resolveCredentialFromEnv() && !normalizeHeader(process.env.FIRECRAWL_API_URL);
 }
+var NEVER_SHARE_API_KEY_SENTENCE = "Never ask for, accept, or put an API key in chat or in an MCP URL.";
+var RETRY_AFTER_CONFIRM_SUFFIX = "start a new client session or run and retry the original task.";
+var HUMAN_CONNECTION_GUIDANCE = `A human or operator must complete the connection because this session cannot reconnect Firecrawl itself. Ask the human to choose before changing anything: (1) in the MCP client's settings, update or replace the existing Firecrawl server entry so its URL is ${MCP_OAUTH_SERVER_URL}, then complete sign-in through the client. That URL is a client configuration value, not a page to open in a browser. Do not add a second Firecrawl server or change configuration without approval; or (2) have an operator create an API key at ${API_KEY_SIGNUP_URL} and configure it in the client or secret manager outside this chat. ${NEVER_SHARE_API_KEY_SENTENCE} After the human confirms setup, ${RETRY_AFTER_CONFIRM_SUFFIX} Connection guide: ${MCP_CONNECTION_GUIDE_URL}`;
+var ACCOUNT_ONLY_TOOL_GUIDANCE = `This tool needs a connected Firecrawl account. Search, Scrape, and Parse remain available, so continue with those if they can complete the task. Only if this task specifically requires this tool, tell the user that a human must update the existing Firecrawl connection using ${MCP_CONNECTION_GUIDE_URL}. Never ask for or accept an API key in chat. After setup, start a new client session and retry.`;
+var HUMAN_RECONNECT_ACCOUNT_ACTION = {
+  kind: "human_reconnect_account",
+  actor: "human",
+  requires_user_consent: true,
+  existing_server_only: true,
+  server_url: MCP_OAUTH_SERVER_URL,
+  open_server_url_in_browser: false,
+  docs_url: MCP_CONNECTION_GUIDE_URL
+};
+var OPERATOR_CONFIGURE_API_KEY_ACTION = {
+  kind: "operator_configure_api_key",
+  actor: "human_or_operator",
+  requires_user_consent: true,
+  credential_delivery: "outside_agent_chat",
+  signup_url: API_KEY_SIGNUP_URL
+};
+var HUMAN_CONNECTION_ACTIONS = [
+  HUMAN_RECONNECT_ACCOUNT_ACTION,
+  OPERATOR_CONFIGURE_API_KEY_ACTION
+];
+function connectionRecoveryPayload(params) {
+  return {
+    code: params.code,
+    auth_mode: params.authMode,
+    message: params.message,
+    docs_url: MCP_CONNECTION_GUIDE_URL,
+    next_actions: params.nextActions
+  };
+}
+function invalidApiKeyRecoveryPayload() {
+  return connectionRecoveryPayload({
+    code: "CREDENTIAL_INVALID",
+    authMode: "api_key",
+    message: `The Firecrawl API key configured for this server is invalid or revoked. Ask a human or operator to replace it in this existing server configuration or secret manager outside this chat. ${NEVER_SHARE_API_KEY_SENTENCE} After the human confirms the change, ${RETRY_AFTER_CONFIRM_SUFFIX}`,
+    nextActions: [OPERATOR_CONFIGURE_API_KEY_ACTION]
+  });
+}
+function invalidOAuthRecoveryPayload(profile) {
+  if (isMcpOAuthEnabled() && profile.advertiseOAuth) {
+    return connectionRecoveryPayload({
+      code: "OAUTH_CONNECTION_INVALID",
+      authMode: "oauth",
+      message: `This Firecrawl account connection is no longer valid. Ask the human to sign in again through this MCP client's account-connection flow. Do not add a second Firecrawl server or open the MCP server URL directly in a browser. After sign-in, ${RETRY_AFTER_CONFIRM_SUFFIX}`,
+      nextActions: [HUMAN_RECONNECT_ACCOUNT_ACTION, OPERATOR_CONFIGURE_API_KEY_ACTION]
+    });
+  }
+  return connectionRecoveryPayload({
+    code: "OAUTH_CONNECTION_INVALID",
+    authMode: "oauth",
+    message: `This Firecrawl account connection is no longer valid, and this server does not start account sign-in. Ask the human to choose before changing anything: (1) have an operator create a Firecrawl API key at ${API_KEY_SIGNUP_URL} and configure it on this existing server outside this chat; or (2) update this existing server's URL to ${MCP_OAUTH_SERVER_URL} and complete sign-in through the MCP client. That URL is a client configuration value, not a page to open in a browser. ${NEVER_SHARE_API_KEY_SENTENCE} After the human confirms the change, ${RETRY_AFTER_CONFIRM_SUFFIX}`,
+    nextActions: [OPERATOR_CONFIGURE_API_KEY_ACTION, HUMAN_RECONNECT_ACCOUNT_ACTION]
+  });
+}
 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. Reconnect the account via OAuth (https://mcp.firecrawl.dev/v2/mcp-oauth) or create a new API key at https://www.firecrawl.dev/signin and send it as Authorization: Bearer <FIRECRAWL_API_KEY>, 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 (https://mcp.firecrawl.dev/v2/mcp-oauth) or create a free API key at https://www.firecrawl.dev/signin and send it as Authorization: Bearer <FIRECRAWL_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 (https://mcp.firecrawl.dev/v2/mcp-oauth) or create a free API key at https://www.firecrawl.dev/signin and send it as Authorization: Bearer <FIRECRAWL_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 via OAuth (https://mcp.firecrawl.dev/v2/mcp-oauth) or create a free API key at https://www.firecrawl.dev/signin and send it as Authorization: Bearer <FIRECRAWL_API_KEY>, then retry.`,
-    ...isKeylessAccessUnavailable ? {} : { available_tools: [...KEYLESS_TOOL_NAMES] },
-    docs_url: "https://docs.firecrawl.dev/mcp-server",
+    message: code === "CREDENTIAL_INVALID" ? `The supplied Firecrawl credential is invalid or revoked. ${HUMAN_CONNECTION_GUIDANCE}` : isQuotaExhausted ? `The free daily limit for this network has been reached${retryAfterSeconds ? `; try again in about ${retryAfterSeconds} seconds` : ""}. To continue now: ${HUMAN_CONNECTION_GUIDANCE}` : isToolUnavailable ? ACCOUNT_ONLY_TOOL_GUIDANCE : isKeylessAccessUnavailable ? `Anonymous keyless access is unavailable for this request. To continue: ${HUMAN_CONNECTION_GUIDANCE}` : isKeylessEligibilityUnavailable ? "The anonymous keyless eligibility check is temporarily unavailable. Retry shortly." : `This tool requires a Firecrawl account or API key. ${HUMAN_CONNECTION_GUIDANCE}`,
+    // CREDENTIAL_INVALID sessions gate every tool call (including keyless
+    // tools) on the credentialError check before the keyless branch ever
+    // runs, so none of KEYLESS_TOOL_NAMES are actually callable here. Listing
+    // them as available_tools would send the agent into a retry loop against
+    // tools that will just return this same recovery payload.
+    ...isKeylessAccessUnavailable || code === "CREDENTIAL_INVALID" ? {} : { available_tools: [...KEYLESS_TOOL_NAMES] },
+    docs_url: MCP_CONNECTION_GUIDE_URL,
     ...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>" }
+    next_actions: isKeylessEligibilityUnavailable ? [{ kind: "retry_later", after_seconds: 30 }] : isQuotaExhausted || isKeylessAccessUnavailable ? HUMAN_CONNECTION_ACTIONS : isToolUnavailable ? [
+      { kind: "continue_keyless", tools: [...KEYLESS_TOOL_NAMES] },
+      ...HUMAN_CONNECTION_ACTIONS
+    ] : [
+      ...HUMAN_CONNECTION_ACTIONS
     ]
   };
 }
@@ -1454,7 +1562,16 @@ function guardHostedTool(tool, { logActions }) {
   const beforeValidate = tool.beforeValidate;
   return {
     ...tool,
-    canList: (session) => !session?.credentialError && (!isHostedKeylessSession(session) || keylessTool) && (canList?.(session) ?? true),
+    canList: (session) => (
+      // A credentialError session lists the keyless tool surface (same as a
+      // real keyless session, not the full authenticated schema) so the
+      // client proceeds past tools/list and calling any listed tool returns
+      // the CREDENTIAL_INVALID recovery payload (below). An empty list would
+      // leave MCP clients that stop after tools/list unable to ever surface
+      // the recovery guidance; the full non-keyless schema would over-disclose
+      // to a request carrying an unrecognized or invalid credential.
+      (session?.credentialError || isHostedKeylessSession(session) ? keylessTool : true) && (canList?.(session) ?? true)
+    ),
     beforeValidate: async (args2, session) => {
       const code = session?.credentialError ? "CREDENTIAL_INVALID" : isHostedKeylessSession(session) && !keylessTool ? "KEYLESS_TOOL_NOT_AVAILABLE" : void 0;
       if (code) {

package/dist/www-authenticate.js

@@ -0,0 +1,7 @@
+// src/www-authenticate.ts
+function escapeWWWAuthenticateValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+export {
+  escapeWWWAuthenticateValue
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.23.6",
+  "version": "3.23.8",
   "description": "MCP server for Firecrawl — search, scrape, and interact with the web. Supports both cloud and self-hosted instances. Features include web search, scraping, page interaction, batch processing, and LLM-powered content analysis.",
   "type": "module",
   "mcpName": "io.github.firecrawl/firecrawl-mcp-server",