mastra-ai/mastra · critical · HTTPException

Mastra instance or listMCPServers method not available

Error message

Mastra instance or listMCPServers method not available

What it means

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.

Source

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

  method: 'GET',
  path: '/mcp/v0/servers',
  responseType: 'json',
  queryParamSchema: listMcpServersQuerySchema,
  responseSchema: listMcpServersResponseSchema,
  summary: 'List MCP servers',
  description: 'Returns a list of registered MCP servers with pagination support',
  tags: ['MCP'],
  requiresAuth: true,
  handler: async ({
    mastra,
    routePrefix,
    page,
    perPage,
    limit,
    offset,
  }: ServerContext & { page?: number; perPage?: number; limit?: number; offset?: number }) => {
    if (!mastra || typeof mastra.listMCPServers !== 'function') {
      throw new HTTPException(500, { message: 'Mastra instance or listMCPServers method not available' });
    }

    const servers = mastra.listMCPServers();

    if (!servers) {
      return { servers: [], total_count: 0, next: null };
    }

    const serverList = Object.values(servers) as MastraMCPServerImplementation[];
    const totalCount = serverList.length;

    // Support both page/perPage and limit/offset for backwards compatibility
    // Detect which format user is using - prefer page/perPage if both provided
    const useLegacyFormat =
      (limit !== undefined || offset !== undefined) && page === undefined && perPage === undefined;

    // If perPage provided, use it; otherwise fall back to limit
    const finalPerPage = perPage ?? limit;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra/core and @mastra/server to matching versions so Mastra#listMCPServers exists.
2. Ensure the Mastra instance is actually passed when creating/registering the server (mastra option).
3. Register at least the MCP machinery by importing the relevant MCP package so the method is attached (e.g. @mastra/mcp with compatible versions).

Example fix

// before
const server = createHonoServer({ /* mastra missing */ });
// after
import { mastra } from './mastra';
const server = createHonoServer({ mastra });

if (!mastra || typeof mastra.listMCPServers !== 'function') throw new Error('Mastra instance lacks MCP server support; check package versions');

function hasMcpSupport(m: unknown): m is { listMCPServers: () => unknown[] } {
  return !!m && typeof (m as any).listMCPServers === 'function';
}

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; }

When it happens

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

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

Related errors

• Storage is not configured
• Scorer definitions storage domain is not available
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• workflowDefinitions storage domain is not available.

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