{"record":{"id":"714ef4eefe7bbcd8","repo":"mastra-ai/mastra","slug":"mastra-instance-or-getmcpserverbyid-method-not-ava","errorCode":null,"errorMessage":"Mastra instance or getMCPServerById method not available","messagePattern":"Mastra instance or getMCPServerById method not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/mcp.ts","lineNumber":120,"sourceCode":"      next: nextUrl,\n    };\n  },\n});\n\nexport const GET_MCP_SERVER_DETAIL_ROUTE = createRoute({\n  method: 'GET',\n  path: '/mcp/v0/servers/:id',\n  responseType: 'json',\n  pathParamSchema: mcpServerDetailPathParams,\n  queryParamSchema: getMcpServerDetailQuerySchema,\n  responseSchema: serverDetailSchema,\n  summary: 'Get MCP server details',\n  description: 'Returns detailed information about a specific MCP server',\n  tags: ['MCP'],\n  requiresAuth: true,\n  handler: async ({ mastra, id, version }: ServerContext & { id: string; version?: string }) => {\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(id);\n\n    if (!server) {\n      throw new HTTPException(404, { message: `MCP server with ID '${id}' not found` });\n    }\n\n    const serverDetail = server.getServerDetail();\n\n    // If a specific version was requested, check if it matches\n    if (version && serverDetail.version_detail.version !== version) {\n      throw new HTTPException(404, {\n        message: `MCP server with ID '${id}' found, but not version '${version}'. Available version: ${serverDetail.version_detail.version}`,\n      });\n    }\n\n    return serverDetail;","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp.ts#L102-L138","documentation":"The GET /api/mcp/v0/servers/:id route handler requires a Mastra instance exposing getMCPServerById. The handler guards with `!mastra || typeof mastra.getMCPServerById !== 'function'` and throws a 500 when either the Mastra instance is missing from the request context or the instance predates the MCP server registry API. This is a server-side wiring/dependency problem, not a problem with the requested ID.","triggerScenarios":"Calling GET /mcp/v0/servers/:id when the request context has no `mastra` object (e.g. server constructed without passing a Mastra instance) or the provided Mastra instance lacks getMCPServerById (older @mastra/core version or a stubbed/mock Mastra object).","commonSituations":"Deploying the Mastra server without registering a Mastra instance in the server context; upgrading @mastra/server without upgrading @mastra/core so the Mastra class is missing the MCP registry methods; tests injecting a partial mock Mastra object.","solutions":["Pass a real Mastra instance when constructing the server (new MastraServer({ mastra }) or equivalent context wiring).","Align package versions: upgrade @mastra/core to a version that defines getMCPServerById (check `typeof mastra.getMCPServerById === 'function'` at startup).","If using a custom/test context, add getMCPServerById to the injected object."],"exampleFix":"// before\nconst server = new MastraServer({}); // no mastra passed\n// after\nconst mastra = new Mastra({ servers: { myServer } });\nconst server = new MastraServer({ mastra });","handlingStrategy":"type-guard","validationCode":"// before calling the endpoint\nif (!mastra || typeof mastra.getMCPServerById !== 'function') {\n  throw new Error('Server misconfigured: Mastra instance with getMCPServerById required');\n}\nawait fetch(`/api/mcp/v0/servers/${encodeURIComponent(id)}`, { headers });","typeGuard":"function hasMcpRegistry(m: unknown): m is { getMCPServerById: (id: string) => unknown } {\n  return !!m && typeof (m as any).getMCPServerById === 'function';\n}","tryCatchPattern":"try {\n  const res = await fetch(`/api/mcp/v0/servers/${id}`);\n  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);\n  return await res.json();\n} catch (err) {\n  console.error('MCP server detail lookup failed (check server Mastra wiring):', err);\n  throw err;\n}","preventionTips":["Always construct MastraServer with a real Mastra instance.","Keep @mastra/core and @mastra/server on matching versions (single lockfile/changeset bump).","In tests, mock the full interface, not a partial object.","Add a startup assertion: if (typeof mastra.getMCPServerById !== 'function') throw ..."],"tags":["server","mastra-instance","mcp","api-contract"],"backgroundTag":"missing-mastra-instance","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}