Tencent/WeKnora · error

failed to connect to MCP service: %w

Error message

failed to connect to MCP service: %w

What it means

After creating the client, GetOrCreateClient calls client.Connect(m.ctx) using the manager's long-lived context; any connection failure is wrapped as "failed to connect to MCP service: %w". For SSE this starts a persistent connection, so network reachability, TLS, and server availability all surface here.

Source

Thrown at internal/mcp/manager.go:117

	// Create new client
	config := &ClientConfig{
		Service:   service,
		TenantID:  tenantID,
		Principal: principal,
		OAuthRepo: m.oauthRepo,
	}

	client, err := NewMCPClient(config)
	if err != nil {
		return nil, fmt.Errorf("failed to create MCP client: %w", err)
	}

	// For SSE connections, Connect() starts a persistent connection that needs a long-lived context
	// Use manager's context (m.ctx) which persists for the lifetime of the manager
	// The HTTP client's timeout will handle connection timeouts, not context cancellation
	if err := client.Connect(m.ctx); err != nil {
		return nil, fmt.Errorf("failed to connect to MCP service: %w", err)
	}

	if err := m.initializeClient(service, client, "failed to initialize MCP client"); err != nil {
		return nil, err
	}

	// Store client (only for non-stdio transports)
	m.clients[key] = client

	logger.GetLogger(m.ctx).Infof("MCP client created and initialized for service: %s", service.Name)
	return client, nil
}

// 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

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped cause: connection refused / timeout / TLS error tells you the layer to fix
2. Verify the service URL is reachable from the server host (curl the /sse or endpoint)
3. Confirm the MCP server process is running and listening on the configured port
4. Fix TLS issues (add CA cert or correct scheme); check ingress/firewall rules

Example fix

// before
svc.URL = "http://mcp-internal:9999/sse" // server not listening
// after
// start/verify the MCP server, then:
svc.URL = "http://mcp-internal:8080/sse"

conn, err := net.DialTimeout("tcp", host, 3*time.Second)
if err != nil { return fmt.Errorf("MCP server %s unreachable: %w", host, err) }
conn.Close()

func isConnectFailure(err error) bool { return err != nil && strings.Contains(err.Error(), "failed to connect to MCP service") }

client, err := manager.GetOrCreateClient(ctx, svc)
if err != nil && isConnectFailure(err) {
    // retry with backoff; surface connectivity guidance to the operator
    return retryConnect(ctx, svc, 3)
}

When it happens

Trigger: client.Connect(m.ctx) failing because the MCP server URL is unreachable, returns non-2xx, TLS handshake fails, times out, or rejects the initial SSE/HTTP handshake.

Common situations: MCP server down or deployed behind a misconfigured ingress; DNS failure; wrong port/path; self-signed cert rejected; container network policy blocking egress; server URL using http vs https incorrectly.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to start client: %w
• failed to get MCP client: %w
• failed to execute request: %w
• URL is required for SSE transport
• failed to create SSE client: %w

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