siyuan-note/siyuan · error

mcp server [ ] not connected

Error message

mcp server [%s] not connected

What it means

callMCPTool looks up a live MCP client session by server name via getMCPSession; if no connected session exists for that server, the tool call cannot proceed and this error is returned. It means the named MCP server has not completed a connection or its session was lost/disconnected.

Solutions

1. Open the MCP server settings and reconnect/enable the named server, then retry the tool call
2. Check the server's connection status and logs to see why the session dropped (auth failure, network error)
3. Verify the tool is invoked with the exact configured server name (case and spelling)
4. Restart the kernel or refresh MCP connections if the session registry is stale

// guard before calling a tool
if getMCPSession(serverName) == nil {
    return fmt.Errorf("server %q not connected; reconnect first", serverName)
}

res, err := callMCPTool(ctx, serverName, toolName, timeout, args)
if err != nil && strings.Contains(err.Error(), "not connected") {
    // re-establish the connection, then retry once
    if cerr := reconnectMCPServer(serverName); cerr == nil {
        res, err = callMCPTool(ctx, serverName, toolName, timeout, args)
    }
}

When it happens

Trigger: A tool invocation names a server with no entry in the session registry: the server was never connected, connection failed at startup, the session was disconnected, or the server name is misspelled.

Common situations: Calling a tool before the MCP server finished connecting; the remote server went offline and the session was dropped; the server was disabled or removed in settings; using a stale server name after renaming the entry.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• agent runtime turn is not finalized
• attr must be a string or null (got %T)
• command is required for stdio server
• configuration is not initialized
• connect

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/2fdfc9b21fb6951d. Report an issue: GitHub.

Appendix: source

Thrown at kernel/mcp/client/mcp.go:808

	return tools.CallToolResult{
		Content: []tools.ContentItem{{
			Type: "text",
			Text: "mcp tool returned invalid content after execution; execution result may have side effects and must not be " +
				"retried automatically",
		}},
		IsError:          true,
		ExecutionUnknown: true,
	}
}

func trustedReadOnlyHint(server conf.MCPServer, tool *mcp.Tool) bool {
	return server.TrustToolAnnotations && tool.Annotations != nil && tool.Annotations.ReadOnlyHint
}

func callMCPTool(parentCtx context.Context, serverName, toolName string, timeout time.Duration, args map[string]any) (*mcp.CallToolResult, error) {
	session := getMCPSession(serverName)
	if session == nil {
		return nil, fmt.Errorf("mcp server [%s] not connected", serverName)
	}

	ctx, cancel := context.WithTimeout(parentCtx, timeout)
	defer cancel()

	return session.CallTool(ctx, &mcp.CallToolParams{
		Name:      toolName,
		Arguments: args,
	})
}

func getMCPSession(serverName string) *mcp.ClientSession {
	mcpMu.Lock()
	defer mcpMu.Unlock()
	for _, conn := range mcpConns {
		if conn.ServerName == serverName {
			return conn.Session
		}

View on GitHub (pinned to 9f775e8a12)