Add Dynamic Client Registration (DCR) OAuth support for MCP servers

This commit implements PR #129 changes with adaptations for the latest main branch:

* Add mcp-oauth-dcr feature flag support to commands and gateway configuration
* Implement OAuth 2.0 Dynamic Client Registration (RFC 7591) for public clients
* Add OAuth 2.0 Authorization Server Discovery (RFC 8414) and Protected Resource Metadata (RFC 9728)
* Support token event handling for OAuth client invalidation on token refresh
* Add secure OAuth credential helper using docker-credential-desktop
* Update MCP remote client to automatically add OAuth Bearer tokens
* Add DCR client management methods to desktop auth client
* Update server enable/disable commands to support DCR feature flag
* Add comprehensive WWW-Authenticate header parsing (RFC 6750)
* Add InvalidateOAuthClients method to gateway client pool
* Include OAuth configuration in catalog server types

Key features:
- Automatic OAuth server discovery from MCP server 401 responses
- Public client registration using PKCE for enhanced security
- Secure token storage via system credential store
- Automatic token refresh handling with client pool invalidation
- Full compliance with OAuth 2.0/2.1 and MCP Authorization specifications

All tests pass and build succeeds.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kgprs

cmd/docker-mcp/commands/feature.go

@@ -38,14 +38,15 @@ func featureEnableCommand(dockerCli command.Cli) *cobra.Command {
 
 Available features:
   oauth-interceptor      Enable GitHub OAuth flow interception for automatic authentication
+  mcp-oauth-dcr          Enable Dynamic Client Registration (DCR) for automatic OAuth client setup
   dynamic-tools          Enable internal MCP management tools (mcp-find, mcp-add, mcp-remove)`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
 			featureName := args[0]
 
 			// Validate feature name
 			if !isKnownFeature(featureName) {
-				return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  oauth-interceptor      Enable GitHub OAuth flow interception\n  dynamic-tools          Enable internal MCP management tools", featureName)
+				return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  oauth-interceptor      Enable GitHub OAuth flow interception\n  mcp-oauth-dcr          Enable Dynamic Client Registration for automatic OAuth setup\n  dynamic-tools          Enable internal MCP management tools", featureName)
 			}
 
 			// Enable the feature
@@ -68,6 +69,13 @@ Available features:
 				fmt.Println("\nThis feature enables automatic GitHub OAuth interception when 401 errors occur.")
 				fmt.Println("When enabled, the gateway will automatically provide OAuth URLs for authentication.")
 				fmt.Println("\nNo additional flags are needed - this applies to all gateway runs.")
+			case "mcp-oauth-dcr":
+				fmt.Println("\nThis feature enables Dynamic Client Registration (DCR) for MCP servers.")
+				fmt.Println("When enabled, remote servers with OAuth configuration will automatically:")
+				fmt.Println("  - Discover OAuth authorization servers")
+				fmt.Println("  - Register public OAuth clients using PKCE")
+				fmt.Println("  - Provide seamless OAuth authentication flows")
+				fmt.Println("\nOnly affects remote servers with OAuth configuration - traditional OAuth flows are unchanged.")
 			case "dynamic-tools":
 				fmt.Println("\nThis feature enables dynamic tool discovery and execution capabilities.")
 				fmt.Println("When enabled, the gateway provides internal tools for managing MCP servers:")
@@ -129,7 +137,7 @@ func featureListCommand(dockerCli command.Cli) *cobra.Command {
 			fmt.Println()
 
 			// Show all known features
-			knownFeatures := []string{"oauth-interceptor", "dynamic-tools"}
+			knownFeatures := []string{"oauth-interceptor", "mcp-oauth-dcr", "dynamic-tools"}
 			for _, feature := range knownFeatures {
 				status := "disabled"
 				if isFeatureEnabledFromCli(dockerCli, feature) {
@@ -142,6 +150,8 @@ func featureListCommand(dockerCli command.Cli) *cobra.Command {
 				switch feature {
 				case "oauth-interceptor":
 					fmt.Printf("  %-20s %s\n", "", "Enable GitHub OAuth flow interception for automatic authentication")
+				case "mcp-oauth-dcr":
+					fmt.Printf("  %-20s %s\n", "", "Enable Dynamic Client Registration (DCR) for automatic OAuth client setup")
 				case "dynamic-tools":
 					fmt.Printf("  %-20s %s\n", "", "Enable internal MCP management tools (mcp-find, mcp-add, mcp-remove)")
 				}
@@ -205,6 +215,7 @@ func isFeatureEnabledFromConfig(configFile *configfile.ConfigFile, feature strin
 func isKnownFeature(feature string) bool {
 	knownFeatures := []string{
 		"oauth-interceptor",
+		"mcp-oauth-dcr",
 		"dynamic-tools",
 	}
 

cmd/docker-mcp/commands/gateway.go

@@ -71,6 +71,9 @@ func gatewayCommand(docker docker.Client, dockerCli command.Cli) *cobra.Command
 			// Check if OAuth interceptor feature is enabled
 			options.OAuthInterceptorEnabled = isOAuthInterceptorFeatureEnabled(dockerCli)
 
+			// Check if MCP OAuth DCR feature is enabled
+			options.McpOAuthDcrEnabled = isMcpOAuthDcrFeatureEnabled(dockerCli)
+
 			// Check if dynamic tools feature is enabled
 			options.DynamicTools = isDynamicToolsFeatureEnabled(dockerCli)
 
@@ -270,6 +273,21 @@ func isOAuthInterceptorFeatureEnabled(dockerCli command.Cli) bool {
 	return value == "enabled"
 }
 
+// isMcpOAuthDcrFeatureEnabled checks if the mcp-oauth-dcr feature is enabled
+func isMcpOAuthDcrFeatureEnabled(dockerCli command.Cli) bool {
+	configFile := dockerCli.ConfigFile()
+	if configFile == nil || configFile.Features == nil {
+		return false
+	}
+
+	value, exists := configFile.Features["mcp-oauth-dcr"]
+	if !exists {
+		return false
+	}
+
+	return value == "enabled"
+}
+
 // isDynamicToolsFeatureEnabled checks if the dynamic-tools feature is enabled
 func isDynamicToolsFeatureEnabled(dockerCli command.Cli) bool {
 	configFile := dockerCli.ConfigFile()

cmd/docker-mcp/commands/root.go

@@ -79,7 +79,7 @@ func Root(ctx context.Context, cwd string, dockerCli command.Cli) *cobra.Command
 	cmd.AddCommand(policyCommand())
 	cmd.AddCommand(registryCommand())
 	cmd.AddCommand(secretCommand(dockerClient))
-	cmd.AddCommand(serverCommand(dockerClient))
+	cmd.AddCommand(serverCommand(dockerClient, dockerCli))
 	cmd.AddCommand(toolsCommand(dockerClient))
 	cmd.AddCommand(versionCommand())
 

cmd/docker-mcp/commands/server.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/mcp-gateway/cmd/docker-mcp/server"
@@ -13,7 +14,7 @@ import (
 	"github.com/docker/mcp-gateway/pkg/oci"
 )
 
-func serverCommand(docker docker.Client) *cobra.Command {
+func serverCommand(docker docker.Client, dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "server",
 		Short: "Manage servers",
@@ -55,7 +56,8 @@ func serverCommand(docker docker.Client) *cobra.Command {
 		Short:   "Enable a server or multiple servers",
 		Args:    cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return server.Enable(cmd.Context(), docker, args)
+			mcpOAuthDcrEnabled := isMcpOAuthDcrFeatureEnabled(dockerCli)
+			return server.Enable(cmd.Context(), docker, args, mcpOAuthDcrEnabled)
 		},
 	})
 
@@ -65,7 +67,8 @@ func serverCommand(docker docker.Client) *cobra.Command {
 		Short:   "Disable a server or multiple servers",
 		Args:    cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return server.Disable(cmd.Context(), docker, args)
+			mcpOAuthDcrEnabled := isMcpOAuthDcrFeatureEnabled(dockerCli)
+			return server.Disable(cmd.Context(), docker, args, mcpOAuthDcrEnabled)
 		},
 	})
 

cmd/docker-mcp/server/enable.go

@@ -12,15 +12,15 @@ import (
 	"github.com/docker/mcp-gateway/pkg/docker"
 )
 
-func Disable(ctx context.Context, docker docker.Client, serverNames []string) error {
-	return update(ctx, docker, nil, serverNames)
+func Disable(ctx context.Context, docker docker.Client, serverNames []string, mcpOAuthDcrEnabled bool) error {
+	return update(ctx, docker, nil, serverNames, mcpOAuthDcrEnabled)
 }
 
-func Enable(ctx context.Context, docker docker.Client, serverNames []string) error {
-	return update(ctx, docker, serverNames, nil)
+func Enable(ctx context.Context, docker docker.Client, serverNames []string, mcpOAuthDcrEnabled bool) error {
+	return update(ctx, docker, serverNames, nil, mcpOAuthDcrEnabled)
 }
 
-func update(ctx context.Context, docker docker.Client, add []string, remove []string) error {
+func update(ctx context.Context, docker docker.Client, add []string, remove []string, mcpOAuthDcrEnabled bool) error {
 	// Read registry.yaml that contains which servers are enabled.
 	registryYAML, err := config.ReadRegistry(ctx, docker)
 	if err != nil {

cmd/docker-mcp/server/server_test.go

@@ -68,14 +68,14 @@ func TestList(t *testing.T) {
 func TestEnableNotFound(t *testing.T) {
 	ctx, _, docker := setup(t, withEmptyRegistryYaml(), withEmptyCatalog())
 
-	err := Enable(ctx, docker, []string{"duckduckgo"})
+	err := Enable(ctx, docker, []string{"duckduckgo"}, false)
 	require.ErrorContains(t, err, "server duckduckgo not found in catalog")
 }
 
 func TestEnable(t *testing.T) {
 	ctx, _, docker := setup(t, withEmptyRegistryYaml(), withCatalog("registry:\n  duckduckgo:\n"))
 
-	err := Enable(ctx, docker, []string{"duckduckgo"})
+	err := Enable(ctx, docker, []string{"duckduckgo"}, false)
 	require.NoError(t, err)
 
 	enabled, err := List(ctx, docker)
@@ -86,7 +86,7 @@ func TestEnable(t *testing.T) {
 func TestDisable(t *testing.T) {
 	ctx, _, docker := setup(t, withRegistryYaml("registry:\n  duckduckgo:\n    ref: \"\"\n  git:\n    ref: \"\""), withCatalog("registry:\n  git:\n  duckduckgo:\n"))
 
-	err := Disable(ctx, docker, []string{"duckduckgo"})
+	err := Disable(ctx, docker, []string{"duckduckgo"}, false)
 	require.NoError(t, err)
 
 	enabled, err := List(ctx, docker)
@@ -97,7 +97,7 @@ func TestDisable(t *testing.T) {
 func TestDisableUnknown(t *testing.T) {
 	ctx, _, docker := setup(t, withRegistryYaml("registry:\n  duckduckgo:\n    ref: \"\""), withCatalog("registry:\n  duckduckgo:\n"))
 
-	err := Disable(ctx, docker, []string{"unknown"})
+	err := Disable(ctx, docker, []string{"unknown"}, false)
 	require.NoError(t, err)
 
 	enabled, err := List(ctx, docker)
@@ -108,7 +108,7 @@ func TestDisableUnknown(t *testing.T) {
 func TestRemoveOutdatedServerOnEnable(t *testing.T) {
 	ctx, _, docker := setup(t, withRegistryYaml("registry:\n  outdated:\n    ref: \"\""), withCatalog("registry:\n  git:\n"))
 
-	err := Enable(ctx, docker, []string{"git"})
+	err := Enable(ctx, docker, []string{"git"}, false)
 	require.NoError(t, err)
 
 	enabled, err := List(ctx, docker)
@@ -119,7 +119,7 @@ func TestRemoveOutdatedServerOnEnable(t *testing.T) {
 func TestRemoveOutdatedServerOnDisable(t *testing.T) {
 	ctx, _, docker := setup(t, withRegistryYaml("registry:\n  outdated:\n    ref: \"\""), withEmptyCatalog())
 
-	err := Disable(ctx, docker, []string{"git"})
+	err := Disable(ctx, docker, []string{"git"}, false)
 	require.NoError(t, err)
 
 	enabled, err := List(ctx, docker)

pkg/catalog/types.go

@@ -14,11 +14,13 @@ type topLevel struct {
 
 type Server struct {
 	Name           string   `yaml:"name,omitempty" json:"name,omitempty"`
+	Type           string   `yaml:"type" json:"type"`
 	Image          string   `yaml:"image" json:"image"`
 	Description    string   `yaml:"description,omitempty" json:"description,omitempty"`
 	LongLived      bool     `yaml:"longLived,omitempty" json:"longLived,omitempty"`
 	Remote         Remote   `yaml:"remote,omitempty" json:"remote,omitempty"`
 	SSEEndpoint    string   `yaml:"sseEndpoint,omitempty" json:"sseEndpoint,omitempty"` // Deprecated: Use Remote instead
+	OAuth          *OAuth   `yaml:"oauth,omitempty" json:"oauth,omitempty"`
 	Secrets        []Secret `yaml:"secrets,omitempty" json:"secrets,omitempty"`
 	Env            []Env    `yaml:"env,omitempty" json:"env,omitempty"`
 	Command        []string `yaml:"command,omitempty" json:"command,omitempty"`
@@ -46,6 +48,15 @@ type Remote struct {
 	Headers   map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
 }
 
+type OAuth struct {
+	Providers []OAuthProvider `yaml:"providers,omitempty" json:"providers,omitempty"`
+	Scopes    []string        `yaml:"scopes,omitempty" json:"scopes,omitempty"`
+}
+
+type OAuthProvider struct {
+	Provider string `yaml:"provider" json:"provider"`
+}
+
 // POCI tools
 
 type Items struct {
@@ -126,3 +137,7 @@ type ServerConfig struct {
 	Config  map[string]any
 	Secrets map[string]string
 }
+
+func (s *Server) IsRemoteOAuthServer() bool {
+	return s.Type == "remote" && s.OAuth != nil && len(s.OAuth.Providers) > 0
+}

pkg/desktop/auth.go

@@ -72,6 +72,61 @@ func (c *Tools) PostOAuthApp(ctx context.Context, app, scopes string, disableAut
 	return result, err
 }
 
+// DCR (Dynamic Client Registration) Methods
+
+type RegisterDCRRequest struct {
+	ClientID              string `json:"clientId"`
+	ProviderName          string `json:"providerName"`
+	ClientName            string `json:"clientName,omitempty"`
+	AuthorizationServer   string `json:"authorizationServer,omitempty"`
+	AuthorizationEndpoint string `json:"authorizationEndpoint,omitempty"`
+	TokenEndpoint         string `json:"tokenEndpoint,omitempty"`
+}
+
+type DCRClient struct {
+	State                 string `json:"state"`
+	ServerName            string `json:"serverName"`
+	ProviderName          string `json:"providerName"`
+	ClientID              string `json:"clientId"`
+	ClientName            string `json:"clientName,omitempty"`
+	RegisteredAt          string `json:"registeredAt"` // ISO timestamp
+	AuthorizationServer   string `json:"authorizationServer,omitempty"`
+	AuthorizationEndpoint string `json:"authorizationEndpoint,omitempty"`
+	TokenEndpoint         string `json:"tokenEndpoint,omitempty"`
+}
+
+func (c *Tools) RegisterDCRClient(ctx context.Context, app string, req RegisterDCRRequest) error {
+	AvoidResourceSaverMode(ctx)
+
+	var result map[string]string
+	return c.rawClient.Post(ctx, fmt.Sprintf("/apps/%s/dcr", app), req, &result)
+}
+
+// RegisterDCRClientPending registers a provider for lazy DCR setup using state=unregistered
+func (c *Tools) RegisterDCRClientPending(ctx context.Context, app string, req RegisterDCRRequest) error {
+	AvoidResourceSaverMode(ctx)
+
+	var result map[string]string
+	return c.rawClient.Post(ctx, fmt.Sprintf("/apps/%s/dcr?state=unregistered", app), req, &result)
+}
+
+func (c *Tools) GetDCRClient(ctx context.Context, app string) (*DCRClient, error) {
+	AvoidResourceSaverMode(ctx)
+
+	var result DCRClient
+	err := c.rawClient.Get(ctx, fmt.Sprintf("/apps/%s/dcr", app), &result)
+	if err != nil {
+		return nil, err
+	}
+	return &result, nil
+}
+
+func (c *Tools) DeleteDCRClient(ctx context.Context, app string) error {
+	AvoidResourceSaverMode(ctx)
+
+	return c.rawClient.Delete(ctx, fmt.Sprintf("/apps/%s/dcr", app))
+}
+
 func addQueryParam[T any](q, name string, value T, required bool) string {
 	if !required && reflect.DeepEqual(value, reflect.Zero(reflect.TypeOf(value)).Interface()) {
 		return ""

pkg/desktop/raw_client.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net"
 	"net/http"
@@ -56,6 +57,18 @@ func (c *RawClient) Get(ctx context.Context, endpoint string, v any) error {
 		return err
 	}
 
+	// Check HTTP status code - return error for non-2xx responses
+	if response.StatusCode < 200 || response.StatusCode >= 300 {
+		// Try to parse error message from response
+		var errorMsg struct {
+			Message string `json:"message"`
+		}
+		if json.Unmarshal(buf, &errorMsg) == nil && errorMsg.Message != "" {
+			return fmt.Errorf("HTTP %d: %s", response.StatusCode, errorMsg.Message)
+		}
+		return fmt.Errorf("HTTP %d: %s", response.StatusCode, string(buf))
+	}
+
 	if err := json.Unmarshal(buf, &v); err != nil {
 		return err
 	}
@@ -100,6 +113,18 @@ func (c *RawClient) Post(ctx context.Context, endpoint string, v any, result any
 		return err
 	}
 
+	// Check HTTP status code - return error for non-2xx responses
+	if response.StatusCode < 200 || response.StatusCode >= 300 {
+		// Try to parse error message from response
+		var errorMsg struct {
+			Message string `json:"message"`
+		}
+		if json.Unmarshal(buf, &errorMsg) == nil && errorMsg.Message != "" {
+			return fmt.Errorf("HTTP %d: %s", response.StatusCode, errorMsg.Message)
+		}
+		return fmt.Errorf("HTTP %d: %s", response.StatusCode, string(buf))
+	}
+
 	if err := json.Unmarshal(buf, &result); err != nil {
 		return err
 	}