Support explicit OAuth credentials for remote MCP servers

Add support for configuring explicit OAuth client credentials (clientId,
clientSecret, callbackPort, scopes) on remote MCP server toolsets. This
fixes connections to MCP servers that do not support Dynamic Client
Registration (RFC 7591), such as Slack and GitHub.

Key changes:
- Add RemoteOAuthConfig to config types with clientId, clientSecret,
  callbackPort, and scopes fields
- Stop fabricating registration_endpoint when the server doesn't
  advertise one in metadata discovery
- Use explicit credentials in the managed OAuth flow when configured,
  falling back to dynamic registration when available
- Support fixed callback port for OAuth redirect URI
- Add scopes parameter to BuildAuthorizationURL
- Validate callbackPort range (1-65535) and oauth on non-mcp types
- Update agent-schema.json with RemoteOAuthConfig definition
- Add example config (examples/remote_mcp_oauth.yaml)

Fixes #2248

Co-Authored-By: nicholasgasior <nicholasgasior@users.noreply.github.com>

Co-Authored-By: rumpl <rumpl@users.noreply.github.com>

Assisted-By: docker-agent

Author: dgageot

agent-schema.json

@@ -1253,6 +1253,10 @@
           "additionalProperties": {
             "type": "string"
           }
+        },
+        "oauth": {
+          "$ref": "#/definitions/RemoteOAuthConfig",
+          "description": "Explicit OAuth credentials for servers that do not support Dynamic Client Registration"
         }
       },
       "required": [
@@ -1686,6 +1690,36 @@
         "strategies"
       ],
       "additionalProperties": false
+    },
+    "RemoteOAuthConfig": {
+      "type": "object",
+      "description": "OAuth configuration for remote MCP servers that do not support Dynamic Client Registration (RFC 7591)",
+      "properties": {
+        "clientId": {
+          "type": "string",
+          "description": "OAuth client ID"
+        },
+        "clientSecret": {
+          "type": "string",
+          "description": "OAuth client secret"
+        },
+        "callbackPort": {
+          "type": "integer",
+          "description": "Fixed port for the OAuth callback server (default: random available port)",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "scopes": {
+          "type": "array",
+          "description": "OAuth scopes to request",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "clientId"
+      ]
     }
   }
 }

examples/remote_mcp_oauth.yaml

@@ -0,0 +1,23 @@
+#!/usr/bin/env docker agent run
+
+# Example: Remote MCP server with explicit OAuth credentials.
+# Use this when connecting to MCP servers that do NOT support
+# Dynamic Client Registration (RFC 7591), such as Slack or GitHub.
+
+agents:
+  root:
+    model: openai/gpt-4.1-mini
+    description: Assistant with remote MCP tools using explicit OAuth credentials
+    instruction: You are a helpful assistant with access to remote tools.
+    toolsets:
+      - type: mcp
+        remote:
+          url: "https://mcp.example.com/sse"
+          transport_type: sse
+          oauth:
+            clientId: "your-client-id"
+            clientSecret: "your-client-secret"
+            callbackPort: 8080
+            scopes:
+              - "read"
+              - "write"

pkg/config/latest/types.go

@@ -741,9 +741,19 @@ 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 holds explicit OAuth credentials for remote MCP servers
+// that do not support Dynamic Client Registration (RFC 7591).
+type RemoteOAuthConfig struct {
+	ClientID     string   `json:"clientId"`
+	ClientSecret string   `json:"clientSecret,omitempty"`
+	CallbackPort int      `json:"callbackPort,omitempty"`
+	Scopes       []string `json:"scopes,omitempty"`
 }
 
 // DeferConfig represents the deferred loading configuration for a toolset.

pkg/config/latest/validate.go

@@ -93,7 +93,7 @@ func (t *Toolset) validate() error {
 	if t.Ref != "" && t.Type != "mcp" && t.Type != "rag" {
 		return errors.New("ref can only be used with type 'mcp' or 'rag'")
 	}
-	if (t.Remote.URL != "" || t.Remote.TransportType != "") && t.Type != "mcp" {
+	if (t.Remote.URL != "" || t.Remote.TransportType != "" || t.Remote.OAuth != nil) && t.Type != "mcp" {
 		return errors.New("remote can only be used with type 'mcp'")
 	}
 	if (len(t.Remote.Headers) > 0) && (t.Type != "mcp" && t.Type != "a2a") {
@@ -139,6 +139,17 @@ func (t *Toolset) validate() error {
 		if count > 1 {
 			return errors.New("either command, remote or ref must be set, but only one of those")
 		}
+		if t.Remote.OAuth != nil {
+			if t.Remote.URL == "" {
+				return errors.New("oauth requires remote url to be set")
+			}
+			if t.Remote.OAuth.ClientID == "" {
+				return errors.New("oauth requires clientId to be set")
+			}
+			if t.Remote.OAuth.CallbackPort != 0 && (t.Remote.OAuth.CallbackPort < 1 || t.Remote.OAuth.CallbackPort > 65535) {
+				return errors.New("oauth callbackPort must be between 1 and 65535")
+			}
+		}
 	case "a2a":
 		if t.URL == "" {
 			return errors.New("a2a toolset requires a url to be set")

pkg/runtime/remote_runtime.go

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

pkg/teamloader/registry.go

@@ -251,7 +251,7 @@ 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" {
-			return mcp.NewRemoteToolset(toolset.Name, serverSpec.Remote.URL, serverSpec.Remote.TransportType, nil), nil
+			return mcp.NewRemoteToolset(toolset.Name, serverSpec.Remote.URL, serverSpec.Remote.TransportType, nil, nil), nil
 		}
 
 		env, err := environment.ExpandAll(ctx, environment.ToValues(toolset.Env), envProvider)
@@ -292,7 +292,7 @@ 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)
 
-		return mcp.NewRemoteToolset(toolset.Name, url, toolset.Remote.TransportType, headers), nil
+		return mcp.NewRemoteToolset(toolset.Name, url, toolset.Remote.TransportType, headers, toolset.Remote.OAuth), nil
 
 	default:
 		return nil, errors.New("mcp toolset requires either ref, command, or remote configuration")

pkg/tools/mcp/describe_test.go

@@ -24,21 +24,21 @@ func TestToolsetDescribe_StdioNoArgs(t *testing.T) {
 func TestToolsetDescribe_RemoteHostAndPort(t *testing.T) {
 	t.Parallel()
 
-	ts := NewRemoteToolset("", "http://example.com:8443/mcp/v1?key=secret", "sse", nil)
+	ts := NewRemoteToolset("", "http://example.com:8443/mcp/v1?key=secret", "sse", nil, nil)
 	assert.Check(t, is.Equal(ts.Describe(), "mcp(remote host=example.com:8443 transport=sse)"))
 }
 
 func TestToolsetDescribe_RemoteDefaultPort(t *testing.T) {
 	t.Parallel()
 
-	ts := NewRemoteToolset("", "https://api.example.com/mcp", "streamable", nil)
+	ts := NewRemoteToolset("", "https://api.example.com/mcp", "streamable", nil, nil)
 	assert.Check(t, is.Equal(ts.Describe(), "mcp(remote host=api.example.com transport=streamable)"))
 }
 
 func TestToolsetDescribe_RemoteInvalidURL(t *testing.T) {
 	t.Parallel()
 
-	ts := NewRemoteToolset("", "://bad-url", "sse", nil)
+	ts := NewRemoteToolset("", "://bad-url", "sse", nil, nil)
 	assert.Check(t, is.Equal(ts.Describe(), "mcp(remote transport=sse)"))
 }
 

pkg/tools/mcp/mcp.go

@@ -18,6 +18,7 @@ import (
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 
+	"github.com/docker/docker-agent/pkg/config/latest"
 	"github.com/docker/docker-agent/pkg/tools"
 )
 
@@ -105,13 +106,13 @@ func NewToolsetCommand(name, command string, args, env []string, cwd string) *To
 }
 
 // NewRemoteToolset creates a new MCP toolset from a remote MCP Server.
-func NewRemoteToolset(name, urlString, transport string, headers map[string]string) *Toolset {
+func NewRemoteToolset(name, urlString, transport string, headers map[string]string, oauthConfig *latest.RemoteOAuthConfig) *Toolset {
 	slog.Debug("Creating Remote MCP toolset", "url", urlString, "transport", transport, "headers", headers)
 
 	desc := buildRemoteDescription(urlString, transport)
 	return &Toolset{
 		name:        name,
-		mcpClient:   newRemoteClient(urlString, transport, headers, NewKeyringTokenStore()),
+		mcpClient:   newRemoteClient(urlString, transport, headers, NewKeyringTokenStore(), oauthConfig),
 		logID:       urlString,
 		description: desc,
 	}

pkg/tools/mcp/oauth.go

@@ -17,6 +17,7 @@ import (
 	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
 	"golang.org/x/oauth2"
 
+	"github.com/docker/docker-agent/pkg/config/latest"
 	"github.com/docker/docker-agent/pkg/tools"
 )
 
@@ -135,7 +136,8 @@ func validateAndFillDefaults(metadata *AuthorizationServerMetadata, authServerUR
 
 	metadata.AuthorizationEndpoint = cmp.Or(metadata.AuthorizationEndpoint, authServerURL+"/authorize")
 	metadata.TokenEndpoint = cmp.Or(metadata.TokenEndpoint, authServerURL+"/token")
-	metadata.RegistrationEndpoint = cmp.Or(metadata.RegistrationEndpoint, authServerURL+"/register")
+	// Do NOT fabricate a registration_endpoint — if the server doesn't
+	// advertise one, dynamic client registration is not supported.
 
 	return metadata
 }
@@ -146,7 +148,6 @@ func createDefaultMetadata(authServerURL string) *AuthorizationServerMetadata {
 		Issuer:                                 authServerURL,
 		AuthorizationEndpoint:                  authServerURL + "/authorize",
 		TokenEndpoint:                          authServerURL + "/token",
-		RegistrationEndpoint:                   authServerURL + "/register",
 		ResponseTypesSupported:                 []string{"code"},
 		ResponseModesSupported:                 []string{"query", "fragment"},
 		GrantTypesSupported:                    []string{"authorization_code"},
@@ -168,10 +169,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 *latest.RemoteOAuthConfig
 
 	// mu protects refreshFailedAt from concurrent access.
 	mu sync.Mutex
@@ -331,7 +333,11 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 	}
 
 	slog.Debug("Creating OAuth callback server")
-	callbackServer, err := NewCallbackServer()
+	var callbackPort int
+	if t.oauthConfig != nil {
+		callbackPort = t.oauthConfig.CallbackPort
+	}
+	callbackServer, err := NewCallbackServerOnPort(callbackPort)
 	if err != nil {
 		return fmt.Errorf("failed to create callback server: %w", err)
 	}
@@ -352,18 +358,26 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 
 	var clientID string
 	var clientSecret string
-
-	if authServerMetadata.RegistrationEndpoint != "" {
+	var scopes []string
+
+	switch {
+	case t.oauthConfig != nil && t.oauthConfig.ClientID != "":
+		// Use explicit credentials from config
+		slog.Debug("Using explicit OAuth credentials from config")
+		clientID = t.oauthConfig.ClientID
+		clientSecret = t.oauthConfig.ClientSecret
+		scopes = t.oauthConfig.Scopes
+	case authServerMetadata.RegistrationEndpoint != "":
 		slog.Debug("Attempting dynamic client registration")
 		clientID, clientSecret, err = RegisterClient(ctx, authServerMetadata, redirectURI, nil)
 		if err != nil {
 			slog.Debug("Dynamic registration failed", "error", err)
 			// TODO(rumpl): fall back to requesting client ID from user
 			return err
 		}
-	} else {
+	default:
 		// TODO(rumpl): fall back to requesting client ID from user
-		return errors.New("authorization server does not support dynamic client registration")
+		return errors.New("authorization server does not support dynamic client registration and no explicit OAuth credentials configured")
 	}
 
 	state, err := GenerateState()
@@ -381,6 +395,7 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 		state,
 		oauth2.S256ChallengeFromVerifier(verifier),
 		t.baseURL,
+		scopes,
 	)
 
 	result, err := t.client.requestElicitation(ctx, &mcpsdk.ElicitParams{

pkg/tools/mcp/oauth_helpers.go

@@ -28,7 +28,7 @@ func GenerateState() (string, error) {
 }
 
 // BuildAuthorizationURL builds the OAuth authorization URL with PKCE
-func BuildAuthorizationURL(authEndpoint, clientID, redirectURI, state, codeChallenge, resourceURL string) string {
+func BuildAuthorizationURL(authEndpoint, clientID, redirectURI, state, codeChallenge, resourceURL string, scopes []string) string {
 	params := url.Values{}
 	params.Set("response_type", "code")
 	params.Set("client_id", clientID)
@@ -37,6 +37,9 @@ func BuildAuthorizationURL(authEndpoint, clientID, redirectURI, state, codeChall
 	params.Set("code_challenge", codeChallenge)
 	params.Set("code_challenge_method", "S256")
 	params.Set("resource", resourceURL) // RFC 8707: Resource Indicators
+	if len(scopes) > 0 {
+		params.Set("scope", strings.Join(scopes, " "))
+	}
 	return authEndpoint + "?" + params.Encode()
 }