MCP Gateway DCR OAuth

[saucow]

Latest version of PR: https://github.com/docker/mcp-gateway/pull/148/files

What I did:

This PR implements the MCP Authorization specification in MCP Gateway behind the: mcp-oauth-dcr feature flag, enabling automatic OAuth setup for MCP servers through Dynamic Client Registration (DCR). The implementation uses lazy DCR registration where OAuth client registration happens during authorization, not server enable.

Component Boundaries:

• MCP Gateway: Orchestrates OAuth discovery, DCR registration, and token injection into MCP requests
• Docker Desktop: Provides credential storage, PKCE generation, browser opening, and token refresh management

Key features:

• OAuth Discovery: RFC 9728 (Protected Resource) + RFC 8414 (Authorization Server) metadata discovery
• Lazy DCR: RFC 7591 public client registration on first authorize
• Token Injection: Automatic Bearer token injection into remote MCP server requests
• Token Event Watching: File-based notification system for token refresh events
• Credential Helper Integration: Direct access to docker-credential-desktop for secure token storage

Key Flows

1. Enable → Authorize Flow

sequenceDiagram
    participant User
    participant Gateway as MCP Gateway
    participant DD as Docker Desktop
    participant AuthServer as Authorization Server

    Note over User: 1. Enable Server (Unregistered State)
    User->>Gateway: docker mcp server enable notion-remote
    Gateway->>DD: Register unregistered DCR client
    DD->>DD: Store placeholder DCR client
    DD->>DD: Add provider to OAuth tab
    Note over User: Provider appears (unregistered)

    Note over User: 2. Authorize (Atomic DCR + OAuth)
    User->>DD: Click "Authorize" or use CLI
    DD->>Gateway: docker mcp oauth authorize notion-remote
    Gateway->>AuthServer: OAuth discovery (RFC 9728 + RFC 8414)
    Gateway->>AuthServer: POST /register (DCR)
    AuthServer-->>Gateway: {client_id, endpoints}
    Gateway->>DD: Store DCR client via API
    DD->>DD: Generate PKCE parameters
    DD->>User: Open browser with auth URL
    User->>AuthServer: Complete authorization
    AuthServer->>DD: OAuth callback
    DD->>DD: Exchange code + verifier for tokens
    Note over User: Provider shows as "Authorized"

Loading

2. Token Injection Flow

sequenceDiagram
    participant Gateway as MCP Gateway
    participant CredHelper as Credential Helper
    participant DD as Docker Desktop
    participant Server as MCP Server

    Note over Gateway: MCP Request with Token
    Gateway->>CredHelper: GetOAuthToken(notion-remote)
    CredHelper->>DD: docker-credential-desktop get
    DD-->>CredHelper: OAuth token (base64 JSON)
    CredHelper->>CredHelper: Parse access_token from JSON
    CredHelper-->>Gateway: Access token
    Gateway->>Server: MCP request + Authorization: Bearer <token>
    Server-->>Gateway: MCP response (authorized)

Loading

3. Token Event File Watching

sequenceDiagram
    participant DD as Docker Desktop
    participant EventFile as ~/.docker/token-event.json
    participant Gateway as MCP Gateway
    participant ClientPool as Client Pool
    participant Server as MCP Server

    Note over DD: Token refresh occurs
    DD->>EventFile: Write token event
    Note over EventFile: {"provider": "notion-remote", "event_type": "token_refreshed", ...}
    
    EventFile->>Gateway: File watcher detects change
    Gateway->>Gateway: Parse event JSON
    Gateway->>ClientPool: Find connection for provider
    ClientPool->>ClientPool: Close existing connection
    Gateway->>CredHelper: Get fresh token
    Gateway->>Server: Reconnect with new token
    Server-->>Gateway: Connection established

Loading

4. OAuth Discovery Flow

sequenceDiagram
    participant Gateway as MCP Gateway
    participant Server as MCP Server
    participant AuthServer as Authorization Server

    Note over Gateway: Discovery Process
    Gateway->>Server: Initial MCP request (no auth)
    Server-->>Gateway: 401 + WWW-Authenticate header
    Note over Gateway: Parse resource metadata URL
    
    Gateway->>Server: GET /.well-known/oauth-protected-resource
    Server-->>Gateway: Resource metadata + auth server URLs
    
    Gateway->>AuthServer: GET /.well-known/oauth-authorization-server
    AuthServer-->>Gateway: Authorization server metadata
    Note over Gateway: Discovery complete - ready for DCR

Loading

Implementation Details

OAuth Package (cmd/docker-mcp/internal/oauth/)

Discovery (discovery.go)

• WWW-Authenticate header parsing per RFC 9728
• Protected resource metadata discovery
• Authorization server metadata retrieval
• Multi-domain OAuth support (Stripe: resource ≠ auth server)

DCR Implementation (dcr.go)

• Public client registration (OAuth 2.1 compliant)
• Client name with server identification
• Dynamic callback URL configuration

Credential Helper (credhelper.go)

• Direct integration with docker-credential-desktop
• Secure token retrieval using DCR client metadata
• Base64 JSON token parsing

Types (types.go)

• RFC-compliant data structures
• Discovery metadata types
• DCR request/response types

Gateway Integration (internal/gateway/)

Token Event Watching (run.go)

• File watcher on ~/.docker/token-event.json
• JSON event parsing and processing
• Automatic connection restart with fresh tokens

Client Pool Enhancement (clientpool.go)

• OAuth-aware connection management
• Token injection for remote servers
• Connection restart on token refresh

Authorization Commands (oauth/)

Authorize (auth.go)

• Atomic DCR + OAuth flow implementation
• Lazy DCR detection and execution
• PKCE parameter delegation to Docker Desktop

List (ls.go)

• OAuth provider status display

Revoke (revoke.go)

• Token revocation and cleanup

Server Lifecycle (server/enable.go)

On Enable:

• Unregistered DCR client placeholder creation
• Provider registration in Docker Desktop UI

On Disable:

• Complete OAuth cleanup (tokens + DCR client)
• Clean slate UX

Feature Flag Protection

All DCR operations are controlled by the mcp-oauth-dcr feature flag:

# Enable DCR functionality
docker mcp feature enable mcp-oauth-dcr

# Disable DCR (fallback to manual setup)
docker mcp feature disable mcp-oauth-dcr

When disabled, users get guidance for manual OAuth setup.

Testing

Manual Verification:

# 1. Enable server (unregistered state)
docker mcp server enable notion-remote
# → Provider appears in Docker Desktop OAuth tab

# 2. Authorize (atomic DCR + OAuth)  
docker mcp oauth authorize notion-remote
# → Discovery + DCR + OAuth in single flow
# → Browser opens, OAuth completes

# 3. Test MCP connectivity
docker mcp tools call --server notion-remote list_pages
# → Should work with OAuth token

# 4. Test token refresh (wait for refresh or trigger manually)
# → Should automatically reconnect with fresh token

# 5. Disable server (clean slate)
docker mcp server disable notion-remote
# → Provider disappears from OAuth tab

[saucow]

Closing as the code has been rebased and merged with this PR: #148