fix(search): relay API error messages for every search, not only Alexandria ones (#546)

* fix(search): relay API error messages for every search

firecrawl_search only sent errors through relayExchangeError when the
sources included alexandria. Searches with explicit non-Alexandria
sources (e.g. ["web"]) went through relayTermsRequired, which rethrows
the raw axios error, so a 402 surfaced as "Request failed with status
code 402" and dropped the API's message and upgrade link.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* chore: release 3.30.2

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

Author: nickscamara

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [3.30.2] - 2026-10-15
+
+### Fixed
+
+- `firecrawl_search` relays the API's error message for every search. Searches with explicit sources that excluded `alexandria` (for example `["web"]`) previously surfaced only `Request failed with status code 402`, dropping the out-of-credits message and upgrade link. The fallback for an error without a message now reads `Firecrawl request failed (HTTP N)`.
+
 ## [3.30.1] - 2026-10-14
 
 ### Added

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "3.30.1",
+  "version": "3.30.2",
   "description": "Official Firecrawl MCP for web search, scraping, crawling, and structured data extraction.",
   "mcpServers": {
     "firecrawl": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.30.1",
+  "version": "3.30.2",
   "description": "MCP server for Firecrawl — search, scrape, and interact with the web, and search scientific papers. Supports both cloud and self-hosted instances. Features include web search, scraping, page interaction, batch processing, LLM-powered content analysis, and research paper search over biomedical and arXiv literature (PubMed, bioRxiv, medRxiv, arXiv) with citation-graph expansion and full-text reading.",
   "type": "module",
   "mcpName": "io.github.firecrawl/firecrawl-mcp-server",

server.json

@@ -3,7 +3,7 @@
   "name": "io.github.firecrawl/firecrawl-mcp-server",
   "title": "Firecrawl MCP Server",
   "description": "MCP server for Firecrawl — web search, scraping, and biomedical/arXiv paper search.",
-  "version": "3.30.1",
+  "version": "3.30.2",
   "repository": {
     "url": "https://github.com/firecrawl/firecrawl-mcp-server.git",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "firecrawl-mcp",
-      "version": "3.30.1",
+      "version": "3.30.2",
       "transport": {
         "type": "stdio"
       },

src/server.ts

@@ -1632,10 +1632,7 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
           searchBody,
           opts.sources === undefined && opts.domainTools !== true
         );
-      const context = { tool: 'firecrawl_search' };
-      const httpRes = exchangeSource
-        ? await relayExchangeError(postSearch, context)
-        : await relayTermsRequired(postSearch, context);
+      const httpRes = await relayExchangeError(postSearch, { tool: 'firecrawl_search' });
       return structuredCompact(withoutDiscoveredToolPrices(httpRes?.data ?? {}));
     },
   });

src/service/search-surface.ts

@@ -10,7 +10,6 @@ import {
   normalizeSearchSources,
   postSearchWithFallback,
   relayExchangeError,
-  relayTermsRequired,
   removeEmptyTopLevel,
   requestOrigin,
   SEARCH_DOMAINS_CONFLICT_MESSAGE,
@@ -158,10 +157,7 @@ Returns result groups in \`data\` and an operation \`id\`.
           searchBody,
           sources === undefined && domainTools !== true
         );
-      const context = { tool: 'firecrawl_search' };
-      const httpRes = exchangeSource
-        ? await relayExchangeError(postSearch, context)
-        : await relayTermsRequired(postSearch, context);
+      const httpRes = await relayExchangeError(postSearch, { tool: 'firecrawl_search' });
       return structuredCompact(httpRes?.data ?? {});
     },
   });

src/tool-helpers.ts

@@ -261,7 +261,7 @@ export async function relayExchangeError(
     const message =
       typeof data?.error === 'string'
         ? data.error
-        : `Alexandria request failed (HTTP ${response.status})`;
+        : `Firecrawl request failed (HTTP ${response.status})`;
     const disabledProvider = response.status === 403
       ? context.providers?.find(provider => message === `Access to ${provider} is disabled for this organization.`)
       : undefined;

tests/helpers/exchange-api.mjs

@@ -66,7 +66,7 @@ async function startFakeExchangeApi(options = {}) {
     if (req.method === 'POST' && (!parsedBody || typeof parsedBody !== 'object' || Array.isArray(parsedBody))) return json(400, {error:'Expected a JSON object body'});
 
     if (options.largeResult && (url.pathname === '/v2/search' || url.pathname.startsWith('/exchange/discover'))) return json(200, options.largeResult);
-    if (options.apiStatus) return json(options.apiStatus, { success: false, error: 'Invalid API key' });
+    if (options.apiStatus) return json(options.apiStatus, { success: false, error: options.apiError ?? 'Invalid API key' });
 
     if (url.pathname === '/exchange/skills/resolve')
       return json(200, { skills: [{ id: 'particle-podcasts' }] });

tests/mcp-alexandria-search.test.mjs

@@ -51,6 +51,17 @@ test('default tools fall back only on discovery refusal; explicit tools and othe
   assert.equal(other.api.requests.length, 1);
 });
 
+test('search relays the API error message whatever sources are requested', async (t) => {
+  const apiError = 'Insufficient credits to perform this request. For more credits, you can upgrade your plan at https://firecrawl.dev/pricing.';
+  const { client } = await startStdioWithApi(t, { apiStatus: 402, apiError });
+  for (const overrides of [{}, { sources: ['web'] }, { sources: ['news'] }, { sources: ['alexandria'] }]) {
+    const result = await callExpectingError(client, {
+      name: 'firecrawl_search', arguments: { query: 'company news', ...overrides },
+    });
+    assert.match(result.content[0].text, /upgrade your plan at https:\/\/firecrawl\.dev\/pricing/, JSON.stringify(overrides));
+  }
+});
+
 test('toolDetail forwards valid values and rejects invalid values before API calls', async (t) => {
   const { api, client } = await startStdioWithApi(t);
   for (const [name, args] of [