feat(mcp): support custom OAuth callbackRedirectURL for remote toolsets

Add an optional `callbackRedirectURL` field to the remote MCP OAuth config.
When set, it is advertised to the authorization server as the OAuth
`redirect_uri` instead of the default `http://127.0.0.1:{callbackPort}/callback`.
The literal placeholder `${callbackPort}` is substituted with the actual
port the local callback server is listening on.

This lets users put a public-facing proxy (HTTPS or pre-registered static
redirect) in front of the local loopback callback, working around auth
servers that refuse http://localhost redirect URIs. The local callback
server still listens on 127.0.0.1:{callbackPort}; only the advertised
redirect URI changes.

Validation:
- URL must be absolute (scheme + host) once ${callbackPort} is substituted.
- Scheme must be http or https; other schemes (javascript:, file:, ftp:, …) are rejected.
- http is only allowed on loopback hosts (127.0.0.1, ::1, localhost); non-loopback http would expose the authorization code on the wire (RFC 8252 §7.3).

Includes JSON schema + docs update, a runnable example, and unit tests for
validation and the pure buildRedirectURI substitution helper.

Assisted-By: docker-agent

Author: dgageot

agent-schema.json

@@ -1803,6 +1803,10 @@
           "items": {
             "type": "string"
           }
+        },
+        "callbackRedirectURL": {
+          "type": "string",
+          "description": "Optional OAuth redirect URI used in place of http://127.0.0.1:{callbackPort}/callback. The literal placeholder ${callbackPort} is replaced with the actual local callback port at runtime. The external URL is expected to redirect the browser back to the local callback server."
         }
       },
       "required": [

docs/features/remote-mcp/index.md

@@ -68,9 +68,40 @@ toolsets:
 | `clientSecret` | string          | ✗        | OAuth client secret. Omit for public clients using PKCE.                                         |
 | `callbackPort` | integer         | ✗        | Local port to receive the OAuth redirect. If omitted, docker-agent picks a random free port.    |
 | `scopes`       | array[string]   | ✗        | Scopes to request during the authorization step. Values are server-specific.                     |
+| `callbackRedirectURL` | string   | ✗        | Custom OAuth redirect URI. Useful when the auth server requires HTTPS or a pre-registered URL. The literal placeholder `${callbackPort}` is replaced with the actual local callback port. See below.            |
 
 Secrets should be stored in a credential helper or environment variable rather than committed — see [Secrets]({{ '/guides/secrets/' | relative_url }}) for interpolation patterns.
 
+### Custom redirect URI (`callbackRedirectURL`)
+
+Some authorization servers require the OAuth `redirect_uri` to be HTTPS or to match a URL that was pre-registered during app creation — neither of which plays nicely with a locally-bound loopback address such as `http://127.0.0.1:8765/callback`.
+
+To work around this, set `callbackRedirectURL` to a public URL that redirects back to the local callback server. The literal placeholder `${callbackPort}` is substituted with the actual port the local callback server is listening on (either `callbackPort` when set, or the randomly-assigned port otherwise).
+
+```yaml
+toolsets:
+  - type: mcp
+    remote:
+      url: "https://mcp.example.com/mcp"
+      transport_type: "streamable"
+      oauth:
+        clientId: "my-app-client-id"
+        callbackPort: 8765
+        # Advertise this URL to the authorization server. The external
+        # service at redirect.example.com is expected to 302-redirect the
+        # browser to http://127.0.0.1:8765/callback preserving the query
+        # string (code, state, …).
+        callbackRedirectURL: "https://redirect.example.com/cb?port=${callbackPort}"
+```
+
+The local callback server still listens on the loopback interface on `callbackPort`; only the `redirect_uri` advertised to the authorization server changes.
+
+**Validation rules:**
+
+- The URL must be absolute (scheme + host) once `${callbackPort}` has been substituted.
+- Only `http` and `https` schemes are accepted.
+- `http` is only allowed when the host is a loopback address (`127.0.0.1`, `::1`, `localhost`); any other host must use `https` to avoid exposing the authorization `code` on the wire (RFC 8252 §7.3).
+
 ## Project Management & Collaboration
 
 | Service    | URL                                | Transport | Description                           |

examples/remote_mcp_oauth_callback_redirect.yaml

@@ -0,0 +1,36 @@
+#!/usr/bin/env docker agent run
+
+# Example: Remote MCP server with a custom OAuth callback redirect URL.
+#
+# Some authorization servers refuse http://localhost or http://127.0.0.1
+# redirect URIs (they require HTTPS or a pre-registered URL). Use
+# `callbackRedirectURL` to advertise a public URL to the authorization
+# server while still receiving the final callback on the local loopback
+# interface.
+#
+# The literal placeholder ${callbackPort} is replaced at runtime with the
+# actual port the local callback server is listening on (either
+# `callbackPort` when set, or a random free port otherwise).
+#
+# The external service at redirect.example.com is expected to 302-redirect
+# the browser back to http://127.0.0.1:${callbackPort}/callback, preserving
+# the OAuth query parameters (code, state, ...).
+
+agents:
+  root:
+    model: openai/gpt-4.1-mini
+    description: Assistant with a remote MCP tool using a custom OAuth redirect URL
+    instruction: You are a helpful assistant with access to remote tools.
+    toolsets:
+      - type: mcp
+        remote:
+          url: "https://mcp.example.com/mcp"
+          transport_type: streamable
+          oauth:
+            clientId: "your-client-id"
+            clientSecret: "your-client-secret"
+            callbackPort: 8765
+            callbackRedirectURL: "https://redirect.example.com/cb?port=${callbackPort}"
+            scopes:
+              - "read"
+              - "write"

pkg/config/latest/types.go

@@ -831,6 +831,20 @@ type RemoteOAuthConfig struct {
 	ClientSecret string   `json:"clientSecret,omitempty"`
 	CallbackPort int      `json:"callbackPort,omitempty"`
 	Scopes       []string `json:"scopes,omitempty"`
+	// CallbackRedirectURL, when set, is used as the OAuth redirect URI
+	// instead of the default http://127.0.0.1:{callbackPort}/callback.
+	// This allows inserting a public-facing proxy (e.g. a URL shortener or
+	// a pre-registered static redirect) in front of the local callback
+	// server — useful for authorization servers that require the redirect
+	// URI to be HTTPS or pre-registered.
+	//
+	// The literal placeholder ${callbackPort} is replaced with the actual
+	// port the local callback server is listening on (either CallbackPort
+	// when set, or a random free port otherwise). The external URL is
+	// expected to redirect the browser back to
+	// http://127.0.0.1:{callbackPort}/callback preserving the OAuth query
+	// parameters.
+	CallbackRedirectURL string `json:"callbackRedirectURL,omitempty"`
 }
 
 // DeferConfig represents the deferred loading configuration for a toolset.

pkg/config/latest/validate.go

@@ -2,6 +2,10 @@ package latest
 
 import (
 	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"strings"
 )
 
 func (t *Config) UnmarshalYAML(unmarshal func(any) error) error {
@@ -156,6 +160,11 @@ func (t *Toolset) validate() error {
 			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")
 			}
+			if t.Remote.OAuth.CallbackRedirectURL != "" {
+				if err := validateCallbackRedirectURL(t.Remote.OAuth.CallbackRedirectURL); err != nil {
+					return err
+				}
+			}
 		}
 	case "a2a":
 		if t.URL == "" {
@@ -184,3 +193,51 @@ func (t *Toolset) validate() error {
 
 	return nil
 }
+
+// isLoopbackHost reports whether host is a loopback address (with or without
+// a port component). It accepts IPv4 loopback, IPv6 loopback, and the literal
+// "localhost".
+func isLoopbackHost(hostPort string) bool {
+	host := hostPort
+	if h, _, err := net.SplitHostPort(hostPort); err == nil {
+		host = h
+	}
+	host = strings.Trim(host, "[]") // strip IPv6 brackets
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		return ip.IsLoopback()
+	}
+	return false
+}
+
+// validateCallbackRedirectURL ensures raw is a well-formed absolute URL
+// suitable for use as an OAuth redirect_uri.
+//
+// Rules:
+//   - Must parse as an absolute URL (scheme + host) once the ${callbackPort}
+//     placeholder has been substituted with a dummy value.
+//   - Scheme must be http or https. Other schemes (javascript:, file:, ftp:,
+//     …) are rejected: the browser will be navigated to this URL by the
+//     authorization server.
+//   - http is only permitted for loopback hosts (RFC 8252 §7.3); any other
+//     host must use https, since non-loopback http redirect URIs allow the
+//     authorization code to be exposed on the wire.
+func validateCallbackRedirectURL(raw string) error {
+	// Substitute the placeholder with a dummy port so url.Parse accepts the
+	// string (Go's parser validates that ports are numeric).
+	probe := strings.ReplaceAll(raw, "${callbackPort}", "1")
+	u, err := url.Parse(probe)
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return fmt.Errorf("oauth callbackRedirectURL must be an absolute URL: %q", raw)
+	}
+	scheme := strings.ToLower(u.Scheme)
+	if scheme != "http" && scheme != "https" {
+		return fmt.Errorf("oauth callbackRedirectURL scheme must be http or https, got %q", u.Scheme)
+	}
+	if scheme == "http" && !isLoopbackHost(u.Host) {
+		return fmt.Errorf("oauth callbackRedirectURL must use https for non-loopback hosts: %q", raw)
+	}
+	return nil
+}

pkg/config/latest/validate_test.go

@@ -216,3 +216,166 @@ agents:
 		})
 	}
 }
+
+func TestToolset_Validate_MCP_RemoteOAuth_CallbackRedirectURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		config  string
+		wantErr string
+	}{
+		{
+			name: "callbackRedirectURL absolute URL is accepted",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: https://redirect.example.com/cb
+`,
+			wantErr: "",
+		},
+		{
+			name: "callbackRedirectURL with placeholder is accepted",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "https://redirect.example.com/cb?port=${callbackPort}"
+`,
+			wantErr: "",
+		},
+		{
+			name: "http on loopback is accepted",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "http://localhost:${callbackPort}/cb"
+`,
+			wantErr: "",
+		},
+		{
+			name: "http on non-loopback host is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "http://redirect.example.com/cb"
+`,
+			wantErr: "must use https for non-loopback hosts",
+		},
+		{
+			name: "javascript scheme is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "javascript:alert(1)"
+`,
+			wantErr: "must be an absolute URL",
+		},
+		{
+			name: "ftp scheme is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "ftp://example.com/cb"
+`,
+			wantErr: "scheme must be http or https",
+		},
+		{
+			name: "relative callbackRedirectURL is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: /just/a/path
+`,
+			wantErr: "oauth callbackRedirectURL must be an absolute URL",
+		},
+		{
+			name: "garbage callbackRedirectURL is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+          oauth:
+            clientId: cid
+            callbackRedirectURL: "://bad-url"
+`,
+			wantErr: "oauth callbackRedirectURL must be an absolute URL",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var cfg Config
+			err := yaml.Unmarshal([]byte(tt.config), &cfg)
+
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}

pkg/tools/mcp/oauth.go

@@ -165,6 +165,15 @@ func resourceMetadataFromWWWAuth(wwwAuth string) string {
 	return ""
 }
 
+// callbackRedirectURLFrom is a nil-safe accessor for the optional
+// CallbackRedirectURL field on a RemoteOAuthConfig.
+func callbackRedirectURLFrom(c *latest.RemoteOAuthConfig) string {
+	if c == nil {
+		return ""
+	}
+	return c.CallbackRedirectURL
+}
+
 // oauthTransport wraps an HTTP transport with OAuth support
 type oauthTransport struct {
 	base http.RoundTripper
@@ -355,7 +364,7 @@ func (t *oauthTransport) handleManagedOAuthFlow(ctx context.Context, authServer,
 		return fmt.Errorf("failed to start callback server: %w", err)
 	}
 
-	redirectURI := callbackServer.GetRedirectURI()
+	redirectURI := callbackServer.resolveRedirectURI(callbackRedirectURLFrom(t.oauthConfig))
 	slog.Debug("Using redirect URI", "uri", redirectURI)
 
 	var clientID string