{"record":{"id":"0f9d38f3201e27b2","repo":"CherryHQ/cherry-studio","slug":"mcp-server-not-found-mcpid","errorCode":null,"errorMessage":"MCP server not found: ${mcpId}","messagePattern":"MCP server not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ai/mcp/createMcpBridgeServer.ts","lineNumber":102,"sourceCode":" * bridge must never gamble on the cache being warm at that single read. Instead:\n * - ListTools reads the shared cache only and never blocks on a server connect, so a\n *   dead/slow server can't stall session start (issue #16242). A cold cache returns `[]`\n *   and `listTools` itself kicks a non-blocking refresh.\n * - Every content change to that cache fires `McpCatalogService.onToolsCacheUpdated`;\n *   the bridge relays it as a `tools/list_changed` notification, and the SDK re-lists\n *   (verified against SDK 0.3.185: the CLI re-lists on the notification, debounced\n *   300ms, keeping the previous tool set if the re-list fails). One notification\n *   round-trip heals a session that started on a cold cache — including servers whose\n *   connect outlives the session-build warm — with zero blocking anywhere.\n */\nexport function createMcpBridgeServer(\n  mcpId: string,\n  serverSnapshot?: McpServerEntity,\n  { listChanged = true }: McpBridgeOptions = {}\n): McpServer {\n  const serverConfig = serverSnapshot ?? mcpServerService.findByIdOrName(mcpId)\n  if (!serverConfig) {\n    throw new Error(`MCP server not found: ${mcpId}`)\n  }\n\n  const sdkServer = new McpServer(\n    { name: serverConfig.name, version: '0.1.0' },\n    // `listChanged` is load-bearing twice over: the SDK client only attaches its re-list\n    // handler for servers that declared it, and the local `sendToolListChanged` below\n    // throws a capability error without it. Declaring it on a transport that cannot\n    // deliver the notification is worse than not declaring it — the client would trust a\n    // heal that never comes and serve a stale tool list indefinitely.\n    { capabilities: { tools: listChanged ? { listChanged: true } : {}, resources: {}, prompts: {} } }\n  )\n\n  // Use the low-level Server to set raw request handlers because this bridge\n  // proxies requests to the downstream MCP server whose tool schemas are not\n  // known at construction time. The high-level McpServer.tool() API requires\n  // Zod schemas to be declared upfront, which is not feasible for a proxy.\n  const rawServer = sdkServer.server\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/mcp/createMcpBridgeServer.ts#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the mcpId exists in the MCP servers list (check via the settings UI or database query)","If the server was deleted, recreate it or update the reference to point to an existing server","Pass a serverSnapshot explicitly if the server entity is available in memory but not in the DB","Add a pre-check using findByIdOrName before calling createMcpBridgeServer"],"exampleFix":"// before\nconst bridge = createMcpBridgeServer('deleted-server-id')\n\n// after\nconst server = mcpServerService.findByIdOrName(mcpId)\nif (!server) {\n  throw new Error(`Cannot create bridge: server '${mcpId}' does not exist`)\n}\nconst bridge = createMcpBridgeServer(mcpId, server)","handlingStrategy":"validation","validationCode":"import { mcpServerService } from '...'\n\nconst serverConfig = mcpServerService.findByIdOrName(mcpId)\nif (!serverConfig) {\n  throw new Error(`Cannot create bridge: MCP server '${mcpId}' not found`)\n}\nconst bridge = createMcpBridgeServer(mcpId, serverConfig)","typeGuard":null,"tryCatchPattern":"try {\n  const bridge = createMcpBridgeServer(mcpId)\n  return bridge\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('MCP server not found')) {\n    // The referenced server was deleted or never existed — clean up the reference\n    logger.warn(`MCP server '${mcpId}' not found, removing stale reference`)\n    return null\n  }\n  throw e\n}","preventionTips":["Look up the server entity before calling createMcpBridgeServer","Clean up references to MCP servers when they are deleted from the database","Pass a serverSnapshot if you already have the entity loaded to avoid a DB lookup"],"tags":["mcp","bridge-server","not-found","configuration"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}