MCP-UI Delegated Authentication Proposal

[tylerrowsell]

This proposal outlines a delegated authentication system for MCP-UI that enables secure access to protected resources hosted on MCP servers. The system uses JWT tokens obtained through a three-party flow, allowing iframe-rendered resources to authenticate and access protected endpoints.

Key Innovation: Custom Auth Payloads

Resources define their own authentication requirements by including:

• authUrl: The endpoint where tokens should be requested
• authPayload: Arbitrary JSON payload containing whatever authentication data is needed

This flexibility allows each resource to specify exactly what it needs for authentication without MCP-UI needing to understand the specifics.

Architecture Flow

sequenceDiagram
    participant Client as Client (MCP-UI)
    participant Remote as Remote Server
    participant Host as Host MCP Server
    participant Protected as Protected Resources (Host)

    Note over Client,Host: Initial Resource Fetch
    Remote->>Host: MCP tool call requesting resources
    Host->>Remote: Returns UI resources (with auth requirements)
    Remote->>Client: Provides resources for rendering
    Client->>Client: Renders resources in iframe

    Note over Client,Host: Authentication Flow
    Client->>Client: iframe emits auth intent on load
    Client->>Client: Check token cache

    alt Token not cached or expired
        Client->>Remote: Request token (authUrl + authPayload)
        Note over Remote,Host: Pre-established server-to-server auth
        Remote->>Host: Request delegated token
        Host->>Host: Validate remote server auth
        Host->>Host: Generate JWT based on authPayload
        Host->>Remote: Return JWT token
        Remote->>Client: Return token to client
        Client->>Client: Cache token
        Client->>Client: Send token to iframe
    else Token cached
        Client->>Client: Return cached token to iframe
    end

    Note over Client,Host: Protected Resource Access
    Client->>Protected: Request with JWT token
    Protected->>Protected: Validate JWT
    Protected->>Client: Return protected content

Loading

Detailed Flow

1. Resource Creation & Delivery

• Host MCP server creates UI resources that may require authentication
• Remote server requests these resources via MCP tool calls
• Resources are passed through to the client and rendered in iframes

2. Authentication Intent

When an iframe loads, it automatically emits an authentication intent:

window.parent.postMessage({
  type: 'intent',
  intentType: 'authenticate',
  payload: {
    authUrl: 'https://host-mcp.example.com/api/v1/delegated-token',
    authPayload: {
      // Custom payload - can be anything the host MCP server expects
      userId: '123',
      permissions: ['read', 'write'],
      sessionId: 'abc',
      customField: 'value'
    }
  },
  messageId: crypto.randomUUID()
}, '*');

3. Token Request Chain

1. Client → Remote: Client requests token with the authUrl and authPayload from the iframe
2. Remote → Host: Remote server forwards request to host MCP server (using server-to-server auth)
3. Host validates: Host MCP server validates the remote server's credentials
4. Token generation: Host generates JWT based on the authPayload
5. Return chain: JWT flows back: Host → Remote → Client → iframe

4. Token Caching

• Tokens are cached by authUrl + authPayload combination
• Identical requests from multiple iframes reuse the same token
• Cache expires 60 seconds before token expiration

5. Protected Resource Access

Once the iframe has the JWT token, it can directly access protected resources on the host MCP server:

fetch('https://host-mcp.example.com/protected-endpoint', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
});

Benefits

Flexibility

• Resources define their own auth requirements via authUrl and authPayload
• No hardcoded authentication logic in MCP-UI
• Supports different auth servers and authentication schemes

Efficiency

• Token caching prevents redundant authentication requests
• Multiple iframes with identical auth requirements share tokens
• Direct access to protected resources after authentication

Security

• Server-to-server authentication between remote and host
• Short-lived JWT tokens (1 hour recommended)
• iframe sandboxing maintained
• Tokens never logged in plaintext

Implementation Requirements

Client (MCP-UI)

• Handle authentication intents from iframes
• Cache tokens based on authUrl + authPayload
• Pass tokens back to requesting iframes

Remote Server

• Relay authentication requests to host MCP server
• Maintain server-to-server authentication credentials
• Pass through authPayload unchanged

Host MCP Server

• Include authUrl and authPayload in resource definitions
• Validate remote server authentication
• Generate JWT tokens based on authPayload
• Host protected endpoints that validate JWT tokens

Example Resource with Auth

// Host MCP server creates resource that points to an iframe URL
const resource = createUIResource({
  uri: 'ui://dashboard',
  content: {
    type: 'externalUrl',
    url: 'https://host-mcp.example.com/dashboard'
  },
  mimeType: 'text/uri-list'
});

// The dashboard page at the URL handles authentication:
// When https://host-mcp.example.com/dashboard loads in the iframe, it:

// 1. Emits authentication intent on load
window.parent.postMessage({
  type: 'intent',
  intentType: 'authenticate',
  payload: {
    authUrl: 'https://host-mcp.example.com/api/v1/delegated-token',
    authPayload: {
      userId: '123',
      scopes: ['dashboard:read'],
      sessionId: 'abc'
    }
  },
  messageId: crypto.randomUUID()
}, '*');

// 2. Receives token from parent
window.addEventListener('message', async (event) => {
  if (event.data?.type === 'ui-message-response' &&
      event.data?.payload?.success) {
    const token = event.data.payload.token;

    // 3. Uses token to fetch protected data
    const response = await fetch('/api/dashboard/data', {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    // 4. Renders protected content
    const data = await response.json();
    renderDashboard(data);
  }
});

Conclusion

This delegated authentication system provides a flexible, secure way for MCP-UI resources to access protected data. By allowing resources to define their own authUrl and authPayload, the system supports diverse authentication requirements without requiring changes to MCP-UI itself. The token caching mechanism ensures efficiency, while the direct access pattern to protected resources maintains performance.