mastra-ai/mastra · error · HTTPException

MCP clients storage domain is not available

Error message

MCP clients storage domain is not available

What it means

After confirming storage exists, the MCP client versions handler resolves the 'mcpClients' storage domain via storage.getStore('mcpClients') and throws HTTPException 500 if that domain is not available. This means the configured storage adapter exists but does not implement (or failed to provide) the MCP clients domain, so version history cannot be read. It indicates an adapter capability/version gap rather than missing storage altogether.

Source

Thrown at packages/server/src/server/handlers/mcp-client-versions.ts:54

  requiresAuth: true,
  responseType: 'json',
  pathParamSchema: mcpClientVersionPathParams,
  queryParamSchema: listMCPClientVersionsQuerySchema,
  responseSchema: listMCPClientVersionsResponseSchema,
  summary: 'List MCP client versions',
  description: 'Returns a paginated list of all versions for a stored MCP client',
  tags: ['MCP Client Versions'],
  handler: async ({ mastra, mcpClientId, page, perPage, orderBy, 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 mcpClient = await mcpClientStore.getById(mcpClientId);
      if (!mcpClient) {
        throw new HTTPException(404, { message: `MCP client with id ${mcpClientId} not found` });
      }
      assertStoredResourceScope(mcpClient, await getStoredResourceScope(mastra, requestContext));

      const result = await mcpClientStore.listVersions({
        mcpClientId,
        page,
        perPage,
        orderBy,
      });

      return result;
    } catch (error) {
      return handleError(error, 'Error listing MCP client versions');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra storage packages so the configured adapter implements the mcpClients domain.
2. Switch to a storage adapter that supports the mcpClients domain (e.g. an official LibSQL/Postgres/Upstash adapter at a current version).
3. If using a custom adapter, implement the mcpClients store methods required by the server.

Example fix

// before: old adapter without the domain
storage: new MyCustomStore({ url }),
// after: current official adapter supporting mcpClients
storage: new LibSQLStore({ url: process.env.DATABASE_URL }),

const storage = mastra.getStorage();
const store = storage ? await storage.getStore('mcpClients') : null;
if (!store) {
  console.warn('Storage adapter lacks mcpClients domain; upgrade or switch adapter');
}

function supportsMcpClients(storage: MastraStorage | null): boolean {
  return !!storage && typeof (storage as any).getStore === 'function' && !!(storage as any).stores?.mcpClients;
}

try {
  return await getMcpClientVersions(id);
} catch (e) {
  if (e.status === 500 && /storage domain is not available/.test(e.message)) {
    return { versions: [], unsupported: true }; // degrade gracefully
  }
  throw e;
}

When it happens

Trigger: GET the MCP client versions endpoint against a storage adapter that lacks an mcpClients store (older or minimal adapter, or a domain the adapter didn't register).

Common situations: Using a custom or third-party storage adapter that hasn't implemented the mcpClients domain; an outdated storage package version predating the mcpClients domain; a storage backend that partially initialized.

Related errors

• AcpAgent does not support resuming suspended stream calls
• ClaudeSDKAgent resumeData must include a message.
• Storage is not configured
• Failed to retrieve created version
• Failed to resolve created MCP client

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