{"record":{"id":"fba6dae6876af5a6","repo":"can1357/oh-my-pi","slug":"no-mcp-manager-available-mcp-servers-may-not-be-c","errorCode":null,"errorMessage":"No MCP manager available. MCP servers may not be configured.","messagePattern":"No MCP manager available\\. MCP servers may not be configured\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/internal-urls/mcp-protocol.ts","lineNumber":123,"sourceCode":"\t\t.join(\"\\n\");\n\treturn available || \"  (none)\";\n}\n\n/**\n * Protocol handler for MCP resources.\n *\n * URL forms:\n * - mcp://<resource-uri> (e.g. mcp://test://notes, mcp://ibkr://portfolio/positions)\n * - A resource's native URI when its scheme has no OMP handler (e.g. ags://capabilities/current-host)\n */\nexport class McpProtocolHandler implements ProtocolHandler {\n\treadonly scheme = \"mcp\";\n\treadonly immutable = true;\n\n\tasync resolve(url: InternalUrl): Promise<InternalResource> {\n\t\tconst mcpManager = MCPManager.instance();\n\t\tif (!mcpManager) {\n\t\t\tthrow new Error(\"No MCP manager available. MCP servers may not be configured.\");\n\t\t}\n\n\t\tconst uri = extractResourceUri(url);\n\t\tlet targetServer = resolveTargetServer(mcpManager, uri);\n\t\tif (!targetServer) {\n\t\t\tawait Promise.allSettled(mcpManager.getConnectedServers().map(name => mcpManager.ensureServerResources(name)));\n\t\t\ttargetServer = resolveTargetServer(mcpManager, uri);\n\t\t}\n\t\tif (!targetServer) {\n\t\t\tthrow new Error(\n\t\t\t\t`No MCP server has resource \"${uri}\".\\n\\nAvailable resources:\\n${formatAvailableResources(mcpManager)}`,\n\t\t\t);\n\t\t}\n\n\t\tlet result: MCPResourceReadResult | undefined;\n\t\ttry {\n\t\t\tresult = await mcpManager.readServerResource(targetServer, uri);\n\t\t} catch (error) {","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/internal-urls/mcp-protocol.ts#L105-L141","documentation":"The mcp:// internal-URL protocol handler resolves MCP resources via a process-wide MCPManager singleton. This error means MCPManager.instance() returned null — no MCP manager was ever initialized, so there is no way to look up or read any MCP resource. The library throws it as a fast, clear failure instead of a null dereference deeper in resolution.","triggerScenarios":"Calling McpProtocolHandler.resolve(url) (or reading any mcp:// URL) in a process where MCP servers were never configured/initialized — MCPManager.setInstance() was never called, or the manager was not created because no MCP servers are in config.","commonSituations":"Running the SDK/embedding path without MCP config; a unit test constructing the protocol handler directly; config file missing the mcp section; MCP feature disabled at startup; using a stale entry point that skips MCP bootstrap.","solutions":["Add MCP server entries to your configuration so the MCP manager is initialized at startup, then retry.","If embedding the library, construct and register the MCPManager (MCPManager.setInstance / its init path) before resolving mcp:// URLs.","If MCP is intentionally unused, stop issuing mcp:// URLs (and remove them from prompts/scripts) instead of resolving them."],"exampleFix":"// before\nconst resource = await handler.resolve(parseInternalUrl(\"mcp://notes/roadmap\"));\n// after\nif (!MCPManager.instance()) {\n  await initMcpManager(config.mcpServers); // bootstrap before resolving\n}\nconst resource = await handler.resolve(parseInternalUrl(\"mcp://notes/roadmap\"));","handlingStrategy":"validation","validationCode":"import { MCPManager } from \"../mcp/manager\";\nif (!MCPManager.instance()) {\n  throw new Error(\"mcp:// URLs unavailable: no MCP servers configured\");\n}\n// safe to resolve mcp:// URLs below","typeGuard":"function hasMcpManager(): boolean {\n  return MCPManager.instance() != null;\n}","tryCatchPattern":"try {\n  return await handler.resolve(url);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"No MCP manager available\")) {\n    return null; // MCP unconfigured — degrade gracefully\n  }\n  throw e;\n}","preventionTips":["Initialize MCP servers from config at startup before any internal-URL resolution can run.","Guard tool prompts so mcp:// URLs are only suggested when MCP servers are configured.","In tests, register a stub MCPManager instance or skip mcp:// fixtures."],"tags":["mcp","configuration","missing-singleton"],"backgroundTag":"mcp-not-configured","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}