{"record":{"id":"a2ddf3addac60292","repo":"zeroclaw-labs/zeroclaw","slug":"mcp-server-server-name-rejected-initialize","errorCode":null,"errorMessage":"MCP server `{server_name}` rejected initialize: {:?}","messagePattern":"MCP server `(.+?)` rejected initialize: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-tools/src/mcp_client.rs","lineNumber":74,"sourceCode":"                \"version\": env!(\"CARGO_PKG_VERSION\")\n            }\n        }),\n    );\n\n    let init_lifecycle = McpRequestLifecycle::uncoordinated(epoch);\n    let init_resp = timeout(\n        Duration::from_secs(RECV_TIMEOUT_SECS),\n        transport.send_and_recv(&init_req, &init_lifecycle),\n    )\n    .await\n    .with_context(|| {\n        format!(\n            \"MCP server `{server_name}` timed out after {RECV_TIMEOUT_SECS}s waiting for initialize response\"\n        )\n    })??;\n\n    if init_resp.error.is_some() {\n        bail!(\n            \"MCP server `{server_name}` rejected initialize: {:?}\",\n            init_resp.error\n        );\n    }\n\n    // Parse server-advertised capabilities from the initialize result.\n    let capabilities = init_resp\n        .result\n        .as_ref()\n        .map(McpServerCapabilities::from_init_result)\n        .unwrap_or_default();\n\n    // Notify the server the client is initialized (notifications expect no\n    // response). Best effort — ignore errors.\n    let notif = JsonRpcRequest::notification(\"notifications/initialized\", json!({}));\n    let notif_lifecycle = McpRequestLifecycle::uncoordinated(epoch);\n    let _ = transport.send_and_recv(&notif, &notif_lifecycle).await;\n","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-tools/src/mcp_client.rs#L56-L92","documentation":"During connect, the client sends the MCP initialize request; this error means the server answered with a JSON-RPC error object instead of a result — a protocol-level rejection of the handshake, distinct from a timeout or a crashed process. The server's error code and message are embedded via Debug formatting of the error field.","triggerScenarios":"Running a non-MCP program as the configured command; wrong args or env causing the server to reject initialize; a server build that only speaks an incompatible MCP protocol version; an HTTP endpoint answering the initialize route with a JSON-RPC error (404, auth required).","commonSituations":"Typos in the MCP server command; pointing the config at a plain OpenAI-plugin/HTTP API instead of an MCP server; version drift after upgrading the server package; auth-protected HTTP MCP endpoints missing required headers.","solutions":["Read the embedded error field — its code and message say exactly what the server rejected","Run the configured command standalone and confirm it speaks MCP (e.g. with an MCP inspector) before reconnecting","Fix the command/args/env in the MCP server config; for HTTP servers verify the URL and required headers","Pin or upgrade the server to a version whose MCP protocol revision the client supports"],"exampleFix":"# before\n[minecraft]\ncommand = \"mc-server\"\n\n# after\n[minecraft]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/data\"]","handlingStrategy":"try-catch","validationCode":"// Fail fast at startup instead of mid-task\nmatch client_connect(&server_config).await {\n    Ok(c) => c,\n    Err(e) if e.to_string().contains(\"rejected initialize\") => {\n        log_and_alert(\"MCP server misconfigured: {}\", e);\n        return Err(e);\n    }\n    Err(e) => return Err(e),\n}","typeGuard":"fn is_handshake_rejected(err: &anyhow::Error) -> bool {\n    err.to_string().contains(\"rejected initialize\")\n}","tryCatchPattern":"Treat as fatal for this server: do not retry the same config. Catch at connect time, surface the embedded server error, and take the server out of rotation until its command/args/env are fixed.","preventionTips":["Smoke-test new MCP server entries with an inspector before adding them to production config","Pin server package versions so protocol upgrades are deliberate","For HTTP servers, verify URL and auth headers before enabling"],"tags":["mcp","json-rpc","handshake","protocol"],"backgroundTag":"handshake-failed","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}