Authenticate local and headless agents

OAuth remains the default. Reuse a CLI-managed OAuth session before considering a PAT.

Native OAuth — default

Configure the remote endpoint in your client and authorize in the browser. This is always the first choice. Cursor editor and CLI share their configuration; the example below uses native OAuth. See your client's guide for its exact setup.

liquidlm mcp install --client cursor
agent mcp login liquidlm

CLI-managed OAuth — second choice

When native OAuth is unsuitable, log in to LiquidLM and configure the client to launch liquidlm mcp serve over stdio. The CLI refreshes the session without requiring a PAT. Initial authorization requires interaction; log in on the machine running the agent. Use CLI 0.1.5 or newer.

  • Cursor, Codex, Claude Code, Claude Desktop and OpenCode have dedicated guides. ChatGPT web and Claude web cannot launch local processes; use remote OAuth.
unset LIQUIDLM_API_TOKEN LIQUIDLM_TOKEN
liquidlm login
liquidlm whoami
# Configure your client to launch this command:
liquidlm mcp serve

PAT — last fallback

Use a static API token only if both OAuth options are unsuitable. Create a PAT limited to the required actions and vaults, then inject LIQUIDLM_API_TOKEN through your secret manager. Keep its value out of configuration files and shell history.

  • LIQUIDLM_TOKEN is an alias. Environment tokens override the saved session: unset both variables to return to OAuth. Remote clients use different environment-reference syntax; follow the client-specific examples.
# LIQUIDLM_API_TOKEN is already injected into this process.
liquidlm mcp serve

Session storage and refresh

The CLI stores rotating refresh tokens in the OS keychain or, when unavailable, a private credentials file. If an older CLI lost the refresh token, upgrade and sign in once again. Access-token lifetime comes from expires_in. A revoked session requires authorization again; retries cannot revive it.

Do not copy credentials into a project or image. Run the proxy under the same user that authorized the CLI. A headless machine still needs a one-time OAuth authorization; if no authorized session can be established, use the explicit PAT fallback.

All client guides

CLI reference