{"record":{"id":"7369e2f32df038b1","repo":"upstash/context7","slug":"32001","errorCode":"-32001","errorMessage":"authentication.error","messagePattern":"authentication\\.error","errorType":"http","errorClass":null,"httpStatus":401,"severity":"error","filePath":"packages/mcp/src/index.ts","lineNumber":488,"sourceCode":"\n            if (isJWT(apiKey)) {\n              const validationResult = await validateJWT(apiKey);\n              if (!validationResult.valid) {\n                return {\n                  outcome: \"invalid\",\n                  value: {\n                    accepted: false,\n                    error: validationResult.error || \"Invalid token. Please re-authenticate.\",\n                  },\n                };\n              }\n            }\n\n            return { outcome: \"accepted\", value: { accepted: true } };\n          });\n\n          if (!authentication.accepted) {\n            res.status(401).json({\n              jsonrpc: \"2.0\",\n              error: {\n                code: -32001,\n                message: authentication.error,\n              },\n              id: null,\n            });\n            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        };","sourceCodeStart":470,"sourceCodeEnd":506,"githubUrl":"https://github.com/upstash/context7/blob/4416fb855b8f752be735e34f943b5d0762701aad/packages/mcp/src/index.ts#L470-L506","documentation":"The MCP HTTP server authenticates incoming JSON-RPC requests; when the auth middleware reports acceptance=false, the server replies with a JSON-RPC error (code -32001) carrying the authentication failure reason. The HTTP layer simultaneously returns 401. This signals the client's credentials (e.g. OAuth token) were rejected.","triggerScenarios":"POST /mcp with a missing, expired, or invalid bearer token, or with an audience/resource mismatch such that verifyAccessToken returns accepted:false with an error string.","commonSituations":"Token expired between requests, MCP client configured with the wrong OAuth issuer/audience, clock skew invalidating JWTs, or hitting the server without completing the OAuth flow.","solutions":["Re-run the MCP OAuth authorization flow to obtain a fresh token.","Verify the token's issuer, audience, and resource match the server's configured OAuth server.","Check server env config (auth issuer/audience/secret variables) for mismatch with the client's OAuth metadata.","Confirm system clocks are synchronized (JWT exp/iat validation)."],"exampleFix":"// before (client)\nmcpClient = new Client({ ..., authProvider: undefined });\n// after\nmcpClient = new Client({\n  ...,\n  authProvider: new OAuthClientProvider({ serverUrl, clientId, ... }) // supplies valid bearer token\n});","handlingStrategy":"retry","validationCode":"const { payload } = await provider.refreshOrReuseToken();\nif (!payload || payload.exp * 1000 <= Date.now()) await provider.authorize();","typeGuard":"function isAuthError(res: unknown): res is { error: { code: -32001; message: string } } {\n  return typeof res === 'object' && res !== null &&\n    (res as any).error?.code === -32001;\n}","tryCatchPattern":"try {\n  await transport.start();\n} catch (e) {\n  if (isJsonRpcAuthError(e)) {\n    await oauthProvider.authorize(); // redo OAuth flow for fresh token\n    await transport.start();\n  } else throw e;\n}","preventionTips":["Configure an OAuthClientProvider so tokens refresh automatically before expiry","Ensure issuer/audience/resource in client config match server metadata","Sync server clocks with NTP to avoid premature JWT expiry","Watch for 401 responses and trigger re-auth instead of retrying blindly"],"tags":["authentication","oauth","mcp"],"backgroundTag":"authentication-required","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"}