Tencent/WeKnora · error

%s: %w

Error message

%s: %w

What it means

initializeClient calls client.Initialize(initCtx) and on failure disconnects the client and returns fmt.Errorf("%s: %w", errPrefix, err), where errPrefix defaults to "failed to initialize MCP client". Callers (GetOrCreateClient) pass their own prefix. This is the MCP protocol handshake failing, not the TCP connection.

Solutions

1. Read the wrapped cause: server error message, timeout, or protocol mismatch
2. Confirm the URL points at a real MCP server endpoint (test with an MCP inspector/client)
3. Update server or client so MCP protocol versions are compatible
4. Increase the initialize timeout if the server is slow to start; retry connection

Example fix

// before
// URL pointed at plain REST endpoint
err := manager.initializeClient(service, client, "failed to initialize MCP client")
// after
// point the service at the actual MCP endpoint
svc.URL = "http://mcp-server:8080/mcp" // streamable MCP endpoint

resp, err := http.Get(strings.TrimSuffix(svc.URL, "/") + "/")
if err != nil || resp.StatusCode >= 500 { return errors.New("endpoint does not look like a healthy MCP server") }

func isInitializeFailure(err error) bool { return err != nil && strings.Contains(err.Error(), "failed to initialize MCP client") }

client, err := manager.GetOrCreateClient(ctx, svc)
if err != nil && isInitializeFailure(err) {
    // handshake failed: verify MCP endpoint/protocol version, then retry once
    return retryAfterVerifyingEndpoint(ctx, svc)
}

When it happens

Trigger: client.Initialize(ctx) failing during the MCP initialize handshake: server returned an error response, timed out, spoke an incompatible protocol version, or the connection dropped right after Connect succeeded.

Common situations: Endpoint pointing at a non-MCP HTTP server that answers 200 but not the MCP protocol; protocol version mismatch between client and server; server crashed between connect and initialize; slow server exceeding the initialize timeout.

Related errors

• failed to initialize
• argument contains null bytes
• argument contains potentially dangerous pattern
• argument exceeds maximum length (1024 characters)
• command cannot be empty

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/03ed730ae20a1324. Report an issue: GitHub.

Appendix: source

Thrown at internal/mcp/manager.go:149

// initializeClient handles the shared initialization flow with timeout enforcement.
func (m *MCPManager) initializeClient(service *types.MCPService, client MCPClient, errPrefix string) error {
	initTimeout := 30 * time.Second
	if service.AdvancedConfig != nil && service.AdvancedConfig.Timeout > 0 {
		initTimeout = time.Duration(service.AdvancedConfig.Timeout) * time.Second
		if initTimeout > 60*time.Second {
			initTimeout = 60 * time.Second
		}
	}

	initCtx, initCancel := context.WithTimeout(m.ctx, initTimeout)
	defer initCancel()

	if _, err := client.Initialize(initCtx); err != nil {
		client.Disconnect()
		if errPrefix == "" {
			errPrefix = "failed to initialize MCP client"
		}
		return fmt.Errorf("%s: %w", errPrefix, err)
	}

	return nil
}

// GetClient gets an existing client
func (m *MCPManager) GetClient(serviceID string) (MCPClient, bool) {
	m.clientsMu.RLock()
	defer m.clientsMu.RUnlock()

	client, exists := m.clients[serviceID]
	return client, exists
}

// CloseClient closes and removes all cached connections for a service. For
// OAuth services this spans every per-principal connection (keys are prefixed with
// the service ID).
func (m *MCPManager) CloseClient(serviceID string) error {

View on GitHub (pinned to 988cbb0330)