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.

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)

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: %w
• failed to get MCP client: %w
• failed to list resources: %w
• mcp service not found
• tool_name is required

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