feat(remote): add headers-based authentication and cursor tool support (#12)

- Add support for headers-based auth via mcp.header.* labels as alternative to OAuth
- Add cursor to list of tools supporting remote MCP servers
- Support http:// URLs in addition to https:// for remote servers
- Refactor ValidateRemoteServerOAuth to ValidateRemoteServerAuth supporting both auth methods
- Add ExtractHeaders function with environment variable expansion
- Update tests to reflect cursor support for remote servers

Co-authored-by: Tom Harada <harathom@amazon.com>

Author: p10q

cmd/integration_test.go

@@ -166,9 +166,9 @@ REMOTE_CLIENT_SECRET=test-client-secret
 		t.Errorf("q-cli should support mixed servers: %v", err)
 	}
 
-	// Should fail for unsupported tools
-	if err := ValidateToolSupport("cursor", mixedServers); err == nil {
-		t.Error("cursor should not support remote servers")
+	// Should pass for cursor (now supported)
+	if err := ValidateToolSupport("cursor", mixedServers); err != nil {
+		t.Errorf("cursor should support remote servers: %v", err)
 	}
 
 	// Should pass when no tool is specified

cmd/remote.go

@@ -11,45 +11,116 @@ import (
 	"time"
 )
 
-// IsRemoteServer detects if a service is a remote MCP server by checking if the command starts with https://
+// IsRemoteServer detects if a service is a remote MCP server by checking if the command starts with https:// or http://
 func IsRemoteServer(service Service) bool {
-	return strings.HasPrefix(service.Command, "https://")
+	return strings.HasPrefix(service.Command, "https://") || strings.HasPrefix(service.Command, "http://")
 }
 
-// ValidateRemoteServerOAuth validates that a remote server has all required OAuth labels
-func ValidateRemoteServerOAuth(name string, service Service) error {
-	requiredLabels := []string{
-		"mcp.grant-type",
-		"mcp.token-endpoint",
-		"mcp.client-id",
-		"mcp.client-secret",
+// UsesHeadersAuth checks if a remote server uses headers-based authentication instead of OAuth
+func UsesHeadersAuth(service Service) bool {
+	// Check if any mcp.header.* labels exist
+	for label := range service.Labels {
+		if strings.HasPrefix(label, "mcp.header.") {
+			return true
+		}
 	}
+	return false
+}
 
-	var missingLabels []string
-	for _, label := range requiredLabels {
-		if _, exists := service.Labels[label]; !exists {
-			missingLabels = append(missingLabels, label)
-		}
+// ValidateRemoteServerAuth validates that a remote server has either OAuth or headers-based auth configured
+func ValidateRemoteServerAuth(name string, service Service) error {
+	usesHeaders := UsesHeadersAuth(service)
+	hasOAuthLabels := service.Labels["mcp.grant-type"] != ""
+
+	if !usesHeaders && !hasOAuthLabels {
+		return fmt.Errorf("remote server '%s' must have either OAuth labels (mcp.grant-type, mcp.token-endpoint, mcp.client-id, mcp.client-secret) or headers labels (mcp.header.*)", name)
 	}
 
-	if len(missingLabels) > 0 {
-		return fmt.Errorf("remote server '%s' missing required OAuth labels: %s",
-			name, strings.Join(missingLabels, ", "))
+	if usesHeaders && hasOAuthLabels {
+		return fmt.Errorf("remote server '%s' cannot have both OAuth labels and headers labels", name)
 	}
 
-	// Validate grant type is client_credentials
-	if grantType := service.Labels["mcp.grant-type"]; grantType != "client_credentials" {
-		return fmt.Errorf("remote server '%s' must use 'client_credentials' grant type, got: %s",
-			name, grantType)
+	if hasOAuthLabels {
+		// Validate OAuth configuration
+		requiredLabels := []string{
+			"mcp.grant-type",
+			"mcp.token-endpoint",
+			"mcp.client-id",
+			"mcp.client-secret",
+		}
+
+		var missingLabels []string
+		for _, label := range requiredLabels {
+			if _, exists := service.Labels[label]; !exists {
+				missingLabels = append(missingLabels, label)
+			}
+		}
+
+		if len(missingLabels) > 0 {
+			return fmt.Errorf("remote server '%s' missing required OAuth labels: %s",
+				name, strings.Join(missingLabels, ", "))
+		}
+
+		// Validate grant type is client_credentials
+		if grantType := service.Labels["mcp.grant-type"]; grantType != "client_credentials" {
+			return fmt.Errorf("remote server '%s' must use 'client_credentials' grant type, got: %s",
+				name, grantType)
+		}
 	}
 
 	return nil
 }
 
+// ValidateRemoteServerOAuth validates that a remote server has all required OAuth labels (deprecated, use ValidateRemoteServerAuth)
+func ValidateRemoteServerOAuth(name string, service Service) error {
+	return ValidateRemoteServerAuth(name, service)
+}
+
+// ExtractHeaders extracts headers from service labels (mcp.header.*) with environment variable expansion
+func ExtractHeaders(service Service, envVars map[string]string) (map[string]string, error) {
+	headers := make(map[string]string)
+	hasHeaders := false
+
+	for label, value := range service.Labels {
+		if strings.HasPrefix(label, "mcp.header.") {
+			hasHeaders = true
+			// Extract header name (everything after "mcp.header.")
+			headerName := strings.TrimPrefix(label, "mcp.header.")
+			if headerName == "" {
+				continue
+			}
+
+			// Skip empty placeholder headers (e.g., "X-Empty: "" for servers that need no auth)
+			if headerName == "X-Empty" && value == "" {
+				continue
+			}
+
+			// Expand environment variables in header value
+			expandedValue := expandEnvVars(value, envVars)
+
+			// Validate that environment variables were resolved
+			if strings.Contains(expandedValue, "${") || (strings.Contains(expandedValue, "$") && !strings.HasPrefix(expandedValue, "$")) {
+				return nil, fmt.Errorf("environment variable in header '%s' was not resolved: %s", headerName, expandedValue)
+			}
+
+			headers[headerName] = expandedValue
+		}
+	}
+
+	// Return headers map (can be empty for servers with no authentication)
+	// If no mcp.header.* labels exist at all, that's an error (use OAuth or headers)
+	if !hasHeaders {
+		return nil, fmt.Errorf("no headers found (expected mcp.header.* labels)")
+	}
+
+	return headers, nil
+}
+
 // remoteSupportedTools defines which tools support remote MCP servers
 var remoteSupportedTools = map[string]bool{
-	"kiro":  true,
-	"q-cli": true,
+	"cursor": true,
+	"kiro":   true,
+	"q-cli":  true,
 }
 
 // ValidateToolSupport validates that the specified tool supports remote servers if any are present

cmd/set.go

@@ -61,10 +61,10 @@ If no profile is specified, it uses default servers.`,
 			}
 		}
 
-		// Validate remote servers have required OAuth labels
+		// Validate remote servers have required auth configuration (OAuth or headers)
 		for name, service := range servers {
 			if IsRemoteServer(service) {
-				if err := ValidateRemoteServerOAuth(name, service); err != nil {
+				if err := ValidateRemoteServerAuth(name, service); err != nil {
 					fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 					os.Exit(1)
 				}
@@ -165,22 +165,47 @@ func convertToMCPConfig(servers map[string]Service, envVars map[string]string) M
 			mcpServer.Type = "http"
 			mcpServer.URL = service.Command
 
-			// Acquire OAuth access token for remote servers
-			oauthConfig, err := ExtractOAuthConfig(service, envVars)
-			if err != nil {
-				fmt.Fprintf(os.Stderr, "Error extracting OAuth config for '%s': %v\n", name, err)
-				os.Exit(1)
+			// Merge service environment variables into envVars for expansion
+			serviceEnvVars := make(map[string]string)
+			for k, v := range envVars {
+				serviceEnvVars[k] = v
 			}
-
-			accessToken, err := AcquireAccessTokenWithFeedback(name, oauthConfig)
-			if err != nil {
-				fmt.Fprintf(os.Stderr, "Failed to acquire access token for '%s': %v\n", name, err)
-				os.Exit(1)
+			// Add service-specific environment variables (with expansion)
+			for key, value := range service.Environment {
+				expandedValue := expandEnvVars(value, envVars)
+				serviceEnvVars[key] = expandedValue
 			}
 
-			// Set Authorization header with Bearer token
-			mcpServer.Headers = map[string]string{
-				"Authorization": fmt.Sprintf("Bearer %s", accessToken),
+			if UsesHeadersAuth(service) {
+				// Headers-based authentication
+				headers, err := ExtractHeaders(service, serviceEnvVars)
+				if err != nil {
+					fmt.Fprintf(os.Stderr, "Error extracting headers for '%s': %v\n", name, err)
+					os.Exit(1)
+				}
+				// Always set headers, even if empty (for servers with no auth)
+				if headers == nil {
+					headers = make(map[string]string)
+				}
+				mcpServer.Headers = headers
+			} else {
+				// OAuth-based authentication
+				oauthConfig, err := ExtractOAuthConfig(service, serviceEnvVars)
+				if err != nil {
+					fmt.Fprintf(os.Stderr, "Error extracting OAuth config for '%s': %v\n", name, err)
+					os.Exit(1)
+				}
+
+				accessToken, err := AcquireAccessTokenWithFeedback(name, oauthConfig)
+				if err != nil {
+					fmt.Fprintf(os.Stderr, "Failed to acquire access token for '%s': %v\n", name, err)
+					os.Exit(1)
+				}
+
+				// Set Authorization header with Bearer token
+				mcpServer.Headers = map[string]string{
+					"Authorization": fmt.Sprintf("Bearer %s", accessToken),
+				}
 			}
 		} else if service.Image != "" {
 			// Container-based server

cmd/tool_shortcuts_test.go

@@ -145,7 +145,7 @@ func TestToolCompatibilityWithRemoteServers(t *testing.T) {
 	}
 
 	// Test unsupported tools
-	unsupportedTools := []string{"cursor", "claude-desktop"}
+	unsupportedTools := []string{"claude-desktop"}
 	for _, tool := range unsupportedTools {
 		err := ValidateToolSupport(tool, mixedServers)
 		if err == nil {