Skip to content

oauth-mcp-http.md

Latest commit

 

History

History
115 lines (85 loc) · 3.03 KB

oauth-mcp-http.md

File metadata and controls

115 lines (85 loc) · 3.03 KB

MCP HTTP OAuth (Issue #97)

This document describes OAuth support for MCP HTTP in uxc.

OAuth tokens are stored in a credential (credentials.json). Runtime selection can use --auth <credential_id> or endpoint binding auto-match (auth_bindings.json).

Scope

Implemented in MVP:

  • OAuth login via device_code, authorization_code (PKCE), and client_credentials
  • Token persistence in ~/.uxc/credentials.json
  • Auto refresh before expiry (60s skew)
  • One-time refresh + retry on 401 Unauthorized
  • Structured error codes for OAuth failures

Commands

Login with Device Code:

uxc auth oauth login <credential_id> \
  --endpoint <mcp_url> \
  --flow device_code \
  --client-id <client_id> \
  --scope "openid profile"

Login with Client Credentials:

uxc auth oauth login <credential_id> \
  --endpoint <mcp_url> \
  --flow client_credentials \
  --client-id <client_id> \
  --client-secret <client_secret> \
  --scope "tools.read"

Login with Authorization Code + PKCE:

uxc auth oauth login <credential_id> \
  --endpoint <mcp_url> \
  --flow authorization_code \
  --redirect-uri <redirect_uri> \
  --scope "openid profile"

Use --authorization-code to provide the code directly, or run interactively and paste the authorization code / callback URL when prompted.

Agent-friendly two-step Authorization Code + PKCE:

uxc auth oauth start <credential_id> \
  --endpoint <mcp_url> \
  --redirect-uri <redirect_uri> \
  --client-id <client_id> \
  --scope "openid profile"
uxc auth oauth complete <credential_id> \
  --session-id <session_id> \
  --authorization-response "http://127.0.0.1:11111/callback?code=..."

Notes:

  • --client-id is optional for authorization_code.
  • When omitted, uxc will attempt OAuth Dynamic Client Registration via provider registration_endpoint (RFC 7591).
  • If provider does not expose registration, pass --client-id explicitly.
  • uxc auth oauth login ... --flow authorization_code remains available for single-process interactive use.
  • uxc auth oauth start/complete is intended for agents or any workflow where authorization must span multiple CLI invocations.

Refresh token manually:

uxc auth oauth refresh <credential_id>

Inspect OAuth credential:

uxc auth oauth info <credential_id>

Logout (clear OAuth token data in the credential):

uxc auth oauth logout <credential_id>

Runtime behavior

When calling MCP HTTP with an OAuth credential:

  1. If token is near expiry, uxc refreshes first.
  2. If server returns 401, uxc refreshes once and retries once.
  3. If refresh cannot continue, command returns structured OAuth errors.

Error codes

  • OAUTH_REQUIRED
  • OAUTH_DISCOVERY_FAILED
  • OAUTH_TOKEN_EXCHANGE_FAILED
  • OAUTH_REFRESH_FAILED
  • OAUTH_SCOPE_INSUFFICIENT

Notes

  • UXC supports mixed credential sources in the same store: literal, env, and op.
  • For external sources (env, op), resolved secret values are used at runtime and are not written back as plaintext credential values.