sipeed/picoclaw · error

MCP server '%s' is configured but not connected

Error message

MCP server '%s' is configured but not connected

What it means

After validation passes, ListMCPTools calls ensureMCPInitialized and then fetches the MCP manager; al.mcp.getManager() returned nil, meaning the MCP runtime never came up. Initialization failures are only logged (WarnCF), not returned, so this error surfaces one step later as 'configured but not connected' — the manager itself is absent.

Source

Thrown at pkg/agent/agent_command.go:220

			}
			if !serverCfg.Enabled {
				return nil, fmt.Errorf("MCP server '%s' is configured but disabled", resolvedName)
			}
			if !cfg.Tools.IsToolEnabled("mcp") {
				return nil, fmt.Errorf("MCP integration is disabled")
			}

			if err := al.ensureMCPInitialized(ctx); err != nil {
				logger.WarnCF("agent", "Failed to initialize MCP runtime for command",
					map[string]any{
						"server": resolvedName,
						"error":  err.Error(),
					})
			}

			manager := al.mcp.getManager()
			if manager == nil {
				return nil, fmt.Errorf("MCP server '%s' is configured but not connected", resolvedName)
			}

			conn, ok := manager.GetServer(resolvedName)
			if !ok {
				return nil, fmt.Errorf("MCP server '%s' is configured but not connected", resolvedName)
			}

			toolInfos := make([]commands.MCPToolInfo, 0, len(conn.Tools))
			for _, tool := range conn.Tools {
				if tool == nil {
					continue
				}
				name := strings.TrimSpace(tool.Name)
				if name == "" {
					continue
				}

				description := strings.TrimSpace(tool.Description)

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Check logs for the preceding 'Failed to initialize MCP runtime for command' warning — it carries the root-cause error field
2. Fix the underlying init failure (server URLs, auth, network) and retry the command, which re-runs ensureMCPInitialized
3. Restart the agent process if the manager was lost after a hot reload
4. Verify at least one enabled server is reachable from the host

if al.mcp.getManager() == nil {
    // call ensureMCPInitialized once more / surface the logged root cause before retrying
}

func mcpRuntimeReady(al *AgentLoop) bool { return al.mcp.getManager() != nil }

tools, err := rt.ListMCPTools(ctx, name)
if err != nil && strings.Contains(err.Error(), "not connected") && al.mcp.getManager() == nil {
    // manager missing: fix init root cause (see logs), then retry after re-init
}

When it happens

Trigger: MCP init failed (no reachable servers, bad global MCP settings, runtime construction error) so the manager was never created; MCP initialized lazily and the first init attempt raced or crashed; discovery disabled with nothing started.

Common situations: All configured servers unreachable at startup in offline environments; bug or panic during MCP runtime construction; deferred discovery never triggered a first connect; process in a degraded state after config hot-reload.

Related errors

• command unavailable: config not loaded
• server name is required
• channel manager not initialized
• process options not available
• reload not configured

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/8db361c32e04dcbd. Report an issue: GitHub.