No MCP manager available. MCP servers may not be configured.

Error message

No MCP manager available. MCP servers may not be configured.

What it means

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.

Source

Thrown at packages/coding-agent/src/internal-urls/mcp-protocol.ts:123

		.join("\n");
	return available || "  (none)";
}

/**
 * Protocol handler for MCP resources.
 *
 * URL forms:
 * - mcp://<resource-uri> (e.g. mcp://test://notes, mcp://ibkr://portfolio/positions)
 * - A resource's native URI when its scheme has no OMP handler (e.g. ags://capabilities/current-host)
 */
export class McpProtocolHandler implements ProtocolHandler {
	readonly scheme = "mcp";
	readonly immutable = true;

	async resolve(url: InternalUrl): Promise<InternalResource> {
		const mcpManager = MCPManager.instance();
		if (!mcpManager) {
			throw new Error("No MCP manager available. MCP servers may not be configured.");
		}

		const uri = extractResourceUri(url);
		let targetServer = resolveTargetServer(mcpManager, uri);
		if (!targetServer) {
			await Promise.allSettled(mcpManager.getConnectedServers().map(name => mcpManager.ensureServerResources(name)));
			targetServer = resolveTargetServer(mcpManager, uri);
		}
		if (!targetServer) {
			throw new Error(
				`No MCP server has resource "${uri}".\n\nAvailable resources:\n${formatAvailableResources(mcpManager)}`,
			);
		}

		let result: MCPResourceReadResult | undefined;
		try {
			result = await mcpManager.readServerResource(targetServer, uri);
		} catch (error) {

View on GitHub (pinned to 9690622007)

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.

Example fix

// before
const resource = await handler.resolve(parseInternalUrl("mcp://notes/roadmap"));
// after
if (!MCPManager.instance()) {
  await initMcpManager(config.mcpServers); // bootstrap before resolving
}
const resource = await handler.resolve(parseInternalUrl("mcp://notes/roadmap"));

Defensive patterns

Strategy: validation

Validate before calling

import { MCPManager } from "../mcp/manager";
if (!MCPManager.instance()) {
  throw new Error("mcp:// URLs unavailable: no MCP servers configured");
}
// safe to resolve mcp:// URLs below

Type guard

function hasMcpManager(): boolean {
  return MCPManager.instance() != null;
}

Try / catch

try {
  return await handler.resolve(url);
} catch (e) {
  if (e instanceof Error && e.message.includes("No MCP manager available")) {
    return null; // MCP unconfigured — degrade gracefully
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/fba6dae6876af5a6. Report an issue: GitHub.