{"record":{"id":"28e16cb387e74b54","repo":"Tencent/WeKnora","slug":"failed-to-connect-to-mcp-service-w","errorCode":null,"errorMessage":"failed to connect to MCP service: %w","messagePattern":"failed to connect to MCP service: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/mcp/manager.go","lineNumber":117,"sourceCode":"\n\t// Create new client\n\tconfig := &ClientConfig{\n\t\tService:   service,\n\t\tTenantID:  tenantID,\n\t\tPrincipal: principal,\n\t\tOAuthRepo: m.oauthRepo,\n\t}\n\n\tclient, err := NewMCPClient(config)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create MCP client: %w\", err)\n\t}\n\n\t// For SSE connections, Connect() starts a persistent connection that needs a long-lived context\n\t// Use manager's context (m.ctx) which persists for the lifetime of the manager\n\t// The HTTP client's timeout will handle connection timeouts, not context cancellation\n\tif err := client.Connect(m.ctx); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to connect to MCP service: %w\", err)\n\t}\n\n\tif err := m.initializeClient(service, client, \"failed to initialize MCP client\"); err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Store client (only for non-stdio transports)\n\tm.clients[key] = client\n\n\tlogger.GetLogger(m.ctx).Infof(\"MCP client created and initialized for service: %s\", service.Name)\n\treturn client, nil\n}\n\n// initializeClient handles the shared initialization flow with timeout enforcement.\nfunc (m *MCPManager) initializeClient(service *types.MCPService, client MCPClient, errPrefix string) error {\n\tinitTimeout := 30 * time.Second\n\tif service.AdvancedConfig != nil && service.AdvancedConfig.Timeout > 0 {\n\t\tinitTimeout = time.Duration(service.AdvancedConfig.Timeout) * time.Second","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/mcp/manager.go#L99-L135","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped cause: connection refused / timeout / TLS error tells you the layer to fix","Verify the service URL is reachable from the server host (curl the /sse or endpoint)","Confirm the MCP server process is running and listening on the configured port","Fix TLS issues (add CA cert or correct scheme); check ingress/firewall rules"],"exampleFix":"// before\nsvc.URL = \"http://mcp-internal:9999/sse\" // server not listening\n// after\n// start/verify the MCP server, then:\nsvc.URL = \"http://mcp-internal:8080/sse\"","handlingStrategy":"retry","validationCode":"conn, err := net.DialTimeout(\"tcp\", host, 3*time.Second)\nif err != nil { return fmt.Errorf(\"MCP server %s unreachable: %w\", host, err) }\nconn.Close()","typeGuard":"func isConnectFailure(err error) bool { return err != nil && strings.Contains(err.Error(), \"failed to connect to MCP service\") }","tryCatchPattern":"client, err := manager.GetOrCreateClient(ctx, svc)\nif err != nil && isConnectFailure(err) {\n    // retry with backoff; surface connectivity guidance to the operator\n    return retryConnect(ctx, svc, 3)\n}","preventionTips":["Health-check the MCP server URL before registering and periodically after","Use stable DNS names and correct http/https scheme","Allowlist egress from the app host to MCP servers in firewalls/security groups"],"tags":["mcp","network","connection","sse"],"backgroundTag":"connection-refused","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}