mastra-ai/mastra · error · HTTPException

MCP client with id ${mcpClientId} not found

Error message

MCP client with id ${mcpClientId} not found

What it means

The MCP client versions list handler looks up the MCP client by ID via mcpClientStore.getById(mcpClientId) and throws HTTPException 404 if no record exists. It signals the client asked for version history of an MCP client ID that is not in storage. The ID is interpolated into the message to make the missing resource unambiguous.

Source

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

  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. Verify mcpClientId against the list of registered MCP clients (list endpoint) and use a valid ID.
  2. Confirm the server's storage points at the same database/environment where the MCP client was created.
  3. If the client was deleted intentionally, remove stale references from the UI/bookmarks.
  4. Check tenant/scope: the caller's scope must match the stored client's resource scope.

Example fix

// before: hard-coded stale ID
await fetch('/api/mcp-clients/clx_old123/versions');
// after: resolve a fresh ID from the list endpoint
const clients = await fetch('/api/mcp-clients').then(r => r.json());
const id = clients.find(c => c.name === 'my-mcp-client').id;
await fetch(`/api/mcp-clients/${id}/versions`);
Defensive patterns

Strategy: validation

Validate before calling

const clients = await fetch('/api/mcp-clients').then(r => r.json());
if (!clients.some(c => c.id === mcpClientId)) {
  throw new Error(`MCP client ${mcpClientId} does not exist; pick a valid id`);
}

Type guard

function isNotFoundError(e: unknown): e is Error & { status: 404 } {
  return e instanceof Error && (e as any).status === 404;
}

Try / catch

try {
  return await fetch(`/api/mcp-clients/${mcpClientId}/versions`).then(r => {
    if (r.status === 404) throw Object.assign(new Error('not found'), { status: 404 });
    return r.json();
  });
} catch (e) {
  if ((e as any).status === 404) {
    return showClientMissingNotice(mcpClientId); // refresh list / clean stale UI
  }
  throw e;
}

Prevention

When it happens

Trigger: GET the versions endpoint with an mcpClientId that was never registered, was deleted, or belongs to a different storage backend/environment than the one the server is using.

Common situations: Stale UI/URL pointing at a deleted MCP client; pointing the client at a server whose storage points at a different database than where the client was created; typo'd or truncated client ID; scope mismatch after multi-tenant scoping was added (assertStoredResourceScope may also reject).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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