sipeed/picoclaw · error

MCP server '%s' is not configured

Error message

MCP server '%s' is not configured

What it means

ListMCPTools did a case-insensitive scan of cfg.Tools.MCP.Servers and found no key matching the requested server name. The name is not defined in configuration at all, so no tools can be listed. The check is EqualFold, so casing is not the problem — the entry is missing.

Source

Thrown at pkg/agent/agent_command.go:201

				return nil, fmt.Errorf("command unavailable: config not loaded")
			}

			serverName = strings.TrimSpace(serverName)
			if serverName == "" {
				return nil, fmt.Errorf("server name is required")
			}

			resolvedName := ""
			var serverCfg config.MCPServerConfig
			for name, candidate := range cfg.Tools.MCP.Servers {
				if strings.EqualFold(name, serverName) {
					resolvedName = name
					serverCfg = candidate
					break
				}
			}
			if resolvedName == "" {
				return nil, fmt.Errorf("MCP server '%s' is not configured", serverName)
			}
			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 {

View on GitHub (pinned to 49183d7e8d)

Solutions

  1. Run /mcp list (ListMCPServers) to see exact configured names, then retry with one of them
  2. Add the missing server under tools.mcp.servers in the active config file and reload
  3. Verify which config file is active (workspace vs global) if you edited one and the server is still reported missing

Example fix

# before
/mcp tools clawhubb   # typo

# after
/mcp list               # confirm exact name
/mcp tools clawhub
Defensive patterns

Strategy: validation

Validate before calling

func serverConfigured(cfg *config.Config, name string) bool {
    for n := range cfg.Tools.MCP.Servers {
        if strings.EqualFold(n, name) { return true }
    }
    return false
}

Type guard

func isConfiguredServer(cfg *config.Config, name string) (string, bool) {
    for n := range cfg.Tools.MCP.Servers {
        if strings.EqualFold(n, name) { return n, true }
    }
    return "", false
}

Prevention

When it happens

Trigger: Calling the tool-list command with a server name absent from the `tools.mcp.servers` map in the picoclaw config: typo, referencing a server defined in a different config file, or expecting a server that was never added.

Common situations: Server was renamed or removed from config; user copies a server name from docs/another project; config file being edited points elsewhere (workspace vs user config precedence); server registered programmatically only in another process.

Related errors

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