{"record":{"id":"c1cb89a8c82ee35c","repo":"Kuberwastaken/claurst","slug":"mcp-server-connection-failed","errorCode":null,"errorMessage":"MCP server '{}' connection failed: {}","messagePattern":"MCP server '(.+?)' connection failed: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src-rust/crates/mcp/src/connection_manager.rs","lineNumber":179,"sourceCode":"\r\n        match Self::connect_expanded_config(name, &config).await {\r\n            Ok(client) => {\r\n                let tool_count = client.tools.len();\r\n                let client_arc = Arc::new(client);\r\n                let mut st = state_arc.lock().await;\r\n                st.client = Some(client_arc);\r\n                st.status = McpServerStatus::Connected { tool_count };\r\n                info!(server = %name, transport = %config.server_type, tools = tool_count, \"MCP server connected\");\r\n                Ok(())\r\n            }\r\n            Err(e) => {\r\n                let msg = e.to_string();\r\n                let mut st = state_arc.lock().await;\r\n                st.client = None;\r\n                st.status = McpServerStatus::Disconnected {\r\n                    last_error: Some(msg.clone()),\r\n                };\r\n                Err(anyhow::anyhow!(\"MCP server '{}' connection failed: {}\", name, msg))\r\n            }\r\n        }\r\n    }\r\n\r\n    /// Disconnect a server and cancel its reconnect loop.\r\n    pub async fn disconnect(&self, name: &str) {\r\n        {\r\n            let mut handles = self.reconnect_handles.lock().await;\r\n            if let Some(handle) = handles.remove(name) {\r\n                handle.abort();\r\n            }\r\n        }\r\n\r\n        if let Some(entry) = self.state.get(name) {\r\n            let mut st = entry.value().lock().await;\r\n            st.client = None;\r\n            st.status = McpServerStatus::Disconnected { last_error: None };\r\n        }\r","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/Kuberwastaken/claurst/blob/b0637c97ec34144387cbf2f74f65df6d16a6cef1/src-rust/crates/mcp/src/connection_manager.rs#L161-L197","documentation":"After a failed MCP client connection attempt, connect marks the server Disconnected with the underlying error message stored as last_error, then returns this wrapped error including the server name and root cause. The state machine is updated before the error propagates so callers and the reconnect loop can inspect what failed.","triggerScenarios":"connect(name) on a registered server whose client handshake/transport fails: server process not installed/unlaunchable, wrong command or URL in config, server crashed during MCP handshake, or network failure for HTTP/SSE servers.","commonSituations":"MCP server command not on PATH; bad args/env in the server config; protocol version mismatch during initialize handshake; server port closed; server binary panics on startup.","solutions":["Inspect the embedded root cause (last_error / inner message) — fix that underlying failure first.","Verify the server command, args, and env in the MCP config; run the command manually to test.","For remote servers, check the URL/port is reachable.","Rely on restart/reconnect after fixing config, since state is already Disconnected."],"exampleFix":"// before\nmanager.connect(\"filesystem\").await?;\n// after\nif let Err(e) = manager.connect(\"filesystem\").await {\n    eprintln!(\"filesystem MCP unavailable, continuing without it: {}\", e);\n    // check server command: npx -y @modelcontextprotocol/server-filesystem\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match manager.connect(name).await {\n    Ok(()) => {},\n    Err(e) => {\n        // error embeds root cause after \"connection failed: ...\"\n        tracing::warn!(\"MCP '{}' unavailable: {}\", name, e);\n        // proceed degraded; inspect McpServerStatus::Disconnected.last_error for detail\n    }\n}","preventionTips":["Run the server command manually to verify it starts before wiring it up.","Pin MCP server versions to avoid protocol handshake breakage.","Check last_error in Disconnected status for the root cause.","Use connect_all and tolerate partial failures rather than hard-failing."],"tags":["mcp","connection","handshake","network"],"backgroundTag":"connection-refused","analyzedSha":"b0637c97ec34144387cbf2f74f65df6d16a6cef1","analyzedAt":"2026-09-10T00:24:58.650Z","contentChangedAt":"2026-09-10T00:24:58.650Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}