{"record":{"id":"9a05d9ef38996174","repo":"mastra-ai/mastra","slug":"mcp-server-serverid-not-found","errorCode":null,"errorMessage":"MCP server '${serverId}' not found","messagePattern":"MCP server '(.+?)' not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/mcp.ts","lineNumber":381,"sourceCode":"\nexport const MCP_HTTP_TRANSPORT_ROUTE = createRoute({\n  method: 'ALL',\n  path: '/mcp/:serverId/mcp',\n  responseType: 'mcp-http',\n  pathParamSchema: mcpServerIdPathParams,\n  summary: 'MCP HTTP Transport',\n  description: 'Streamable HTTP transport endpoint for MCP protocol communication',\n  tags: ['MCP'],\n  requiresAuth: true,\n  handler: async ({ mastra, serverId }: ServerContext & { serverId: string }): Promise<MCPHttpTransportResult> => {\n    if (!mastra || typeof mastra.getMCPServerById !== 'function') {\n      throw new HTTPException(500, { message: 'Mastra instance or getMCPServerById method not available' });\n    }\n\n    const server = mastra.getMCPServerById(serverId);\n\n    if (!server) {\n      throw new HTTPException(404, { message: `MCP server '${serverId}' not found` });\n    }\n\n    return {\n      server,\n      httpPath: `/mcp/${serverId}/mcp`,\n    };\n  },\n});\n\nexport const MCP_SSE_TRANSPORT_ROUTE = createRoute({\n  method: 'ALL',\n  path: '/mcp/:serverId/sse',\n  responseType: 'mcp-sse',\n  pathParamSchema: mcpServerIdPathParams,\n  summary: 'MCP SSE Transport',\n  description: 'SSE transport endpoint for MCP protocol communication',\n  tags: ['MCP'],\n  requiresAuth: true,","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp.ts#L363-L399","documentation":"This 404 is thrown by the MCP server detail handler in packages/server when `mastra.getMCPServerById(serverId)` returns no server. It means the Mastra instance is reachable but has no MCP server registered under the given id. The server registry is populated at Mastra construction time from the `mcpServers` config.","triggerScenarios":"GET/POST to a route like /api/mcp/:serverId (handler at mcp.ts:381) where the :serverId path param does not match any id in `new Mastra({ mcpServers: {...} })`, or the server was removed/not yet registered on the instance used by the API server.","commonSituations":"Typo in serverId in the URL; MCP server defined in one Mastra instance but the playground/server runs against another; forgetting to pass `mcpServers` to `new Mastra()`; hot-reload dropping registration; calling an internal MCP server by an external id.","solutions":["Verify the serverId in the URL exactly matches a key registered via `new Mastra({ mcpServers: { <id>: ... } })`.","Log/list registered MCP servers on the Mastra instance (e.g. `mastra.getMCPServers?.()` or list keys) and confirm the id exists at startup.","Ensure the same Mastra instance that registers the MCP server is the one handed to the Hono server/playground.","If the server is conditionally registered, fix the registration condition or create the MCPServer before Mastra construction."],"exampleFix":"// before\nawait fetch('/api/mcp/weather/mcp') // 404: id never registered\n// after\nconst mastra = new Mastra({\n  mcpServers: { weather: weatherServer },\n});\nawait fetch('/api/mcp/weather/mcp')","handlingStrategy":"validation","validationCode":"const ids = Object.keys(mastraConfig.mcpServers ?? {});\nif (!ids.includes(serverId)) throw new Error(`Unknown MCP server: ${serverId}. Known: ${ids.join(', ')}`);","typeGuard":null,"tryCatchPattern":"try {\n  const res = await fetch(`/api/mcp/${serverId}/mcp`);\n  if (res.status === 404) { /* list available servers, correct id */ }\n} catch (e) { /* handle network */ }","preventionTips":["Derive MCP server URLs from a single registry/config object so ids can't drift.","Validate serverId against the registered list at app startup.","Centralize server id constants instead of hardcoding strings in URLs."],"tags":["mcp","http-404","server-config"],"backgroundTag":"mcp-server-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}