Support OAuth 2.0 Device Authorization Grant (device_code) for headless environments

[KittisakT]

Problem

Some OAuth authorization servers advertise support for the Device Authorization Grant (RFC 8628) via OAuth metadata, e.g.:

• .well-known/oauth-authorization-server includes device_authorization_endpoint
• grant_types_supported includes urn:ietf:params:oauth:grant-type:device_code

However, mcp-remote currently only supports browser-based PKCE (authorization_code) flow, which blocks headless environments.

Current behavior

• mcp-remote discovers OAuth server config and then requires visiting an authorization URL + local callback server (e.g. http://127.0.0.1:<port>/oauth/callback).
• There is no CLI option to force device flow / no-browser flow.
• Client metadata appears to only request authorization_code + refresh_token grant types.

Requested feature

Add support for the OAuth 2.0 Device Authorization Grant (RFC 8628) when the server supports it.

Detection

If OAuth metadata contains:

• device_authorization_endpoint
• and grant_types_supported contains urn:ietf:params:oauth:grant-type:device_code

then mcp-remote should be able to use device flow.

UX / CLI

Provide one of:

• --device-code (force device flow)
• --no-browser (use device flow when available, otherwise error)

and ideally allow --device-code even if a browser is available.

Flow

1. POST to device_authorization_endpoint with client_id + scope
2. Print verification_uri (+ user_code) or verification_uri_complete
3. Poll token endpoint until success/expired/denied (respect interval)
4. Persist refresh token like current flow (so subsequent runs are non-interactive)

Storage

Use the same token cache mechanism as the current authorization_code flow so cron jobs can run without re-auth every time.

Why it matters

This enables mcp-remote to be used reliably in:

• cron/scheduled jobs
• servers
• SSH-only machines
• environments where opening a browser is not possible

Workarounds today

• Manually perform a browser PKCE flow (not possible in many headless environments)
• Bootstrap access tokens outside mcp-remote and pass --header 'Authorization: Bearer ...' (short-lived; no refresh token; not viable for cron)

Environment

• mcp-remote: 0.1.38
• Authorization server supports device flow via .well-known metadata

Thanks!