Tencent/WeKnora · error

failed to create MCP client: %w

Error message

failed to create MCP client: %w

What it means

GetOrCreateClient builds an MCPClientConfig and calls NewMCPClient; if client construction fails it wraps the cause with "failed to create MCP client: %w". This happens before any network connection — typically invalid transport config, bad URL parsing, or unsupported transport type.

Source

Thrown at internal/mcp/manager.go:110

	defer m.clientsMu.Unlock()

	// Double check after acquiring write lock
	client, exists = m.clients[key]
	if exists && client.IsConnected() {
		return client, nil
	}

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

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped cause for the exact construction failure (URL parse error, unsupported transport, etc.)
2. Validate the MCPService URL has a scheme and is reachable before saving it
3. Re-save the service configuration with all required fields populated
4. Confirm the transport type is one of the supported values (SSE or HTTP streamable)

Example fix

// before
svc.URL = "localhost:3000" // no scheme -> NewMCPClient fails
// after
svc.URL = "http://localhost:3000"

if svc.URL == "" { return errors.New("MCP service URL is required") }
if _, err := url.Parse(svc.URL); err != nil { return fmt.Errorf("invalid MCP service URL: %w", err) }

func hasValidURL(svc *types.MCPService) bool {
    u, err := url.Parse(svc.URL)
    return err == nil && u.Scheme != "" && u.Host != ""
}

client, err := manager.GetOrCreateClient(ctx, svc)
if err != nil && strings.Contains(err.Error(), "failed to create MCP client") {
    return fmt.Errorf("check MCP service config for %q: %w", svc.Name, err)
}

When it happens

Trigger: NewMCPClient(config) returning an error because the MCPService config is invalid (malformed URL, unknown transport type, missing required fields) when GetOrCreateClient is invoked.

Common situations: Service URL missing scheme (e.g. "localhost:3000" instead of "http://localhost:3000"); transport type string corrupted in DB; required config fields blanked by a partial update.

Related errors

• MCP client config and service are required
• URL is required for SSE transport
• URL is required for HTTP Streamable transport
• stdio transport is disabled for security reasons; please use
• OAuth repository is required for OAuth MCP services

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