fix(keyless): put recovery URLs in the message text agents actually read (#359)

* fix(keyless): put recovery URLs in the message text agents actually read

Agent hosts surface only the error message string to the model;
structuredContent (next_actions, docs_url, client_commands) is not
passed through. Verified empirically: an agent asked to repeat the
error verbatim reported 'no URLs present in the response'.

Add the OAuth endpoint and the free-API-key signup URL directly to the
four recovery messages (quota exhausted, keyless unavailable, invalid
credential, account-tool required), matching the API-side precedent in
apps/api keyless.ts. With the change, agents relay both URLs and the
Authorization header format to users unprompted.

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

* fix(keyless): align CREDENTIAL_INVALID message with sibling recovery guidance

Add the Authorization: Bearer wiring instruction so a user replacing a
broken key sees the same how-to as the quota and access messages.

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

* chore: 3.23.5

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.4",
+  "version": "3.23.5",
   "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

@@ -973,16 +973,16 @@ function recoveryPayload(
     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.'
+        ? `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 or configure an API key.`
+          ? `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 or configure an API key.'
+              ? `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 or configure Authorization: Bearer <FIRECRAWL_API_KEY>, then retry.',
+              : `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] }),