MCP OAuth Architecture

Reference Sequence

sequenceDiagram
  participant MCP as Local MCP
  participant API as Aegis API
  participant User as End User
  participant Browser as Browser Session

  MCP->>API: BeginMcpOauthDeviceAuthorization
  API-->>MCP: device_code + verification_uri
  User->>Browser: Login + approve
  Browser->>API: ApproveMcpOauthDeviceAuthorization
  MCP->>API: ExchangeMcpOauthDeviceAuthorization
  API-->>MCP: short-lived access token
  MCP->>API: Call integration operation

Implementation Checklist

1. Start device login from MCP.
2. Wait for user approval in browser.
3. Exchange for short-lived token.
4. Call required API operations.
5. Handle denied/expired outcomes cleanly.

• No static API keys for local MCP login.
• Use short-lived access tokens for API calls.
• Treat denied and expired outcomes as terminal states.
• Verify the full flow with E2E tests before rollout.