What causes "MCP server '${serverId}' not found" in mastra-ai/mastra?

Verify the serverId in the URL exactly matches a key registered via `new Mastra({ mcpServers: { : ... } })`.

mastra-ai/mastra · error · HTTPException

MCP server '${serverId}' not found

Error message

MCP server '${serverId}' not found

What it means

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.

Source

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

export const MCP_HTTP_TRANSPORT_ROUTE = createRoute({
  method: 'ALL',
  path: '/mcp/:serverId/mcp',
  responseType: 'mcp-http',
  pathParamSchema: mcpServerIdPathParams,
  summary: 'MCP HTTP Transport',
  description: 'Streamable HTTP transport endpoint for MCP protocol communication',
  tags: ['MCP'],
  requiresAuth: true,
  handler: async ({ mastra, serverId }: ServerContext & { serverId: string }): Promise<MCPHttpTransportResult> => {
    if (!mastra || typeof mastra.getMCPServerById !== 'function') {
      throw new HTTPException(500, { message: 'Mastra instance or getMCPServerById method not available' });
    }

    const server = mastra.getMCPServerById(serverId);

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

    return {
      server,
      httpPath: `/mcp/${serverId}/mcp`,
    };
  },
});

export const MCP_SSE_TRANSPORT_ROUTE = createRoute({
  method: 'ALL',
  path: '/mcp/:serverId/sse',
  responseType: 'mcp-sse',
  pathParamSchema: mcpServerIdPathParams,
  summary: 'MCP SSE Transport',
  description: 'SSE transport endpoint for MCP protocol communication',
  tags: ['MCP'],
  requiresAuth: true,

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
await fetch('/api/mcp/weather/mcp') // 404: id never registered
// after
const mastra = new Mastra({
  mcpServers: { weather: weatherServer },
});
await fetch('/api/mcp/weather/mcp')

Defensive patterns

Strategy: validation

Validate before calling

const ids = Object.keys(mastraConfig.mcpServers ?? {});
if (!ids.includes(serverId)) throw new Error(`Unknown MCP server: ${serverId}. Known: ${ids.join(', ')}`);

Try / catch

try {
  const res = await fetch(`/api/mcp/${serverId}/mcp`);
  if (res.status === 404) { /* list available servers, correct id */ }
} catch (e) { /* handle network */ }

Prevention

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.

When it happens

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

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

Related errors

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