What causes "MCP server %q not found" in sipeed/picoclaw?

List configured servers with picoclaw mcp list and copy the exact key

MCP server %q not found

Error message

MCP server %q not found

What it means

Returned by picoclaw mcp show <name> when the name is not a key under tools.mcp.servers in the loaded config. The lookup is an exact, case-sensitive map-key match. The command exits before printing anything about the server.

Source

Thrown at cmd/picoclaw/internal/mcp/show.go:159

}

func newShowCommand() *cobra.Command {
	var timeout time.Duration

	cmd := &cobra.Command{
		Use:   "show <name>",
		Short: "Show details and tools for a configured MCP server",
		Args:  cobra.ExactArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			cfg, err := loadConfig()
			if err != nil {
				return err
			}

			name := args[0]
			server, exists := cfg.Tools.MCP.Servers[name]
			if !exists {
				return fmt.Errorf("MCP server %q not found", name)
			}

			serverInfo := buildServerInfo(name, server, cfg.Tools.MCP.Discovery.Enabled)

			if !server.Enabled {
				cliui.PrintMCPShow(cmd.OutOrStdout(), serverInfo, nil, true)
				return nil
			}

			ctx, cancel := context.WithTimeout(context.Background(), timeout)
			defer cancel()

			details, err := serverShowProbe(ctx, name, server, cfg.WorkspacePath())
			if err != nil {
				return fmt.Errorf("failed to connect to MCP server %q: %w", name, err)
			}

			tools := make([]cliui.MCPShowTool, 0, len(details))

View on GitHub (pinned to 49183d7e8d)

Solutions

List configured servers with picoclaw mcp list and copy the exact key
Re-run picoclaw mcp show <exact-name>
If the list is empty, add the server first with picoclaw mcp add
Verify which config file picoclaw loads for the current workspace

Example fix

# before
$ picoclaw mcp show github
MCP server "github" not found

# after
$ picoclaw mcp list
NAME       TYPE      ENABLED
gh-tools   http      true
$ picoclaw mcp show gh-tools

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := cfg.Tools.MCP.Servers[name]; !ok {
  available := make([]string, 0, len(cfg.Tools.MCP.Servers))
  for k := range cfg.Tools.MCP.Servers {
    available = append(available, k)
  }
  return fmt.Errorf("MCP server %q not found; available: %v", name, available)
}

Type guard

func isMCPServerNotFound(err error) bool {
  return err != nil && strings.Contains(err.Error(), "MCP server") && strings.Contains(err.Error(), "not found")
}

Try / catch

if err := showCmd.Execute(); err != nil {
  if isMCPServerNotFound(err) {
    // fall back to `picoclaw mcp list` output so the user sees valid names
  }
  return err
}

Prevention

Copy names verbatim from picoclaw mcp list
Remember the config resolved depends on the workspace — run list in the same directory
Add servers before referencing them in scripts

When it happens

Trigger: picoclaw mcp show with a typo'd or wrongly-cased name; showing a server that was never added to this config; picoclaw resolving a different config file (workspace vs user) than the one containing the entry.

Common situations: Documentation or README examples naming servers that were never added locally; multiple config files causing name confusion; automation referencing renamed servers.

Related errors

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