{"record":{"id":"713ffd195e40f42b","repo":"musistudio/claude-code-router","slug":"mcp-http-request-failed-this-server-name-r","errorCode":null,"errorMessage":"MCP HTTP request failed (${this.server.name}): ${response.status} ${text.slice(0, 300)}","messagePattern":"MCP HTTP request failed \\((.+?)\\): (.+?) (.+?)","errorType":"http","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/mcp/toolhub-mcp.ts","lineNumber":1208,"sourceCode":"      if (apiKey && !headers.has(\"authorization\")) {\n        headers.set(\"authorization\", `Bearer ${apiKey}`);\n      }\n      if (this.sessionId) {\n        headers.set(\"mcp-session-id\", this.sessionId);\n      }\n      const response = await fetch(this.server.url, {\n        body: JSON.stringify(request),\n        headers,\n        method: \"POST\",\n        signal: controller.signal\n      });\n      this.sessionId = response.headers.get(\"mcp-session-id\") || response.headers.get(\"x-mcp-session-id\") || this.sessionId;\n      if (notification && response.status === 204) {\n        return undefined;\n      }\n      const text = await response.text();\n      if (!response.ok) {\n        throw new Error(`MCP HTTP request failed (${this.server.name}): ${response.status} ${text.slice(0, 300)}`);\n      }\n      if (!text.trim()) {\n        return undefined;\n      }\n      return parseHttpJsonRpcResponse(text);\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\nclass StdioMcpClient implements McpClient {\n  private child: ChildProcessWithoutNullStreams | undefined;\n  private initialized = false;\n  private nextId = 1;\n  private readonly pending = new Map<string, PendingRequest>();\n  private stdoutBuffer = Buffer.alloc(0);\n","sourceCodeStart":1190,"sourceCodeEnd":1226,"githubUrl":"https://github.com/musistudio/claude-code-router/blob/99f24806c6a2c660b16e53e95211c517448a6c90/packages/core/src/mcp/toolhub-mcp.ts#L1190-L1226","documentation":"Thrown when the underlying HTTP request to an MCP server completes but returns a non-2xx status. The message includes the server name, the HTTP status code, and up to 300 characters of the response body to aid diagnosis. This is the transport-level counterpart to the JSON-RPC error (error 200).","triggerScenarios":"The MCP HTTP endpoint returns 4xx/5xx: 404 wrong endpoint path, 401/403 missing or expired auth token, 400 malformed JSON-RPC body, 502/503 gateway unavailable, or a proxy rejecting the streamable-HTTP request.","commonSituations":"Misconfigured server URL (missing /mcp path suffix); expired API key or bearer token; MCP server behind a reverse proxy that buffers/blocks SSE; server restart mid-session with stale mcp-session-id; rate limiting from the provider.","solutions":["Check the status code in the message: 401/403 → fix credentials; 404 → fix the endpoint URL; 5xx → server-side issue, retry later","Read the sliced response body in the message for the server's own error detail","Verify any session id is still valid; re-initialize to obtain a fresh mcp-session-id","If behind a proxy, ensure it supports POST + SSE streaming to the MCP path"],"exampleFix":"// before\nconst client = new ToolHubMcpClient({ url: \"https://mcp.example.com\" });\n\n// after\nconst client = new ToolHubMcpClient({ url: \"https://mcp.example.com/mcp\", headers: { Authorization: `Bearer ${token}` } });","handlingStrategy":"retry","validationCode":"// Verify the endpoint is reachable and returns 2xx before wiring the client\nconst res = await fetch(new URL(\"/mcp\", baseUrl), { method: \"POST\" });\nif (res.status >= 400) throw new Error(`Bad MCP endpoint: ${res.status}`);","typeGuard":"const isHttpTransportError = (e: unknown): boolean =>\n  e instanceof Error && e.message.includes(\"MCP HTTP request failed\");","tryCatchPattern":"try {\n  await client.callTool(name, args);\n} catch (e) {\n  if (isHttpTransportError(e) && /5\\d\\d|429/.test(e.message)) {\n    await backoff(); await client.callTool(name, args); // retry transient\n  } else throw e;\n}","preventionTips":["Health-check the MCP URL at startup","Keep auth tokens fresh; rotate before expiry","Ensure proxies support POST+SSE to the /mcp path"],"tags":["mcp","http","status-code","transport"],"backgroundTag":"http-request-failed","analyzedSha":"99f24806c6a2c660b16e53e95211c517448a6c90","analyzedAt":"2026-08-27T04:11:01.184Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}