Authentication

ATOMS MCP Server supports two authentication methods: interactive OAuth for desktop use and access tokens for CI/CD pipelines.

Interactive OAuth (recommended)

The default login flow uses OAuth 2.1 with PKCE : the same industry-standard flow used by GitHub CLI and other developer tools.

npx @atoms-tech/atoms-mcp login

What happens

A local HTTP server starts on localhost:19275
Your browser opens to the ATOMS consent page
You approve the connection
Tokens are exchanged using PKCE (no secrets transmitted)
Credentials are saved to ~/.atoms/credentials.json with 0600 permissions

Token refresh

Tokens refresh automatically. The server checks expiry before each request and refreshes if the token expires within 60 seconds.

CLI commands

npx @atoms-tech/atoms-mcp login    # Interactive OAuth login
npx @atoms-tech/atoms-mcp logout   # Delete stored credentials
npx @atoms-tech/atoms-mcp whoami   # Show current user

Headless / CI mode

For automation, set the ATOMS_ACCESS_TOKEN environment variable:

export ATOMS_ACCESS_TOKEN="eyJhbGciOiJIUzI1..."

The access token is a Supabase JWT. You can obtain one from your ATOMS account settings or by extracting the access_token from ~/.atoms/credentials.json after logging in.

Priority order

The server resolves authentication in this order:

ATOMS_ACCESS_TOKEN environment variable (highest priority)
Stored credentials at ~/.atoms/credentials.json
Interactive login prompt (if running in a terminal)

Environment variables

Variable	Purpose	Default
`ATOMS_ACCESS_TOKEN`	JWT for headless auth	:
`ATOMS_APP_URL`	Override consent page URL	`https://x.atoms.tech`
`ATOMS_RATE_LIMIT_RPM`	Requests per minute limit	`60`
`ATOMS_CLIENT_NAME`	Client identifier for audit logs	`unknown`

Security notes

Credentials are stored with 0600 file permissions (owner read/write only)
No secrets are embedded in the npm package : the published anon key only grants API gateway access
All data access is enforced by Supabase Row Level Security using your JWT
Token refresh happens transparently without re-authentication

Authentication

On this page