Hmbown/CodeWhale · error · anyhow::Error

required MCP server failed to initialize

Error message

required MCP server failed to initialize

What it means

connect_all connects every enabled configured server, then walks config.servers and pushes this error for each entry that is both required and enabled but whose connection is not is_ready() (Ready state plus catalog_authorized). It aggregates startup failures: the server either failed to connect/initialize, or connected but its reviewed-plugin catalog is not current, so it cannot satisfy its required contract.

Source

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

            .collect();

        for name in names {
            if let Err(e) = self.get_or_connect(&name).await {
                errors.push((name, e));
            }
        }

        for (name, server_cfg) in &self.config.servers {
            if server_cfg.required
                && server_cfg.is_enabled()
                && !self
                    .connections
                    .get(name)
                    .is_some_and(McpConnection::is_ready)
            {
                errors.push((
                    name.clone(),
                    anyhow::anyhow!("required MCP server failed to initialize"),
                ));
            }
        }

        errors
    }

    /// The single definition of an MCP tool's model-facing name.
    ///
    /// [`Self::all_tools`] (which builds the model catalog) and
    /// [`Self::resolved_tool_servers`] (which tells tool inspection which
    /// server owns a name) both call this, so a human-facing server
    /// attribution can never drift from the name the model actually received.
    #[must_use]
    pub fn mcp_model_tool_name(server: &str, tool: &str) -> String {
        format!("mcp_{server}_{tool}")
    }

View on GitHub (pinned to 8880682c63)

Solutions

1. Check the per-server connect error that accompanies or precedes this one in the errors list (and logs) — it names the root cause; fix command path, URL, env, or auth.
2. Verify the server name in the required entry actually matches a connectable server definition.
3. If the server is optional in practice, drop the required flag so startup degrades gracefully.
4. For reviewed plugins, update/re-approve the bundle so catalog_authorized passes and is_ready becomes true.

Example fix

# before (.mcp.json)
{"servers": {"db": {"command": "/usr/local/bin/db-mcp", "required": true}}}
# binary absent at that path -> required MCP server failed to initialize

# after — correct path, or relax the requirement
{"servers": {"db": {"command": "db-mcp", "required": true, "env": {"PATH": "/opt/db/bin:$PATH"}}}}
# or: {"command": "db-mcp", "required": false}

// Rust: pre-flight the required server before startup
async fn required_servers_ready(pool: &mut McpPool) -> Result<()> {
    for (name, cfg) in pool.config().servers.iter() {
        if cfg.required && cfg.is_enabled() {
            pool.get_or_connect(name).await
                .with_context(|| format!("required server '{name}' failed"))?;
        }
    }
    Ok(())
}

// Rust: connect_all returns a Vec, inspect per-server entries
let errors = pool.connect_all().await;
for (name, e) in &errors {
    if e.to_string().contains("required MCP server failed to initialize") {
        tracing::error!("startup blocked by required server '{name}': {e:#}");
    }
}

When it happens

Trigger: A required: true server whose command/URL is wrong, times out during initialize, returns an error, or whose reviewed plugin authority is stale — connect_all records (name, this error) in its Vec of per-server failures. Note connect_all returns errors rather than Err, so callers inspect the list.

Common situations: CI or fresh clones where a required server binary isn't installed or its env vars are absent; network-restricted environments blocking a required remote MCP server; plugin bundles updated but not re-approved; auth tokens for a required server expired.

Related errors

• Stdio transport closed {stderr}
• ${name} is required
• ${name} is required
• -32603
• invalid JSON payload at key {MCP_SERVER_DEFINITIONS_KEY}; co

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