mastra-ai/mastra · error · HTTPException

Stored MCP client with id ${storedMCPClientId} not found

Error message

Stored MCP client with id ${storedMCPClientId} not found

What it means

HTTP 404 thrown after getByIdResolved(storedMCPClientId, { status }) returns no record, meaning no stored MCP client exists with that id (in the requested status). This is a normal not-found signal, not a crash: the store was reachable but the row was absent.

Source

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

  tags: ['Stored MCP Clients'],
  requiresAuth: true,
  handler: async ({ mastra, storedMCPClientId, status, 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.getByIdResolved(storedMCPClientId, { status });

      if (!mcpClient) {
        throw new HTTPException(404, { message: `Stored MCP client with id ${storedMCPClientId} not found` });
      }
      assertStoredResourceScope(mcpClient, await getStoredResourceScope(mastra, requestContext));

      return mcpClient;
    } catch (error) {
      return handleError(error, 'Error getting stored MCP client');
    }
  },
});

/**
 * POST /stored/mcp-clients - Create a new stored MCP client
 */
export const CREATE_STORED_MCP_CLIENT_ROUTE = createRoute({
  method: 'POST',
  path: '/stored/mcp-clients',
  responseType: 'json',
  bodySchema: createStoredMCPClientBodySchema,

View on GitHub (pinned to 75dd419e61)

Solutions

Confirm the exact id via the list endpoint (GET /api/mcp/clients) before fetching by id.
Retry with status 'draft' or omit the status filter for newly created clients.
Recreate the client with POST if it was intentionally deleted.
Check for slug drift: the id is derived from name via toSlug, so renamed clients may have new ids.

Example fix

// before
const c = await fetch(`/api/mcp/clients/${id}?status=archived`).json();
// after
const c = await fetch(`/api/mcp/clients/${id}?status=draft`).json();
if (!c) throw new Error(`Client ${id} not found`);

Defensive patterns

Strategy: try-catch

Validate before calling

const list = await fetch('/api/mcp/clients').then(r => r.json());
const exists = list.some(c => c.id === targetId);
if (!exists) console.warn(`${targetId} not present; skipping fetch`);

Type guard

function isNotFound(res: Response): boolean { return res.status === 404; }

Try / catch

const res = await fetch(`/api/mcp/clients/${id}?status=${status}`);
if (res.status === 404) {
  return null; // treat as absent, not fatal
}
if (!res.ok) throw new Error(`Unexpected ${res.status}`);
return res.json();

Prevention

Resolve ids from the list endpoint instead of hardcoding.
Remember fresh clients are drafts — query with the right status.
Re-derive ids after renames (toSlug drift).
Handle 404 as a normal branch in client code.

When it happens

Trigger: GET /api/mcp/clients/:id with an id that was never created, a typo'd id, or an id that exists only in a different status than requested (e.g. exists as draft but queried with status 'archived').

Common situations: Client code cached an id from a deleted client; ids derived via toSlug(name) changed after a rename; requesting a non-draft status for a freshly created client.

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/7ea972fe281dc2a4. Report an issue: GitHub.