{"record":{"id":"9d5be58192613616","repo":"danny-avila/LibreChat","slug":"mcp-servername-toolname-tool-call-failed","errorCode":null,"errorMessage":"[MCP][${serverName}][${toolName}] tool call failed${error?.message ? `: ${error?.message}` : '.'}","messagePattern":"\\[MCP\\]\\[(.+?)\\]\\[(.+?)\\] tool call failed(.+?)` : '\\.'\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"api/server/services/MCP.js","lineNumber":1153,"sourceCode":"        error.message === 'OAuth flow initiated - return early' ||\n        error.message === 'Pending OAuth flow reused - return early';\n\n      if (isOAuthError) {\n        if (\n          capturedServerConfig &&\n          !requiresOAuthMachinery(capturedServerConfig) &&\n          !isOAuthFlowSignal\n        ) {\n          throw new Error(\n            `[MCP][${serverName}][${toolName}] upstream authentication failed; MCP OAuth is not configured for this server.`,\n          );\n        }\n        throw new Error(\n          `[MCP][${serverName}][${toolName}] OAuth authentication required. Please check the server logs for the authentication URL.`,\n        );\n      }\n\n      throw new Error(\n        `[MCP][${serverName}][${toolName}] tool call failed${error?.message ? `: ${error?.message}` : '.'}`,\n      );\n    }\n  };\n\n  const toolInstance = tool(_call, {\n    schema,\n    name: normalizedToolKey,\n    description: description || '',\n    responseFormat: AgentConstants.CONTENT_AND_ARTIFACT,\n  });\n  toolInstance.mcp = true;\n  toolInstance.mcpRawServerName = serverName;\n  // Ephemeral request-scoped servers (runtime body placeholders) tear their\n  // connection down at request end, so they must never be backgrounded. A\n  // missing/stale config means the server's lifetime is unknowable, so fail\n  // closed (foreground) rather than risk a detached call against a torn-down\n  // connection.","sourceCodeStart":1135,"sourceCodeEnd":1171,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/api/server/services/MCP.js#L1135-L1171","documentation":"The MCP tool _call catch-all (MCP.js:1153) rethrows with this message when the caught error is neither an OAuth-class error nor recoverable — it appends the upstream error.message if present. It is the generic surface for any MCP tool call failure: transport errors, server-side execution failures, malformed tool arguments, timeouts, aborts.","triggerScenarios":"mcpManager.callTool rejects for any non-auth reason: the MCP server returned a non-401 error, the SSE/stdio transport died, the tool arguments failed server-side validation, an AbortSignal fired, or the server threw during execution.","commonSituations":"Network outage to a remote MCP server. A tool whose arguments changed upstream. Long-running tool hit the request timeout. Server restarted mid-call. Schema mismatch after an MCP server upgrade.","solutions":["Read the appended error.message — it is the upstream's own failure reason and is the primary diagnostic.","If transient (timeout/reset), retry the call; if the server is remote, check connectivity.","Validate the tool arguments against the server's current schema; update the call if the server changed.","If an AbortSignal is being passed, ensure it is not being cancelled prematurely upstream."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"function assertToolArgs(schema, args) {\n  for (const [k, t] of Object.entries(schema)) {\n    if (typeof args?.[k] !== t) throw new Error(`arg ${k} expected ${t}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await callMcpTool(...);\n} catch (e) {\n  if (/timeout|reset|ECONNRESET|429|503/.test(e.message)) { await backoff(); return retry(); }\n  throw e;\n}","preventionTips":["Validate tool arguments against the server's current schema before calling.","Pass a realistic AbortSignal timeout rather than letting requests hang.","Log the appended upstream error.message for every MCP tool failure."],"tags":["mcp","tools","transport","runtime"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}