{"record":{"id":"2fdfc9b21fb6951d","repo":"siyuan-note/siyuan","slug":"mcp-server-s-not-connected","errorCode":null,"errorMessage":"mcp server [%s] not connected","messagePattern":"mcp server \\[(.+?)\\] not connected","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/mcp/client/mcp.go","lineNumber":801,"sourceCode":"\treturn tools.CallToolResult{\n\t\tContent: []tools.ContentItem{{\n\t\t\tType: \"text\",\n\t\t\tText: \"mcp tool returned invalid content after execution; execution result may have side effects and must not be \" +\n\t\t\t\t\"retried automatically\",\n\t\t}},\n\t\tIsError:          true,\n\t\tExecutionUnknown: true,\n\t}\n}\n\nfunc trustedReadOnlyHint(server conf.MCPServer, tool *mcp.Tool) bool {\n\treturn server.TrustToolAnnotations && tool.Annotations != nil && tool.Annotations.ReadOnlyHint\n}\n\nfunc callMCPTool(parentCtx context.Context, serverName, toolName string, timeout time.Duration, args map[string]any) (*mcp.CallToolResult, error) {\n\tsession := getMCPSession(serverName)\n\tif session == nil {\n\t\treturn nil, fmt.Errorf(\"mcp server [%s] not connected\", serverName)\n\t}\n\n\tctx, cancel := context.WithTimeout(parentCtx, timeout)\n\tdefer cancel()\n\n\treturn session.CallTool(ctx, &mcp.CallToolParams{\n\t\tName:      toolName,\n\t\tArguments: args,\n\t})\n}\n\nfunc getMCPSession(serverName string) *mcp.ClientSession {\n\tmcpMu.Lock()\n\tdefer mcpMu.Unlock()\n\tfor _, conn := range mcpConns {\n\t\tif conn.ServerName == serverName {\n\t\t\treturn conn.Session\n\t\t}","sourceCodeStart":783,"sourceCodeEnd":819,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/mcp/client/mcp.go#L783-L819","documentation":"Returned by callMCPTool when no connected ClientSession exists for the given server name. getMCPSession walks mcpConns under mcpMu and returns nil if no conn.ServerName matches; the tool-call cannot proceed. This is a connectivity/ordering problem, not a tool-arg problem.","triggerScenarios":"An AI agent or kernel code path invokes callMCPTool(parentCtx, serverName, toolName, timeout, args) while the named MCP server is not in mcpConns: it was never started, failed to connect, was disconnected, or the name does not match (case-sensitive).","commonSituations":"Server was disabled in config or its connect failed silently; the agent used a stale tool list after a ToolListChanged event but before reconnect completed; name mismatch between the tool's owning server and the name passed in; server crashed and reconnectMCPServer has not yet succeeded.","solutions":["Check the MCP runtime state for the server (state, error message) via the kernel's MCP status API before issuing tool calls.","Ensure the server is enabled and connected; if it failed, read its connection error and fix it (see the stdio/http connect errors).","Verify serverName matches exactly (case-sensitive) the Name field of a connected server.","After reconnecting, the ToolListChanged handler triggers reconnectMCPServer; do not call tools on that server until reconnect completes."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check connectivity before issuing a tool call.\nfunc serverConnected(name string) bool {\n    return client.GetMCPSession(name) != nil // (would require exporting getMCPSession)\n}","typeGuard":null,"tryCatchPattern":"// On 'not connected', do NOT retry the tool call blindly; refresh server state first.\nif strings.Contains(err.Error(), \"not connected\") {\n    // read MCP runtime state, reconnect if appropriate, then retry once\n}","preventionTips":["Cache the connected-server list and skip tool calls for disconnected servers.","After a ToolListChanged event, wait for reconnectMCPServer to finish before calling tools.","Match serverName exactly (case-sensitive)."],"tags":["mcp","tool-call","connectivity","ordering"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}