fix(mcp): make invalid API key recovery reach the agent (#365)

* fix(mcp): make invalid API key recovery reach the agent

An invalid or revoked API key on /v2/mcp returned HTTP 401 at initialize and
tools/list. MCP clients treat a 401 at connect as "server unavailable" and
never surface the response body to the model, so the CREDENTIAL_INVALID
recovery payload — the whole point of #363 for this case — was unreachable in
a real agent session. The agent saw "no Firecrawl tools connected" and fell
back to generic, often outdated setup advice.

Fix: on the keyless+API-key endpoint, admit a supplied-but-invalid credential
as a session flagged credentialError instead of throwing a 401. The connection
succeeds, tools list, and every tool call returns the CREDENTIAL_INVALID
recovery payload as a 200 isError result — the same agent-legible path keyless
quota recovery already uses. No credential is forwarded and no tool executes,
so this grants zero functional access (strictly less than the previously
rejected "downgrade to keyless" option).

Scope: only profiles that accept API keys as a valid auth mode (allowKeyless).
OAuth-only surfaces such as /v2/mcp-search keep their hard 401 credential
rejection unchanged.

Verified end to end: a live claude session wired to an invalid-key server now
receives the payload and relays both recovery options to the human without
asking for a key in chat. Smoke suite updated to the 200/isError contract;
no net-new failures vs main.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(mcp): bump to 3.23.8 for the invalid-key recovery fix

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mcp): stop CREDENTIAL_INVALID payload from advertising unusable keyless tools

The credentialError guard in guardHostedTool's execute() runs before the
keyless branch, so no tool (including keyless ones) is actually callable in a
CREDENTIAL_INVALID session. recoveryPayload() was still including
available_tools: KEYLESS_TOOL_NAMES for this code, which could send the agent
into a retry loop against tools that just return the same recovery error.
Omit available_tools when code is CREDENTIAL_INVALID, matching the existing
isKeylessAccessUnavailable carve-out.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(mcp): scope CREDENTIAL_INVALID tools/list to the keyless surface; pin next_actions shape

canList previously returned true for every registered tool in a
credentialError session, so tools/list disclosed the full authenticated tool
schema (including non-keyless tools) to any request carrying an unrecognized
or invalid credential -- more schema disclosure than a real keyless session
gets. Scope it to the same keyless-tool surface a keyless session already
lists; recovery guidance still surfaces on any listed tool call since
execute() gates on credentialError before the keyless branch either way.

Also tighten the invalid-key next_actions assertion in mcp-smoke.test.mjs
from a loose non-empty-array check to pinning the human_reconnect_account /
operator_configure_api_key kinds and their consent flags, so a regression
that drops or reorders the recovery actions is caught.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: hmishra2250

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.23.7",
+  "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",

src/index.ts

@@ -535,11 +535,25 @@ async function authenticateRequest(
   if (process.env.CLOUD_SERVICE === 'true') {
     if (!headerCred && !managedCred) {
       if (resolved?.invalid) {
-        // A supplied credential must never silently downgrade a hosted session
-        // to an empty tool list. MCP clients commonly stop after tools/list, so
-        // the old in-band recovery payload was unreachable for invalid header
-        // credentials. Keep unauthenticated requests on the keyless path; only
-        // reject requests that actually supplied an invalid credential.
+        // A supplied-but-invalid credential must reach the *agent*, not die as a
+        // transport 401. MCP clients treat a 401 at initialize/tools-list as
+        // "server unavailable" and never surface the response body to the model,
+        // so the recovery payload in that 401 was unreachable in a real session.
+        // On the keyless+API-key endpoint, admit the session flagged with
+        // credentialError: the connection succeeds, tools list, and every tool
+        // call returns the CREDENTIAL_INVALID recovery payload as a 200 isError
+        // result — the same agent-legible path keyless quota recovery uses. No
+        // credential is forwarded and no tool executes, so this grants zero
+        // functional access. OAuth-only surfaces (e.g. /v2/mcp-search) keep the
+        // hard 401 credential-rejection contract they already advertise.
+        if (profile.allowKeyless) {
+          return {
+            authType: 'api-key',
+            credentialError: 'CREDENTIAL_INVALID',
+            firecrawlApiKey: undefined,
+            keylessClientIp: extractClientIp(request),
+          };
+        }
         throw new InvalidFirecrawlCredentialError();
       }
       if (profile.allowKeyless) {
@@ -1128,7 +1142,12 @@ function recoveryPayload(
               : isKeylessEligibilityUnavailable
                 ? 'The anonymous keyless eligibility check is temporarily unavailable. Retry shortly.'
               : `This tool requires a Firecrawl account or API key. ${HUMAN_CONNECTION_GUIDANCE}`,
-    ...(isKeylessAccessUnavailable
+    // 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,
@@ -1232,8 +1251,16 @@ function guardHostedTool(
   return {
     ...tool,
     canList: (session: SessionData) =>
-      !session?.credentialError &&
-      (!isHostedKeylessSession(session) || keylessTool) &&
+      // 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 (args: unknown, session: SessionData) => {
       const code = session?.credentialError

tests/mcp-smoke.test.mjs

@@ -2081,24 +2081,11 @@ test('account OAuth tokens cannot replay on keyless and invalid keys get correct
   });
   assert.equal(replay.status, 401);
 
-  const invalidApiKeyRecovery = {
-    error: 'invalid_api_key',
-    error_description:
-      '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 ask for, accept, or put an API key in chat or in an MCP URL. After the human confirms the change, start a new client session or run and retry the original task.',
-    code: 'CREDENTIAL_INVALID',
-    auth_mode: '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 ask for, accept, or put an API key in chat or in an MCP URL. After the human confirms the change, start a new client session or run and retry the original task.',
-    docs_url: 'https://docs.firecrawl.dev/mcp-server',
-    next_actions: [{
-      kind: 'operator_configure_api_key',
-      actor: 'human_or_operator',
-      requires_user_consent: true,
-      credential_delivery: 'outside_agent_chat',
-      signup_url: 'https://www.firecrawl.dev/app/api-keys',
-    }],
-  };
-
+  // On the keyless+API-key endpoint an invalid key is now agent-legible: the
+  // session connects (200) and lists tools, so an MCP client (which commonly
+  // stops after a 401 at tools/list) proceeds; any tool call then returns the
+  // CREDENTIAL_INVALID recovery payload as a 200 isError result. A raw 401 with
+  // the payload in the body was unreachable to the model.
   const invalidList = await fetch(`http://127.0.0.1:${port}/v2/mcp`, {
     body: JSON.stringify({ id: 2, jsonrpc: '2.0', method: 'tools/list', params: {} }),
     headers: {
@@ -2108,9 +2095,12 @@ test('account OAuth tokens cannot replay on keyless and invalid keys get correct
     },
     method: 'POST',
   });
-  assert.equal(invalidList.status, 401);
-  assert.equal(invalidList.headers.has('www-authenticate'), false);
-  assert.deepEqual(await invalidList.json(), invalidApiKeyRecovery);
+  assert.equal(invalidList.status, 200);
+  const invalidListJson = parseSseJson(await invalidList.text());
+  assert.ok(
+    (invalidListJson.result?.tools?.length ?? 0) > 0,
+    'invalid key still lists tools so the client proceeds to a callable tool'
+  );
 
   const invalidCall = await httpToolCall(port, {
     headers: {
@@ -2120,9 +2110,33 @@ test('account OAuth tokens cannot replay on keyless and invalid keys get correct
     id: 3,
     params: { arguments: { query: 'x' }, name: 'firecrawl_search' },
   });
-  assert.equal(invalidCall.status, 401);
-  assert.equal(invalidCall.headers.has('www-authenticate'), false);
-  assert.deepEqual(await invalidCall.json(), invalidApiKeyRecovery);
+  assert.equal(invalidCall.status, 200);
+  const invalidCallJson = parseSseJson(await invalidCall.text());
+  const invalidRecovery = invalidCallJson.result.structuredContent;
+  assert.equal(invalidCallJson.result.isError, true);
+  assert.equal(invalidRecovery.code, 'CREDENTIAL_INVALID');
+  assert.match(invalidRecovery.message, /invalid or revoked/);
+  // The consent-first boundary must survive: never route the key through chat.
+  assert.match(
+    invalidRecovery.message,
+    /Never ask for, accept, or put an API key in chat/
+  );
+  // Recovery pins the concrete next-action contract: reconnect (human) then
+  // operator-configure, each with its consent flag, not just a non-empty array.
+  assert.equal(invalidRecovery.next_actions[0].kind, 'human_reconnect_account');
+  assert.equal(invalidRecovery.next_actions[0].actor, 'human');
+  assert.equal(invalidRecovery.next_actions[0].requires_user_consent, true);
+  assert.equal(invalidRecovery.next_actions[1].kind, 'operator_configure_api_key');
+  assert.equal(invalidRecovery.next_actions[1].actor, 'human_or_operator');
+  assert.equal(invalidRecovery.next_actions[1].requires_user_consent, true);
+  // No tool is actually callable in a credentialError session (the
+  // credentialError check gates execute() before the keyless branch), so the
+  // payload must not advertise keyless tools as available.
+  assert.equal(
+    invalidRecovery.available_tools,
+    undefined,
+    'CREDENTIAL_INVALID must not advertise tools the agent cannot call'
+  );
 
   const invalidLegacyPath = await fetch(`http://127.0.0.1:${port}/v2/mcp`, {
     body: JSON.stringify({ id: 4, jsonrpc: '2.0', method: 'tools/list', params: {} }),
@@ -2134,9 +2148,9 @@ test('account OAuth tokens cannot replay on keyless and invalid keys get correct
     },
     method: 'POST',
   });
-  assert.equal(invalidLegacyPath.status, 401);
-  assert.equal(invalidLegacyPath.headers.has('www-authenticate'), false);
-  assert.deepEqual(await invalidLegacyPath.json(), invalidApiKeyRecovery);
+  assert.equal(invalidLegacyPath.status, 200);
+  const invalidLegacyJson = parseSseJson(await invalidLegacyPath.text());
+  assert.ok((invalidLegacyJson.result?.tools?.length ?? 0) > 0);
   await delay(25);
   const rejectedTelemetry = stdout
     .split(/\r?\n/)