{"record":{"id":"3c0f788bde31611b","repo":"mastra-ai/mastra","slug":"mastra-instance-or-listmcpservers-method-not-avail","errorCode":null,"errorMessage":"Mastra instance or listMCPServers method not available","messagePattern":"Mastra instance or listMCPServers method not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"critical","filePath":"packages/server/src/server/handlers/mcp.ts","lineNumber":47,"sourceCode":"  method: 'GET',\n  path: '/mcp/v0/servers',\n  responseType: 'json',\n  queryParamSchema: listMcpServersQuerySchema,\n  responseSchema: listMcpServersResponseSchema,\n  summary: 'List MCP servers',\n  description: 'Returns a list of registered MCP servers with pagination support',\n  tags: ['MCP'],\n  requiresAuth: true,\n  handler: async ({\n    mastra,\n    routePrefix,\n    page,\n    perPage,\n    limit,\n    offset,\n  }: ServerContext & { page?: number; perPage?: number; limit?: number; offset?: number }) => {\n    if (!mastra || typeof mastra.listMCPServers !== 'function') {\n      throw new HTTPException(500, { message: 'Mastra instance or listMCPServers method not available' });\n    }\n\n    const servers = mastra.listMCPServers();\n\n    if (!servers) {\n      return { servers: [], total_count: 0, next: null };\n    }\n\n    const serverList = Object.values(servers) as MastraMCPServerImplementation[];\n    const totalCount = serverList.length;\n\n    // Support both page/perPage and limit/offset for backwards compatibility\n    // Detect which format user is using - prefer page/perPage if both provided\n    const useLegacyFormat =\n      (limit !== undefined || offset !== undefined) && page === undefined && perPage === undefined;\n\n    // If perPage provided, use it; otherwise fall back to limit\n    const finalPerPage = perPage ?? limit;","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp.ts#L29-L65","documentation":"The MCP servers list handler requires the Mastra instance and its listMCPServers() method; if mastra is undefined or the method is missing it throws HTTPException 500. This indicates a version/registration mismatch between @mastra/server and @mastra/core — the server expects an MCP-enabled Mastra instance.","triggerScenarios":"GET /api/mcp/servers (list route) where the registered mastra instance is null, or was built without MCP server support (older @mastra/core lacking listMCPServers).","commonSituations":"Version skew: server package updated but core not (or vice versa); Mastra instance not passed to server registration; custom server bootstrap omitting mastra from the context.","solutions":["Upgrade @mastra/core and @mastra/server to matching versions so Mastra#listMCPServers exists.","Ensure the Mastra instance is actually passed when creating/registering the server (mastra option).","Register at least the MCP machinery by importing the relevant MCP package so the method is attached (e.g. @mastra/mcp with compatible versions)."],"exampleFix":"// before\nconst server = createHonoServer({ /* mastra missing */ });\n// after\nimport { mastra } from './mastra';\nconst server = createHonoServer({ mastra });","handlingStrategy":"type-guard","validationCode":"if (!mastra || typeof mastra.listMCPServers !== 'function') throw new Error('Mastra instance lacks MCP server support; check package versions');","typeGuard":"function hasMcpSupport(m: unknown): m is { listMCPServers: () => unknown[] } {\n  return !!m && typeof (m as any).listMCPServers === 'function';\n}","tryCatchPattern":"try { const res = await fetch('/api/mcp/servers'); if (!res.ok) throw await res.json(); } catch (e) { if (/listMCPServers/.test(e.message ?? '')) { /* align @mastra/core & server versions, pass mastra to server */ } else throw e; }","preventionTips":["Keep @mastra/core, @mastra/server, and @mastra/mcp versions aligned","Always pass the Mastra instance when creating the server","Add a startup smoke call to an MCP route in CI","Run pnpm why @mastra/core to catch version skew in the workspace"],"tags":["http-500","version-mismatch","mcp","configuration"],"backgroundTag":"api-version-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}