ProxmoxMCP-Plus v0.5.22

Release date: 2026-09-26

Optional OAuth for native MCP HTTP clients (#138)

Native Streamable HTTP can use an authorization-code flow with PKCE when
MCP_OAUTH_ENABLED=true. The MCP Python SDK handles OAuth discovery,
registration, request validation, token exchange and Bearer protection.
ProxmoxMCP-Plus provides a consent page where the operator enters the existing
MCP_API_KEY. The OAuth client receives an authorization code, never the key.

OAuth clients, codes, access/refresh tokens, login failures and key-version
metadata are stored in PostgreSQL. The database is initialized before HTTP
requests are accepted. Key rotation with a higher MCP_OAUTH_KEY_VERSION
invalidates existing OAuth credentials across workers. A slower, issuer-scoped
key verifier protects the stored API-key fingerprint. Authorization and refresh
tokens are checked for expiry again when atomically consumed.

The existing API-key Bearer behavior remains the default when OAuth is off.
OAuth is limited to Streamable HTTP; STDIO and SSE retain their existing modes.

Upgrade

Install proxmox-mcp-plus==0.5.22 or pull
ghcr.io/rekklesna/proxmoxmcp-plus:0.5.22, then restart and reconnect clients.
To enable OAuth, provide MCP_API_KEY, MCP_OAUTH_ISSUER, and
MCP_OAUTH_DATABASE_URL for a reachable PostgreSQL database, then set
MCP_OAUTH_ENABLED=true. The database role needs permission to create and
modify the proxmox_mcp_oauth_* tables. Protect this database and backups as
credential storage. Keep MCP_OAUTH_KEY_VERSION consistent among workers and
increment it whenever the API key changes. See the README for all options.

Validation and limits

Regression tests cover end-to-end OAuth with PostgreSQL, client registration,
consent, PKCE token exchange, MCP access, expiry, refresh rotation/replay,
key rotation, and default-mode compatibility. CI validates Python 3.11/3.12,
CodeQL, dependency audit, package metadata and build artifacts. No live
Proxmox instance is used by the OAuth test suite.