Hmbown/CodeWhale · error · anyhow::Error

Failed to find MCP server: {server_name}

Error message

Failed to find MCP server: {server_name}

What it means

get_or_connect resolves a server by looking in static config (config.servers) first and then the dynamic runtime registry (dynamic_servers); if neither contains the name it fails with this error before attempting any connection. It means the server is not configured at all — distinct from being configured-but-disabled or configured-but-failed.

Source

Thrown at crates/tui/src/mcp.rs:2669

            .map(|conn| conn.is_ready())
            .unwrap_or(false);
        if is_ready {
            return self
                .connections
                .get_mut(server_name)
                .ok_or_else(|| anyhow::anyhow!("MCP connection disappeared for {server_name}"));
        }

        self.drop_connection(server_name, "reconnect");

        // Check static config first, then dynamic servers
        let server_config = self
            .config
            .servers
            .get(server_name)
            .cloned()
            .or_else(|| self.dynamic_servers.read().get(server_name).cloned())
            .ok_or_else(|| anyhow::anyhow!("Failed to find MCP server: {server_name}"))?;

        if !server_config.is_enabled() {
            anyhow::bail!("Failed to connect MCP server '{server_name}': server is disabled");
        }

        let mut connection = McpConnection::connect_with_policy(
            server_name.to_string(),
            server_config,
            &self.config.timeouts,
            self.network_policy.as_ref(),
        )
        .await?;
        connection.catalog_generation = self.catalog_generation.load(Ordering::SeqCst);

        self.connections.insert(server_name.to_string(), connection);
        self.connections
            .get_mut(server_name)
            .ok_or_else(|| anyhow::anyhow!("Failed to store MCP connection for {server_name}"))

View on GitHub (pinned to 8880682c63)

Solutions

1. Check the exact server key in the MCP config file (JSON keys are case-sensitive) and correct the caller.
2. If the server was recently added or removed, force a reload (reload_if_config_changed already runs lazily — verify the file was actually saved) or reconnect.
3. For dynamic servers, confirm registration happened before dispatching to the name.
4. List configured servers (config keys + dynamic_servers) in logs to compare against the requested name.

Example fix

# before (.mcp.json)
{"servers": {"github": {"command": "gh-mcp"}}}
# caller asks for 'Github' -> Failed to find MCP server: Github

# after
{"servers": {"github": {"command": "gh-mcp"}}}
# caller uses 'github' exactly

// Rust: confirm the name resolves before use
fn server_exists(pool: &McpPool, name: &str) -> bool {
    pool.config().servers.contains_key(name)
        || pool.dynamic_server_names().contains(&name.to_string())
}
if !server_exists(&pool, name) {
    bail!("server '{name}' is not configured; check .mcp.json keys (case-sensitive)");
}

// Rust: catch and translate for the model/UI
match pool.get_or_connect(name).await {
    Err(e) if e.to_string().contains("Failed to find MCP server") => {
        let known: Vec<_> = pool.config().servers.keys().cloned().collect();
        bail!("unknown server '{name}'; configured servers: {}", known.join(", "))
    }
    o => o,
}

When it happens

Trigger: Calling a tool/resource/prompt API with a server name that is misspelled, refers to a server removed from the config after the last reload, or a dynamic server that was never registered or was unregistered.

Common situations: Typos in server names from hand-written tool arguments; stale catalogs where the model or UI remembers a server deleted from .mcp config; referencing a dynamically added server before its registration completes; case-sensitive name mismatches (GitHub vs github).

Related errors

• invalid JSON payload at key {MCP_SERVER_DEFINITIONS_KEY}; co
• invalid MCP server definition list in key {MCP_SERVER_DEFINI
• Failed to write MCP config {}: {}
• MCP config path cannot be empty
• MCP config path cannot contain '..' components

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/9c3b0aa6685580c6. Report an issue: GitHub.