CherryHQ/cherry-studio · error · Error

MCP server not found: ${mcpId}

Error message

MCP server not found: ${mcpId}

What it means

Thrown by `createMcpBridgeServer` when neither the provided `serverSnapshot` nor a database lookup by `mcpId` (via findByIdOrName) returns a server configuration. The bridge server needs an existing MCP server entity to proxy its tools/resources/prompts to SDK clients.

Source

Thrown at src/main/ai/mcp/createMcpBridgeServer.ts:102

 * bridge must never gamble on the cache being warm at that single read. Instead:
 * - ListTools reads the shared cache only and never blocks on a server connect, so a
 *   dead/slow server can't stall session start (issue #16242). A cold cache returns `[]`
 *   and `listTools` itself kicks a non-blocking refresh.
 * - Every content change to that cache fires `McpCatalogService.onToolsCacheUpdated`;
 *   the bridge relays it as a `tools/list_changed` notification, and the SDK re-lists
 *   (verified against SDK 0.3.185: the CLI re-lists on the notification, debounced
 *   300ms, keeping the previous tool set if the re-list fails). One notification
 *   round-trip heals a session that started on a cold cache — including servers whose
 *   connect outlives the session-build warm — with zero blocking anywhere.
 */
export function createMcpBridgeServer(
  mcpId: string,
  serverSnapshot?: McpServerEntity,
  { listChanged = true }: McpBridgeOptions = {}
): McpServer {
  const serverConfig = serverSnapshot ?? mcpServerService.findByIdOrName(mcpId)
  if (!serverConfig) {
    throw new Error(`MCP server not found: ${mcpId}`)
  }

  const sdkServer = new McpServer(
    { name: serverConfig.name, version: '0.1.0' },
    // `listChanged` is load-bearing twice over: the SDK client only attaches its re-list
    // handler for servers that declared it, and the local `sendToolListChanged` below
    // throws a capability error without it. Declaring it on a transport that cannot
    // deliver the notification is worse than not declaring it — the client would trust a
    // heal that never comes and serve a stale tool list indefinitely.
    { capabilities: { tools: listChanged ? { listChanged: true } : {}, resources: {}, prompts: {} } }
  )

  // Use the low-level Server to set raw request handlers because this bridge
  // proxies requests to the downstream MCP server whose tool schemas are not
  // known at construction time. The high-level McpServer.tool() API requires
  // Zod schemas to be declared upfront, which is not feasible for a proxy.
  const rawServer = sdkServer.server

View on GitHub (pinned to 726446b54c)

Solutions

1. Verify the mcpId exists in the MCP servers list (check via the settings UI or database query)
2. If the server was deleted, recreate it or update the reference to point to an existing server
3. Pass a serverSnapshot explicitly if the server entity is available in memory but not in the DB
4. Add a pre-check using findByIdOrName before calling createMcpBridgeServer

Example fix

// before
const bridge = createMcpBridgeServer('deleted-server-id')

// after
const server = mcpServerService.findByIdOrName(mcpId)
if (!server) {
  throw new Error(`Cannot create bridge: server '${mcpId}' does not exist`)
}
const bridge = createMcpBridgeServer(mcpId, server)

import { mcpServerService } from '...'

const serverConfig = mcpServerService.findByIdOrName(mcpId)
if (!serverConfig) {
  throw new Error(`Cannot create bridge: MCP server '${mcpId}' not found`)
}
const bridge = createMcpBridgeServer(mcpId, serverConfig)

try {
  const bridge = createMcpBridgeServer(mcpId)
  return bridge
} catch (e) {
  if (e instanceof Error && e.message.startsWith('MCP server not found')) {
    // The referenced server was deleted or never existed — clean up the reference
    logger.warn(`MCP server '${mcpId}' not found, removing stale reference`)
    return null
  }
  throw e
}

When it happens

Trigger: Calling `createMcpBridgeServer(mcpId)` with an ID or name that doesn't exist in the MCP servers database, and no serverSnapshot override provided. This happens when the referenced server was deleted, the ID is mistyped, or the server hasn't been imported yet.

Common situations: Server was deleted from the database but a reference (session config, bookmark, AI agent config) still points to it; mcpId was constructed from a stale cache; the server was never created; typo in the server name; the database migration didn't carry over all servers.

Related errors

• Invalid manifest: missing server.mcp_config.command
• Invalid manifest: server.mcp_config.args must be an array
• MCP server ${server.name} is disabled
• Invalid server type
• Either baseUrl or command must be provided

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/0f9d38f3201e27b2. Report an issue: GitHub.