{"record":{"id":"758244e7c484a7d4","repo":"upstash/context7","slug":"32603","errorCode":"-32603","errorMessage":"Internal server error","messagePattern":"Internal server error","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"packages/mcp/src/index.ts","lineNumber":514,"sourceCode":"            return;\n          }\n        }\n\n        const context: ClientContext = {\n          clientIp: req.ip,\n          apiKey,\n          clientInfo: extractClientInfoFromUserAgent(req.headers[\"user-agent\"]),\n          plugin,\n          transport: \"http\",\n        };\n\n        await requestContext.run(context, async () => {\n          await nodeHandler(req, res, req.body);\n        });\n      } catch (error) {\n        console.error(\"Error handling MCP request:\", error);\n        if (!res.headersSent) {\n          res.status(500).json({\n            jsonrpc: \"2.0\",\n            error: { code: -32603, message: \"Internal server error\" },\n            id: null,\n          });\n        }\n      }\n    };\n\n    // JSON bodies and JSON-RPC error envelopes are the MCP contract only, so the\n    // parser and its error boundary live on the MCP router: every other route\n    // stays out of the parser and keeps its own response shape.\n    const mcpRouter = express.Router();\n    mcpRouter.use(express.json());\n    mcpRouter.use(mcpBodyErrorHandler);\n    mcpRouter.all(\"/\", (req, res) => handleMcpRequest(req, res));\n    // OAuth-protected endpoint - requires authentication\n    mcpRouter.all(\"/oauth\", (req, res) => handleMcpRequest(req, res));\n    app.use(\"/mcp\", mcpRouter);","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/upstash/context7/blob/4416fb855b8f752be735e34f943b5d0762701aad/packages/mcp/src/index.ts#L496-L532","documentation":"Catch-all handler in the MCP server's request wrapper: if nodeHandler (the JSON-RPC dispatch) throws an unhandled exception, the server logs it and returns a JSON-RPC internal error (code -32603, \"Internal server error\") with HTTP 500, unless headers were already sent. It deliberately hides internals from clients.","triggerScenarios":"Any unexpected exception inside MCP tool call handling, session resolution, or request parsing that isn't converted to a JSON-RPC error — e.g. a tool handler throwing, a database/network call failing inside a tool, or a bug in the server itself.","commonSituations":"A tool crashes on bad arguments (unhandled TypeError), an upstream dependency is down, or the request context/session store throws.","solutions":["Check the server console logs for \"Error handling MCP request:\" to see the underlying exception.","Fix or guard the failing tool/handler found in the stack trace; validate tool arguments with the tool's input schema.","Update the MCP server/client to latest versions in case of a known bug.","Retry the request after fixing; transient dependency failures can also be retried with backoff."],"exampleFix":"// before\nserver.tool(\"search\", { q: z.string() }, async ({ q }) => search(q)); // throws on upstream failure\n// after\nserver.tool(\"search\", { q: z.string() }, async ({ q }) => {\n  try { return await search(q); }\n  catch (e) { return { isError: true, content: [{ type: \"text\", text: String(e) }] }; }\n});","handlingStrategy":"try-catch","validationCode":"// Client-side: validate tool arguments against the schema before calling\nconst parsed = toolSchema.safeParse(args);\nif (!parsed.success) throw new Error(`Invalid tool args: ${parsed.error.message}`);","typeGuard":"function isInternalRpcError(res: unknown): res is { error: { code: -32603 } } {\n  return typeof res === 'object' && res !== null &&\n    (res as any).error?.code === -32603;\n}","tryCatchPattern":"try {\n  const result = await client.callTool({ name, arguments });\n} catch (e) {\n  if (isInternalRpcError(e)) {\n    console.error('Server-side crash; check MCP server logs');\n    // retry with backoff only if the failure may be transient\n  } else throw e;\n}","preventionTips":["Wrap every tool handler body in try/catch returning isError results","Validate tool inputs with zod schemas before executing handlers","Keep server and client SDK versions in sync","Monitor server logs for 'Error handling MCP request' and alert on spikes"],"tags":["internal-error","mcp","jsonrpc"],"backgroundTag":"internal-invariant-violation","analyzedSha":"4416fb855b8f752be735e34f943b5d0762701aad","analyzedAt":"2026-09-16T20:28:07.148Z","contentChangedAt":"2026-09-16T20:28:07.148Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}