mastra-ai/mastra · critical · HTTPException

MCP clients storage domain is not available

Error message

MCP clients storage domain is not available

What it means

Storage is present but storage.getStore('mcpClients') returned nothing, so the list handler throws a 500 HTTPException. The mcpClients domain store backs resolved MCP client records. This signals the adapter does not support that domain or failed to initialize it.

Source

Thrown at packages/server/src/server/handlers/stored-mcp-clients.ts:48

  path: '/stored/mcp-clients',
  responseType: 'json',
  queryParamSchema: listStoredMCPClientsQuerySchema,
  responseSchema: listStoredMCPClientsResponseSchema,
  summary: 'List stored MCP clients',
  description: 'Returns a paginated list of all MCP client configurations stored in the database',
  tags: ['Stored MCP Clients'],
  requiresAuth: true,
  handler: async ({ mastra, page, perPage, orderBy, status, authorId, metadata, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const mcpClientStore = await storage.getStore('mcpClients');
      if (!mcpClientStore) {
        throw new HTTPException(500, { message: 'MCP clients storage domain is not available' });
      }

      const scope = await getStoredResourceScope(mastra, requestContext);
      const result = await mcpClientStore.listResolved({
        page,
        perPage,
        orderBy,
        status,
        authorId,
        metadata: scopeStoredResourceMetadata(metadata, scope),
      });

      return result;
    } catch (error) {
      return handleError(error, 'Error listing stored MCP clients');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade the storage adapter so it implements the mcpClients domain (match versions with @mastra/core).
2. Verify migrations/schema creation ran for the MCP clients tables.
3. Inspect startup logs for getStore/domain registration errors.
4. Switch to a first-party adapter known to support all current domains.

const mcpStore = await storage.getStore('mcpClients');
if (!mcpStore) throw new Error('mcpClients storage domain unavailable — upgrade/verify your storage adapter.');

try {
  const clients = await client.listStoredMCPClients({});
} catch (e) {
  if (isMastraServerError(e) && e.status === 500 && e.message.includes('storage domain')) {
    // flag adapter/domain incompatibility
  } else throw e;
}

When it happens

Trigger: GET /api/mcp/clients/stored where the configured storage adapter lacks the 'mcpClients' store domain or its registration failed.

Common situations: Older storage adapter versions predating the mcpClients domain; core/storage version mismatch; failed schema migrations on startup; custom adapters implementing only core domains.

Related errors

• Storage is not configured
• Failed to resolve updated MCP client
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls
• ACP prompt stopped before completing: ${response.stopReason}

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