feat: RFC 8414 catalog schema, pre-registered OAuth, CE mode secret injection

Catalog schema:
- OAuthServerMetadata (RFC 8414 field naming) + OAuthRegistration (client_id only)
- client_secret never in catalogs, user provides via secrets store
- HasPreRegisteredOAuth() enables OAuth for non-remote servers

OAuth registration:
- Read client_secret from Secrets Engine at registration time, pass to Pinata
- Read scopes from server_metadata.scopes_supported
- Re-register DcrClient with client_secret at authorize time (CLI path)

CE mode:
- readCEModeOAuthSecrets() for container secret injection without se:// URIs
- docker mcp oauth register command for manual client registration

Container args:
- Skip secrets without env field (OAuth infrastructure secrets)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: saucow

cmd/docker-mcp/oauth/auth.go

@@ -5,10 +5,15 @@ import (
 	"fmt"
 	"time"
 
+	"github.com/docker/mcp-gateway/cmd/docker-mcp/secret-management/secret"
 	"github.com/docker/mcp-gateway/pkg/desktop"
+	"github.com/docker/mcp-gateway/pkg/log"
 	pkgoauth "github.com/docker/mcp-gateway/pkg/oauth"
 )
 
+// clientSecretSuffix is the naming convention for OAuth client secrets in the secrets store.
+const clientSecretSuffix = ".client_secret"
+
 func Authorize(ctx context.Context, app string, scopes string) error {
 	// Check if running in CE mode
 	if pkgoauth.IsCEMode() {
@@ -23,6 +28,25 @@ func Authorize(ctx context.Context, app string, scopes string) error {
 func authorizeDesktopMode(ctx context.Context, app string, scopes string) error {
 	client := desktop.NewAuthClient()
 
+	// For pre-registered OAuth clients, re-register the DCR client with the latest
+	// client_secret from the Secrets Engine. The user may have set the secret after
+	// the server was added to the profile.
+	if dcrClient, err := client.GetDCRClient(ctx, app); err == nil && dcrClient.ClientID != "" {
+		clientSecretKey := secret.GetDefaultSecretKey(app + clientSecretSuffix)
+		if env, err := secret.GetSecret(ctx, clientSecretKey); err == nil && string(env.Value) != "" {
+			req := desktop.RegisterDCRRequest{
+				ProviderName:          dcrClient.ProviderName,
+				ClientID:              dcrClient.ClientID,
+				ClientSecret:          string(env.Value),
+				AuthorizationEndpoint: dcrClient.AuthorizationEndpoint,
+				TokenEndpoint:         dcrClient.TokenEndpoint,
+			}
+			if err := client.RegisterDCRClientPending(ctx, app, req); err != nil {
+				log.Logf("Warning: failed to update DCR client with client_secret: %v", err)
+			}
+		}
+	}
+
 	// Start OAuth flow - Docker Desktop handles DCR automatically if needed
 	authResponse, err := client.PostOAuthApp(ctx, app, scopes, false)
 	if err != nil {

cmd/docker-mcp/server/enable.go

@@ -60,8 +60,8 @@ func update(ctx context.Context, docker docker.Client, dockerCli command.Cli, ad
 				Ref: "",
 			}
 
-			// DCR flag enabled AND type="remote" AND oauth present
-			if mcpOAuthDcrEnabled && server.HasExplicitOAuthProviders() {
+			// DCR flag enabled AND (remote OAuth server OR pre-registered OAuth from catalog)
+			if mcpOAuthDcrEnabled && (server.HasExplicitOAuthProviders() || server.HasPreRegisteredOAuth()) {
 				// In CE mode, skip lazy setup - DCR happens during oauth authorize
 				if pkgoauth.IsCEMode() {
 					fmt.Printf("OAuth server %s enabled. Run 'docker mcp oauth authorize %s' to authenticate\n", serverName, serverName)
@@ -74,7 +74,7 @@ func update(ctx context.Context, docker docker.Client, dockerCli command.Cli, ad
 						fmt.Printf("OAuth provider configured for %s - use 'docker mcp oauth authorize %s' to authenticate\n", serverName, serverName)
 					}
 				}
-			} else if !mcpOAuthDcrEnabled && server.HasExplicitOAuthProviders() {
+			} else if !mcpOAuthDcrEnabled && (server.HasExplicitOAuthProviders() || server.HasPreRegisteredOAuth()) {
 				// Provide guidance when DCR is needed but disabled
 				fmt.Printf("Server %s requires OAuth authentication but DCR is disabled.\n", serverName)
 				fmt.Printf("   To enable automatic OAuth setup, run: docker mcp feature enable mcp-oauth-dcr\n")

pkg/catalog/types.go

@@ -70,6 +70,18 @@ func (s *Server) HasExplicitOAuthProviders() bool {
 	return s.Type == "remote" && s.IsOAuthServer()
 }
 
+// HasPreRegisteredOAuth returns true if this server has pre-registered OAuth
+// client metadata embedded in the catalog, regardless of server type.
+// This supports local container servers that need OAuth tokens (e.g., Google Workspace)
+// where the admin pre-registers the OAuth client in the catalog.
+func (s *Server) HasPreRegisteredOAuth() bool {
+	if s.OAuth == nil || len(s.OAuth.Providers) == 0 {
+		return false
+	}
+	p := s.OAuth.Providers[0]
+	return p.Registration != nil && p.Registration.ClientID != ""
+}
+
 type Secret struct {
 	Name string `yaml:"name" json:"name"`
 	Env  string `yaml:"env" json:"env"`
@@ -95,6 +107,34 @@ type OAuthProvider struct {
 	Provider string `yaml:"provider" json:"provider"`
 	Secret   string `json:"secret,omitempty" yaml:"secret,omitempty"`
 	Env      string `json:"env,omitempty" yaml:"env,omitempty"`
+	// ServerMetadata holds OAuth authorization server metadata following RFC 8414 field naming.
+	// Omit if the server supports /.well-known/oauth-authorization-server discovery.
+	// Required for local servers or providers that don't publish metadata endpoints.
+	ServerMetadata *OAuthServerMetadata `json:"server_metadata,omitempty" yaml:"server_metadata,omitempty"`
+	// Registration holds out-of-band client credentials from manual OAuth app registration.
+	// Used when the provider does not support Dynamic Client Registration (DCR).
+	Registration *OAuthRegistration `json:"registration,omitempty" yaml:"registration,omitempty"`
+}
+
+// OAuthServerMetadata follows RFC 8414 (OAuth 2.0 Authorization Server Metadata) field naming.
+// https://datatracker.ietf.org/doc/html/rfc8414
+type OAuthServerMetadata struct {
+	Issuer                            string   `json:"issuer,omitempty" yaml:"issuer,omitempty"`
+	AuthorizationEndpoint             string   `json:"authorization_endpoint" yaml:"authorization_endpoint"`
+	TokenEndpoint                     string   `json:"token_endpoint" yaml:"token_endpoint"`
+	ScopesSupported                   []string `json:"scopes_supported,omitempty" yaml:"scopes_supported,omitempty"`
+	ResponseTypesSupported            []string `json:"response_types_supported,omitempty" yaml:"response_types_supported,omitempty"`
+	GrantTypesSupported               []string `json:"grant_types_supported,omitempty" yaml:"grant_types_supported,omitempty"`
+	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported,omitempty" yaml:"code_challenge_methods_supported,omitempty"`
+	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty" yaml:"token_endpoint_auth_methods_supported,omitempty"`
+}
+
+// OAuthRegistration holds the client_id from an out-of-band OAuth app registration.
+// The client_secret is NOT included here -- it is provided by the user via the
+// Docker secrets store (e.g., docker mcp secret set {server}.client_secret).
+// This ensures secrets are never distributed in catalogs.
+type OAuthRegistration struct {
+	ClientID string `json:"client_id" yaml:"client_id"`
 }
 
 // POCI tools

pkg/desktop/auth.go

@@ -86,13 +86,15 @@ func (c *Tools) PostOAuthApp(ctx context.Context, app, scopes string, disableAut
 // 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"`
-	ResourceURL           string `json:"resourceUrl,omitempty"`
+	ClientID              string   `json:"clientId"`
+	ClientSecret          string   `json:"clientSecret,omitempty"`
+	ProviderName          string   `json:"providerName"`
+	ClientName            string   `json:"clientName,omitempty"`
+	AuthorizationServer   string   `json:"authorizationServer,omitempty"`
+	AuthorizationEndpoint string   `json:"authorizationEndpoint,omitempty"`
+	TokenEndpoint         string   `json:"tokenEndpoint,omitempty"`
+	ResourceURL           string   `json:"resourceUrl,omitempty"`
+	Scopes                []string `json:"scopes,omitempty"`
 }
 
 type DCRClient struct {

pkg/gateway/clientpool.go

@@ -328,6 +328,11 @@ func (cp *clientPool) argsAndEnv(serverConfig *catalog.ServerConfig, targetConfi
 
 	// Secrets
 	for _, s := range serverConfig.Spec.Secrets {
+		// Skip secrets without an env field - they are OAuth infrastructure
+		// (e.g., client_secret) and are not injected into containers.
+		if s.Env == "" {
+			continue
+		}
 		args = append(args, "-e", s.Env)
 
 		secretValue, ok := serverConfig.Secrets[s.Name]

pkg/gateway/configuration.go

@@ -581,9 +581,9 @@ func (c *FileBasedConfiguration) readOnce(ctx context.Context) (Configuration, e
 		}
 	}
 
-	// CE mode: supplement with OAuth tokens from credential helper.
-	// Docker Desktop's secret mechanisms (jcat, se://) aren't available in CE mode,
-	// but OAuth tokens are stored in the credential helper by `docker mcp oauth authorize`.
+	// CE mode: resolve OAuth tokens for container secret injection.
+	// In CE mode there is no se:// URI resolution, so tokens must be read from
+	// the credential helper and injected as raw env var values.
 	if ceSecrets := readCEModeOAuthSecrets(ctx, servers, serverNames); len(ceSecrets) > 0 {
 		if secrets == nil {
 			secrets = make(map[string]string)

pkg/gateway/configuration_workingset.go

@@ -137,11 +137,13 @@ func (c *WorkingSetConfiguration) readOnce(ctx context.Context, dao db.DAO) (Con
 		// }
 	}
 
-	// CE mode: supplement with OAuth tokens from credential helper.
+	// CE mode: resolve OAuth tokens for container secret injection.
+	// In CE mode there is no se:// URI resolution, so tokens must be read from
+	// the credential helper and injected as raw env var values.
 	if ceSecrets := readCEModeOAuthSecrets(ctx, servers, serverNames); len(ceSecrets) > 0 {
 		for k, v := range ceSecrets {
-			if _, exists := flattenedSecrets[k]; !exists {
-				flattenedSecrets[k] = v
+			if _, exists := secrets[k]; !exists {
+				secrets[k] = v
 			}
 		}
 	}

pkg/gateway/run.go

@@ -362,7 +362,7 @@ func (g *Gateway) Run(ctx context.Context) error {
 				continue
 			}
 
-			if serverConfig.Spec.HasExplicitOAuthProviders() {
+			if serverConfig.Spec.HasExplicitOAuthProviders() || serverConfig.Spec.HasPreRegisteredOAuth() {
 				g.startProvider(ctx, serverName)
 			} else if serverConfig.IsRemote() {
 				// Community servers: start provider if they have a stored OAuth token

pkg/gateway/secrets_ce.go

@@ -8,11 +8,16 @@ import (
 	"github.com/docker/mcp-gateway/pkg/oauth"
 )
 
-// readCEModeOAuthSecrets reads OAuth tokens from the credential helper in CE mode.
-// In CE mode, Docker Desktop's secret mechanisms (jcat, Secrets Engine, se:// URIs)
-// are not available. Instead, OAuth tokens are stored in the system credential helper
-// (e.g., macOS Keychain) by `docker mcp oauth authorize`. This function reads those
-// tokens and maps them to the secret names expected by server definitions.
+// readCEModeOAuthSecrets resolves OAuth tokens for container secret injection in CE mode.
+//
+// In Desktop mode, secrets are injected into containers via se:// URIs that Docker
+// Desktop resolves at container start time. In CE mode, the standard Docker CLI has
+// no se:// URI resolution. Instead, OAuth tokens stored in the system credential
+// helper (e.g., macOS Keychain) by `docker mcp oauth authorize` must be read directly
+// and injected as raw environment variable values.
+//
+// This function reads those tokens and maps them to the secret names expected by
+// server definitions, so that clientpool.go can set them as container env vars.
 func readCEModeOAuthSecrets(ctx context.Context, servers map[string]catalog.Server, serverNames []string) map[string]string {
 	secrets := make(map[string]string)
 

pkg/oauth/dcr_registration.go

@@ -6,11 +6,15 @@ import (
 
 	oauthhelpers "github.com/docker/mcp-gateway-oauth-helpers"
 
+	"github.com/docker/mcp-gateway/cmd/docker-mcp/secret-management/secret"
 	"github.com/docker/mcp-gateway/pkg/catalog"
 	"github.com/docker/mcp-gateway/pkg/desktop"
 	"github.com/docker/mcp-gateway/pkg/log"
 )
 
+// clientSecretSuffix is the naming convention for OAuth client secrets in the secrets store.
+const clientSecretSuffix = ".client_secret"
+
 // dcrRegistrationClient is the subset of desktop.Tools used for DCR registration.
 // Extracted as an interface to enable testing.
 type dcrRegistrationClient interface {
@@ -53,16 +57,36 @@ func RegisterProviderForLazySetup(ctx context.Context, serverName string) error
 		return fmt.Errorf("server %s not found in catalog", serverName)
 	}
 
-	// Verify this is a remote OAuth server (Type="remote" && OAuth providers exist)
-	if !server.HasExplicitOAuthProviders() {
-		return fmt.Errorf("server %s is not a remote OAuth server", serverName)
+	// Verify this server has OAuth providers (remote with explicit providers, or pre-registered)
+	if !server.HasExplicitOAuthProviders() && !server.HasPreRegisteredOAuth() {
+		return fmt.Errorf("server %s does not have OAuth providers configured", serverName)
 	}
 
-	providerName := server.OAuth.Providers[0].Provider
+	provider := server.OAuth.Providers[0]
 
-	// Register with DD (pending DCR state)
+	// Build DCR request with pre-registered metadata if available.
+	// When registration + server_metadata are provided (from a catalog with
+	// embedded OAuth metadata), Pinata skips DCR discovery and uses them directly.
 	dcrRequest := desktop.RegisterDCRRequest{
-		ProviderName: providerName,
+		ProviderName: provider.Provider,
+	}
+	if provider.Registration != nil {
+		dcrRequest.ClientID = provider.Registration.ClientID
+
+		// Look up client_secret from the Secrets Engine (user sets it via docker mcp secret set).
+		// The catalog only contains client_id; the secret is never distributed in catalogs.
+		clientSecretKey := secret.GetDefaultSecretKey(serverName + clientSecretSuffix)
+		if env, err := secret.GetSecret(ctx, clientSecretKey); err == nil && string(env.Value) != "" {
+			dcrRequest.ClientSecret = string(env.Value)
+			log.Logf("- Registering pre-configured OAuth client for %s with client_secret", serverName)
+		} else {
+			log.Logf("- Registering pre-configured OAuth client for %s without client_secret (not yet set)", serverName)
+		}
+	}
+	if provider.ServerMetadata != nil {
+		dcrRequest.AuthorizationEndpoint = provider.ServerMetadata.AuthorizationEndpoint
+		dcrRequest.TokenEndpoint = provider.ServerMetadata.TokenEndpoint
+		dcrRequest.Scopes = provider.ServerMetadata.ScopesSupported
 	}
 
 	return client.RegisterDCRClientPending(ctx, serverName, dcrRequest)
@@ -103,7 +127,7 @@ func registerProviderForDynamicDiscovery(ctx context.Context, serverName, server
 // RegisterProviderWithSnapshot registers a DCR provider using OAuth metadata from the server snapshot
 // This avoids querying the catalog since the snapshot already contains all necessary OAuth information
 // Idempotent - safe to call multiple times for the same server
-func RegisterProviderWithSnapshot(ctx context.Context, serverName, providerName string) error {
+func RegisterProviderWithSnapshot(ctx context.Context, serverName string, provider catalog.OAuthProvider, scopes []string) error {
 	client := desktop.NewAuthClient()
 
 	// Idempotent check - already registered?
@@ -113,8 +137,26 @@ func RegisterProviderWithSnapshot(ctx context.Context, serverName, providerName
 	}
 
 	// Register with Docker Desktop (pending DCR state)
+	// Include pre-registered client metadata if available from catalog
 	dcrRequest := desktop.RegisterDCRRequest{
-		ProviderName: providerName,
+		ProviderName: provider.Provider,
+		Scopes:       scopes,
+	}
+	if provider.Registration != nil {
+		dcrRequest.ClientID = provider.Registration.ClientID
+
+		// Look up client_secret from Secrets Engine (not distributed in catalogs)
+		clientSecretKey := secret.GetDefaultSecretKey(serverName + clientSecretSuffix)
+		if env, err := secret.GetSecret(ctx, clientSecretKey); err == nil && string(env.Value) != "" {
+			dcrRequest.ClientSecret = string(env.Value)
+		}
+	}
+	if provider.ServerMetadata != nil {
+		dcrRequest.AuthorizationEndpoint = provider.ServerMetadata.AuthorizationEndpoint
+		dcrRequest.TokenEndpoint = provider.ServerMetadata.TokenEndpoint
+		if len(dcrRequest.Scopes) == 0 {
+			dcrRequest.Scopes = provider.ServerMetadata.ScopesSupported
+		}
 	}
 
 	return client.RegisterDCRClientPending(ctx, serverName, dcrRequest)