{"record":{"id":"925f63c015be5a18","repo":"can1357/oh-my-pi","slug":"mcp-server-not-connected-name","errorCode":null,"errorMessage":"MCP server not connected: ${name}","messagePattern":"MCP server not connected: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/mcp/manager.ts","lineNumber":915,"sourceCode":"\tgetServerConfig(name: string): MCPServerConfig | undefined {\n\t\treturn this.#connections.get(name)?.config ?? this.#serverConfigs.get(name);\n\t}\n\n\t/**\n\t * Wait for a connection to complete (or fail).\n\t */\n\tasync waitForConnection(name: string): Promise<MCPServerConnection> {\n\t\tconst connection = this.#connections.get(name);\n\t\tif (connection) return connection;\n\t\tconst pending = this.#pendingConnections.get(name);\n\t\tif (pending) return pending;\n\t\t// If a reconnection is in flight, wait for it to complete\n\t\tconst reconnecting = this.#pendingReconnections.get(name);\n\t\tif (reconnecting) {\n\t\t\tconst result = await reconnecting;\n\t\t\tif (result) return result;\n\t\t}\n\t\tthrow new Error(`MCP server not connected: ${name}`);\n\t}\n\n\t/**\n\t * Resolve auth and shell-command substitutions in config before connecting.\n\t * Pass `oauth: false` to skip OAuth credential injection (used by reauth's\n\t * unauthenticated probe, which must observe the server's bare 401).\n\t */\n\tasync prepareConfig(config: MCPServerConfig, options?: { oauth?: boolean }): Promise<MCPServerConfig> {\n\t\treturn this.#resolveAuthConfig(config, options);\n\t}\n\n\t/**\n\t * Get all connected server names.\n\t */\n\tgetConnectedServers(): string[] {\n\t\treturn Array.from(this.#connections.keys());\n\t}\n","sourceCodeStart":897,"sourceCodeEnd":933,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/mcp/manager.ts#L897-L933","documentation":"A lookup path in MCPManager (e.g. retrieving a connection to call a tool) throws \"MCP server not connected: <name>\" when no active connection exists for that server and no reconnection is in flight. If a pending reconnection promise exists, the call awaits it and returns its result; only when there is neither a live connection nor a pending reconnect does it throw.","triggerScenarios":"Calling a tool or requesting the connection for a server that was never connected, was disconnected via disconnectServer/disconnectAll, failed to connect earlier (bad command, crashed on start), or whose config was removed — with no reconnect currently in flight.","commonSituations":"Invoking an MCP tool while the server's stdio process failed to launch (missing npx, bad package); server was disabled or removed from config; a previous connect attempt errored (auth failure) and no retry is queued; calling tools before connectServers() finished; /mcp disconnect then immediate tool call.","solutions":["Check /mcp status (or manager state) to see whether the server is connected; reconnect it first.","Fix the underlying connect failure (bad command, missing package, auth) that prevented the connection.","Verify the server name spelling matches the config entry exactly.","Ensure connectServers() has completed before issuing tool calls at startup.","If the server was disconnected intentionally, trigger an explicit reconnect rather than assuming auto-reconnect.","Catch this error in tool-call paths and surface a 'server not running — run /mcp' hint to the user."],"exampleFix":"// before\nconst result = await manager.callTool(\"github\", \"list_issues\", args); // throws if not connected\n// after\nlet conn;\ntry {\n  conn = await manager.getConnection(\"github\");\n} catch {\n  await manager.connectServers([\"github\"]); // reconnect, then retry\n  conn = await manager.getConnection(\"github\");\n}","handlingStrategy":"try-catch","validationCode":"import { readMCPConfigFile } from \"@oh-my-pi/pi-coding-agent/mcp/config\";\nconst cfg = await readMCPConfigFile(configPath);\nif (!cfg.mcpServers?.[serverName]) throw new Error(`Server \"${serverName}\" is not in config`);","typeGuard":"function hasConnection(manager: MCPManager, name: string): boolean {\n  // only meaningful if your manager build exposes status; otherwise gate on config\n  return manager.isConnected?.(name) ?? false;\n}","tryCatchPattern":"try {\n  return await manager.callTool(serverName, tool, args);\n} catch (e) {\n  if (e instanceof Error && e.message === `MCP server not connected: ${serverName}`) {\n    await manager.connectServers(); // reconnect then surface a user-facing hint\n    throw new Error(`MCP server \"${serverName}\" is not running — reconnect attempted, please retry`);\n  }\n  throw e;\n}","preventionTips":["Wait for initial connectServers() to complete before exposing MCP tools.","Check /mcp status before issuing tool calls in scripts.","Fix connect failures (bad command, missing binary, auth) promptly — they leave the server unavailable.","Don't call tools for servers you just disconnected or removed from config.","Verify exact server name spelling against the config."],"tags":["mcp","connection","lifecycle","state"],"backgroundTag":"server-not-connected","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}