feat: explicit OAuth configuration for remote MCP servers (#2248)

Implement support for pre-registered OAuth clients with remote MCP servers.
This allows using servers that do not support Dynamic Client Registration (RFC 7591),
such as Slack and GitHub MCP.

Key features:
- New RemoteOAuthConfig struct for clientId, clientSecret, callbackPort, and scopes
- Explicit OAuth priority over dynamic registration
- Configurable callback port for OAuth flow
- Custom scope support for authorization requests
- Updated agent-schema.json for validation (using camelCase as requested)
- Comprehensive tests and example configuration

Fixes root cause of #416
Addresses #2248

Author: yunus25jmi1

agent-schema.json

@@ -1205,13 +1205,49 @@
           "additionalProperties": {
             "type": "string"
           }
+        },
+        "oauth": {
+          "$ref": "#/definitions/RemoteOAuthConfig",
+          "description": "Explicit OAuth configuration for remote MCP servers that do not support Dynamic Client Registration"
         }
       },
       "required": [
         "url"
       ],
       "additionalProperties": false
     },
+    "RemoteOAuthConfig": {
+      "type": "object",
+      "description": "Explicit OAuth configuration for remote MCP servers. Allows using pre-registered OAuth clients with servers that do not support Dynamic Client Registration (RFC 7591), such as the Slack MCP server.",
+      "properties": {
+        "clientId": {
+          "type": "string",
+          "description": "OAuth client ID (required for explicit OAuth)",
+          "examples": ["3660753192626.8903469228982"]
+        },
+        "clientSecret": {
+          "type": "string",
+          "description": "OAuth client secret (optional, for confidential clients)"
+        },
+        "callbackPort": {
+          "type": "integer",
+          "description": "Fixed port for the OAuth callback server (optional). When not specified, a random available port is used.",
+          "examples": [3118]
+        },
+        "scopes": {
+          "type": "array",
+          "description": "List of OAuth scopes to request (optional). When not specified, default scopes from the server are used.",
+          "items": {
+            "type": "string"
+          },
+          "examples": [
+            ["search:read.public", "chat:write"]
+          ]
+        }
+      },
+      "required": ["clientId"],
+      "additionalProperties": false
+    },
     "ScriptShellToolConfig": {
       "type": "object",
       "description": "Configuration for custom shell tool",

examples/slack-oauth-example.yaml

@@ -0,0 +1,96 @@
+# Example Docker Agent configuration with explicit OAuth for remote MCP servers
+# This demonstrates how to configure OAuth for servers that do not support
+# Dynamic Client Registration (RFC 7591), such as the Slack MCP server.
+#
+# Related issue: #2248
+
+metadata:
+  author: "Your Name"
+  description: "Agent with explicit OAuth configuration for Slack MCP"
+  version: "1.0.0"
+
+models:
+  default:
+    provider: openai
+    model: gpt-4o
+
+agents:
+  slack-agent:
+    model: default
+    description: "An agent with Slack MCP integration using explicit OAuth"
+    instruction: |
+      You are a helpful assistant with access to Slack.
+      You can read messages, search channels, and send messages.
+    toolsets:
+      # Slack MCP server with explicit OAuth configuration
+      # This is required because Slack does not support Dynamic Client Registration
+      - type: mcp
+        remote:
+          url: https://mcp.slack.com/mcp
+          transport_type: streamable
+          oauth:
+            # Client ID from your Slack app registration
+            # Get this from https://api.slack.com/apps
+            clientId: "3660753192626.8903469228982"
+            
+            # Client secret (optional, for confidential clients)
+            # Leave empty for public clients
+            clientSecret: ""
+            
+            # Fixed callback port (optional)
+            # Some OAuth servers require a specific redirect URI port
+            # Default: random available port
+            callbackPort: 3118
+            
+            # Scopes to request (optional)
+            # If not specified, server defaults are used
+            scopes:
+              - search:read.public
+              - chat:write
+              - channels:read
+              - users:read
+
+# Alternative: GitHub MCP Server with explicit OAuth
+# Uncomment and configure for GitHub integration
+#
+# agents:
+#   github-agent:
+#     model: default
+#     description: "An agent with GitHub MCP integration"
+#     instruction: |
+#       You are a helpful assistant with access to GitHub.
+#     toolsets:
+#       - type: mcp
+#         remote:
+#           url: https://api.githubcopilot.com/mcp
+#           transport_type: streamable
+#           oauth:
+#             clientId: "your-github-client-id"
+#             clientSecret: "your-github-client-secret"
+#             scopes:
+#               - read:user
+#               - repo
+
+# How to use:
+# 1. Register your OAuth application with the MCP server provider
+#    - For Slack: https://api.slack.com/apps
+#    - For GitHub: https://github.com/settings/applications/new
+#
+# 2. Get your Client ID and Client Secret from the provider
+#
+# 3. Configure the OAuth settings in your agent YAML as shown above
+#
+# 4. Run the agent:
+#    docker-agent run ./slack-oauth-example.yaml
+#
+# 5. When the agent needs to access the MCP server, it will:
+#    - Use your configured Client ID for the OAuth flow
+#    - Open your browser for authorization
+#    - Exchange the authorization code for tokens
+#    - Store tokens for subsequent requests
+#
+# Notes:
+# - OAuth tokens are stored in memory for the session
+# - The callback server runs on localhost at the configured port (or random)
+# - User authorization is required for the initial OAuth flow
+# - Subsequent requests use the stored access token automatically

pkg/config/latest/types.go

@@ -624,9 +624,26 @@ func (t *Toolset) UnmarshalYAML(unmarshal func(any) error) error {
 }
 
 type Remote struct {
-	URL           string            `json:"url"`
-	TransportType string            `json:"transport_type,omitempty"`
-	Headers       map[string]string `json:"headers,omitempty"`
+	URL           string             `json:"url"`
+	TransportType string             `json:"transport_type,omitempty"`
+	Headers       map[string]string  `json:"headers,omitempty"`
+	OAuth         *RemoteOAuthConfig `json:"oauth,omitempty"`
+}
+
+// RemoteOAuthConfig represents explicit OAuth configuration for remote MCP servers.
+// This allows using pre-registered OAuth clients with servers that do not support
+// Dynamic Client Registration (RFC 7591), such as the Slack MCP server.
+type RemoteOAuthConfig struct {
+	// ClientID is the OAuth client ID (required for explicit OAuth)
+	ClientID string `json:"clientId,omitempty" yaml:"clientId,omitempty"`
+	// ClientSecret is the OAuth client secret (optional, for confidential clients)
+	ClientSecret string `json:"clientSecret,omitempty" yaml:"clientSecret,omitempty"`
+	// CallbackPort is the fixed port for the OAuth callback server (optional)
+	// When not specified, a random available port is used
+	CallbackPort int `json:"callbackPort,omitempty" yaml:"callbackPort,omitempty"`
+	// Scopes is the list of OAuth scopes to request (optional)
+	// When not specified, default scopes from the server are used
+	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
 }
 
 // DeferConfig represents the deferred loading configuration for a toolset.

pkg/runtime/remote_runtime.go

@@ -362,6 +362,7 @@ func (r *RemoteRuntime) handleOAuthElicitation(ctx context.Context, req *Elicita
 		state,
 		oauth2.S256ChallengeFromVerifier(verifier),
 		serverURL,
+		nil, // scopes - use server defaults
 	)
 
 	slog.Debug("Authorization URL built", "url", authURL)

pkg/teamloader/registry.go

@@ -250,6 +250,16 @@ func createMCPTool(ctx context.Context, toolset latest.Toolset, _ string, runCon
 
 		// TODO(dga): until the MCP Gateway supports oauth with docker agent, we fetch the remote url and directly connect to it.
 		if serverSpec.Type == "remote" {
+			// Check if explicit OAuth config is provided in the toolset
+			if toolset.Remote.OAuth != nil {
+				oauthConfig := &mcp.RemoteOAuthConfig{
+					ClientID:     toolset.Remote.OAuth.ClientID,
+					ClientSecret: toolset.Remote.OAuth.ClientSecret,
+					CallbackPort: toolset.Remote.OAuth.CallbackPort,
+					Scopes:       toolset.Remote.OAuth.Scopes,
+				}
+				return mcp.NewRemoteToolsetWithOAuth(toolset.Name, serverSpec.Remote.URL, serverSpec.Remote.TransportType, nil, oauthConfig), nil
+			}
 			return mcp.NewRemoteToolset(toolset.Name, serverSpec.Remote.URL, serverSpec.Remote.TransportType, nil), nil
 		}
 
@@ -291,6 +301,17 @@ func createMCPTool(ctx context.Context, toolset latest.Toolset, _ string, runCon
 		headers := expander.ExpandMap(ctx, toolset.Remote.Headers)
 		url := expander.Expand(ctx, toolset.Remote.URL, nil)
 
+		// Use explicit OAuth config if provided
+		if toolset.Remote.OAuth != nil {
+			oauthConfig := &mcp.RemoteOAuthConfig{
+				ClientID:     toolset.Remote.OAuth.ClientID,
+				ClientSecret: toolset.Remote.OAuth.ClientSecret,
+				CallbackPort: toolset.Remote.OAuth.CallbackPort,
+				Scopes:       toolset.Remote.OAuth.Scopes,
+			}
+			return mcp.NewRemoteToolsetWithOAuth(toolset.Name, url, toolset.Remote.TransportType, headers, oauthConfig), nil
+		}
+
 		return mcp.NewRemoteToolset(toolset.Name, url, toolset.Remote.TransportType, headers), nil
 
 	default:

pkg/tools/mcp/mcp.go

@@ -20,6 +20,22 @@ import (
 	"github.com/docker/docker-agent/pkg/tools"
 )
 
+// RemoteOAuthConfig represents explicit OAuth configuration for remote MCP servers.
+// This allows using pre-registered OAuth clients with servers that do not support
+// Dynamic Client Registration (RFC 7591), such as the Slack MCP server.
+type RemoteOAuthConfig struct {
+	// ClientID is the OAuth client ID (required for explicit OAuth)
+	ClientID string
+	// ClientSecret is the OAuth client secret (optional, for confidential clients)
+	ClientSecret string
+	// CallbackPort is the fixed port for the OAuth callback server (optional)
+	// When not specified, a random available port is used
+	CallbackPort int
+	// Scopes is the list of OAuth scopes to request (optional)
+	// When not specified, default scopes from the server are used
+	Scopes []string
+}
+
 type mcpClient interface {
 	Initialize(ctx context.Context, request *mcp.InitializeRequest) (*mcp.InitializeResult, error)
 	ListTools(ctx context.Context, request *mcp.ListToolsParams) iter.Seq2[*mcp.Tool, error]
@@ -107,6 +123,20 @@ func NewRemoteToolset(name, urlString, transport string, headers map[string]stri
 	}
 }
 
+// NewRemoteToolsetWithOAuth creates a new MCP toolset from a remote MCP Server with explicit OAuth configuration.
+func NewRemoteToolsetWithOAuth(name, urlString, transport string, headers map[string]string, oauthConfig *RemoteOAuthConfig) *Toolset {
+	slog.Debug("Creating Remote MCP toolset with OAuth", "url", urlString, "transport", transport, "headers", headers)
+
+	desc := buildRemoteDescription(urlString, transport)
+	client := newRemoteClient(urlString, transport, headers, NewInMemoryTokenStore()).WithOAuthConfig(oauthConfig)
+	return &Toolset{
+		name:        name,
+		mcpClient:   client,
+		logID:       urlString,
+		description: desc,
+	}
+}
+
 // errServerUnavailable is returned by doStart when the MCP server could not be
 // reached but the error is non-fatal (e.g. EOF). The toolset is considered
 // "started" so the agent can proceed, but watchConnection must not be spawned

pkg/tools/mcp/oauth.go

@@ -161,10 +161,11 @@ func resourceMetadataFromWWWAuth(wwwAuth string) string {
 type oauthTransport struct {
 	base http.RoundTripper
 	// TODO(rumpl): remove client reference, we need to find a better way to send elicitation requests
-	client     *remoteMCPClient
-	tokenStore OAuthTokenStore
-	baseURL    string
-	managed    bool
+	client      *remoteMCPClient
+	tokenStore  OAuthTokenStore
+	baseURL     string
+	managed     bool
+	oauthConfig *RemoteOAuthConfig
 }
 
 func (t *oauthTransport) RoundTrip(req *http.Request) (*http.Response, error) {
@@ -265,6 +266,11 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 		}
 	}()
 
+	// Use explicit callback port if configured
+	if t.oauthConfig != nil && t.oauthConfig.CallbackPort > 0 {
+		callbackServer.SetPort(t.oauthConfig.CallbackPort)
+	}
+
 	if err := callbackServer.Start(); err != nil {
 		return fmt.Errorf("failed to start callback server: %w", err)
 	}
@@ -275,17 +281,22 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 	var clientID string
 	var clientSecret string
 
-	if authServerMetadata.RegistrationEndpoint != "" {
+	// Use explicit OAuth credentials if provided, otherwise attempt dynamic registration
+	if t.oauthConfig != nil && t.oauthConfig.ClientID != "" {
+		slog.Debug("Using explicit OAuth client ID from configuration")
+		clientID = t.oauthConfig.ClientID
+		clientSecret = t.oauthConfig.ClientSecret
+	} else if authServerMetadata.RegistrationEndpoint != "" {
 		slog.Debug("Attempting dynamic client registration")
-		clientID, clientSecret, err = RegisterClient(ctx, authServerMetadata, redirectURI, nil)
+		clientID, clientSecret, err = RegisterClient(ctx, authServerMetadata, redirectURI, t.oauthConfig.Scopes)
 		if err != nil {
 			slog.Debug("Dynamic registration failed", "error", err)
-			// TODO(rumpl): fall back to requesting client ID from user
-			return err
+			// If explicit client ID was not provided and registration failed, return error
+			return fmt.Errorf("dynamic client registration failed and no explicit client ID provided: %w", err)
 		}
 	} else {
-		// TODO(rumpl): fall back to requesting client ID from user
-		return errors.New("authorization server does not support dynamic client registration")
+		// No dynamic registration support and no explicit credentials
+		return errors.New("authorization server does not support dynamic client registration and no explicit OAuth credentials provided")
 	}
 
 	state, err := GenerateState()
@@ -296,13 +307,20 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 	callbackServer.SetExpectedState(state)
 	verifier := GeneratePKCEVerifier()
 
+	// Use explicit scopes if provided, otherwise use server defaults
+	scopes := authServerMetadata.ScopesSupported
+	if t.oauthConfig != nil && len(t.oauthConfig.Scopes) > 0 {
+		scopes = t.oauthConfig.Scopes
+	}
+
 	authURL := BuildAuthorizationURL(
 		authServerMetadata.AuthorizationEndpoint,
 		clientID,
 		redirectURI,
 		state,
 		oauth2.S256ChallengeFromVerifier(verifier),
 		t.baseURL,
+		scopes,
 	)
 
 	result, err := t.client.requestElicitation(ctx, &mcpsdk.ElicitParams{