mastra-ai/mastra · error · HTTPException

Mastra instance or getMCPServerById method not available

Error message

Mastra instance or getMCPServerById method not available

What it means

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.

Source

Thrown at packages/server/src/server/handlers/mcp.ts:120

      next: nextUrl,
    };
  },
});

export const GET_MCP_SERVER_DETAIL_ROUTE = createRoute({
  method: 'GET',
  path: '/mcp/v0/servers/:id',
  responseType: 'json',
  pathParamSchema: mcpServerDetailPathParams,
  queryParamSchema: getMcpServerDetailQuerySchema,
  responseSchema: serverDetailSchema,
  summary: 'Get MCP server details',
  description: 'Returns detailed information about a specific MCP server',
  tags: ['MCP'],
  requiresAuth: true,
  handler: async ({ mastra, id, version }: ServerContext & { id: string; version?: string }) => {
    if (!mastra || typeof mastra.getMCPServerById !== 'function') {
      throw new HTTPException(500, { message: 'Mastra instance or getMCPServerById method not available' });
    }

    const server = mastra.getMCPServerById(id);

    if (!server) {
      throw new HTTPException(404, { message: `MCP server with ID '${id}' not found` });
    }

    const serverDetail = server.getServerDetail();

    // If a specific version was requested, check if it matches
    if (version && serverDetail.version_detail.version !== version) {
      throw new HTTPException(404, {
        message: `MCP server with ID '${id}' found, but not version '${version}'. Available version: ${serverDetail.version_detail.version}`,
      });
    }

    return serverDetail;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a real Mastra instance when constructing the server (new MastraServer({ mastra }) or equivalent context wiring).
2. Align package versions: upgrade @mastra/core to a version that defines getMCPServerById (check `typeof mastra.getMCPServerById === 'function'` at startup).
3. If using a custom/test context, add getMCPServerById to the injected object.

Example fix

// before
const server = new MastraServer({}); // no mastra passed
// after
const mastra = new Mastra({ servers: { myServer } });
const server = new MastraServer({ mastra });

// before calling the endpoint
if (!mastra || typeof mastra.getMCPServerById !== 'function') {
  throw new Error('Server misconfigured: Mastra instance with getMCPServerById required');
}
await fetch(`/api/mcp/v0/servers/${encodeURIComponent(id)}`, { headers });

function hasMcpRegistry(m: unknown): m is { getMCPServerById: (id: string) => unknown } {
  return !!m && typeof (m as any).getMCPServerById === 'function';
}

try {
  const res = await fetch(`/api/mcp/v0/servers/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return await res.json();
} catch (err) {
  console.error('MCP server detail lookup failed (check server Mastra wiring):', err);
  throw err;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Storage is not configured
• MCP clients storage domain is not available
• Failed to resolve updated MCP client
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/714ef4eefe7bbcd8. Report an issue: GitHub.