Skip to main content

​
Overview

The auth command manages OAuth authentication tokens for MCP HTTP and SSE servers. Tokens are stored securely in your operating system’s keyring (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). 
fast-agent auth                 # Show auth status
fast-agent auth status          # Show detailed token status
fast-agent auth login my-server # Login to a server
fast-agent auth clear --all     # Clear all tokens

​
Usage

fast-agent auth [COMMAND] [OPTIONS]

​
Commands

​
status

Show keyring backend and token status for configured MCP servers. 
fast-agent auth status
fast-agent auth status my-server
fast-agent auth status https://api.example.com
With Target:
​
target
string
Identity (base URL) or server name to check. Optional.
# Check specific server by name
fast-agent auth status my-server

# Check by identity URL
fast-agent auth status https://api.example.com
​
--config-path
string
Path to config file.
fast-agent auth status --config-path ./config/fastagent.config.yaml
fast-agent auth status -c ./fastagent.config.yaml
Output Includes:
  • Keyring backend name and availability
  • Stored token identities
  • Per-server OAuth status
  • Token presence for each server
  • Server-to-identity mapping
  • Codex OAuth status (if configured)

​
login

Start OAuth flow and store tokens in the keyring for a server. 
fast-agent auth login my-server
fast-agent auth login https://api.example.com
fast-agent auth login https://api.example.com --transport sse
​
target
string
required
Server name (from config) or identity (base URL).
# Login to configured server
fast-agent auth login my-server

# Login to URL directly
fast-agent auth login https://api.example.com
​
--transport
string
default:"http"
Transport type for identity mode: http or sse.
fast-agent auth login https://api.example.com --transport http
fast-agent auth login https://api.example.com --transport sse
​
--config-path
string
Path to config file (for server name lookup).
fast-agent auth login my-server --config-path ./fastagent.config.yaml
How it Works:
  1. Opens OAuth authorization URL in browser
  2. Starts local callback server on port 3030
  3. Captures authorization code
  4. Exchanges code for tokens using PKCE
  5. Stores tokens securely in OS keyring

​
clear

Clear stored OAuth tokens from the keyring. 
fast-agent auth clear my-server
fast-agent auth clear --identity https://api.example.com
fast-agent auth clear --all
​
server
string
Server name to clear (from config).
fast-agent auth clear my-server
​
--identity
string
Token identity (base URL) to clear.
fast-agent auth clear --identity https://api.example.com
​
--all
boolean
default:false
Clear tokens for all identities in keyring.
fast-agent auth clear --all
​
--config-path
string
Path to config file.
fast-agent auth clear my-server --config-path ./fastagent.config.yaml
Clearing tokens requires confirmation. This action cannot be undone.

​
codex-login

Start OAuth flow for Codex and store tokens in the keyring. 
fast-agent auth codex-login
Initiates OAuth flow for OpenAI Codex access.

​
codexplan

Ensure Codex OAuth tokens are present; optionally start login. 
fast-agent auth codexplan
Checks for existing Codex tokens and prompts to login if not found.

​
codex-clear

Remove Codex OAuth tokens from the keyring. 
fast-agent auth codex-clear
Requires confirmation before removing tokens.

​
Configuration

​
OAuth Configuration in fastagent.config.yaml

OAuth is enabled by default for HTTP and SSE servers: 
mcp:
  servers:
    myserver:
      transport: http  # or sse
      url: http://localhost:8001/mcp
      auth:
        oauth: true              # default: true
        redirect_port: 3030      # default: 3030
        redirect_path: /callback # default: /callback
        persist: keyring         # default: keyring
        # scope: "user"          # optional

​
Disable OAuth

To disable OAuth for a specific server: 
mcp:
  servers:
    myserver:
      transport: http
      url: http://localhost:8001/mcp
      auth:
        oauth: false

​
In-Memory Token Storage

To use in-memory tokens instead of keyring: 
mcp:
  servers:
    myserver:
      transport: http
      url: http://localhost:8001/mcp
      auth:
        oauth: true
        persist: memory  # Tokens not saved between sessions

​
Identity Calculation

Tokens are keyed by “identity” (base URL) rather than full endpoint:
  • http://localhost:8001/mcp → identity: http://localhost:8001
  • https://api.example.com/v1/sse → identity: https://api.example.com
Multiple servers with the same base URL share tokens: 
mcp:
  servers:
    server1:
      url: https://api.example.com/mcp
    server2:
      url: https://api.example.com/v2/mcp
# Both use identity: https://api.example.com

​
Keyring Backends

​
macOS

Uses Keychain. Tokens stored in login keychain. 
# Check keyring status
fast-agent auth status
# Output: Keyring backend: macOS Keychain

​
Windows

Uses Credential Manager. 
fast-agent auth status
# Output: Keyring backend: Windows Credential Manager

​
Linux

Uses Secret Service (GNOME Keyring, KWallet, etc.). 
fast-agent auth status
# Output: Keyring backend: Secret Service

​
Headless/Container

Falls back to in-memory storage if no keyring available. 
fast-agent auth status
# Output: Keyring backend: not available

​
Examples

​
Check Authentication Status

fast-agent auth status
Output: 
Keyring backend: macOS Keychain

Stored Tokens (Identity)         Present
https://api.example.com          ✓
http://localhost:8001            ✗

Server      Transport  OAuth  Persist   Token  Identity
myserver    HTTP       on     keyring   ✓      https://api.example.com
local-dev   HTTP       on     keyring   ✗      http://localhost:8001

​
Login to Configured Server

fast-agent auth login myserver
Process:
  1. Discovers OAuth endpoints from server
  2. Opens browser to authorization URL
  3. Starts local server on port 3030
  4. Captures authorization code
  5. Exchanges for access/refresh tokens
  6. Stores in keyring
Output: 
Authenticated. Tokens stored for identity: https://api.example.com

​
Login to URL Directly

fast-agent auth login https://api.example.com
Uses HTTP transport and /mcp endpoint by default. 
fast-agent auth login https://api.example.com --transport sse
Uses SSE transport and /sse endpoint.

​
Check Specific Server Status

fast-agent auth status myserver
Output: 
Keyring backend: macOS Keychain

Identity                    Token  Servers
https://api.example.com     ✓      myserver, myserver-v2

​
Clear Specific Server Tokens

fast-agent auth clear myserver
Prompt: 
Remove tokens for the selected server(s) from keyring? [y/N]: y
Tokens removed.

​
Clear All Tokens

fast-agent auth clear --all
Prompt: 
Remove tokens for the selected server(s) from keyring? [y/N]: y
Tokens removed.

​
Clear by Identity

fast-agent auth clear --identity https://api.example.com
Removes tokens for all servers with this base URL.

​
PKCE Flow

fast-agent uses OAuth 2.0 with PKCE (Proof Key for Code Exchange):
  1. Generate Code Verifier: Random string
  2. Calculate Code Challenge: SHA-256 hash of verifier
  3. Authorization Request: Send challenge to server
  4. User Authorization: User approves in browser
  5. Authorization Code: Server redirects with code
  6. Token Exchange: Exchange code + verifier for tokens
  7. Store Tokens: Save to keyring
PKCE prevents authorization code interception attacks.

​
Token Refresh

Tokens are automatically refreshed when:
  • Access token expires
  • Server returns 401 Unauthorized
  • Refresh token is valid
If refresh fails, re-authentication is required: 
fast-agent auth login myserver

​
Callback Server

The local callback server:
  • Runs on localhost:3030 by default
  • Handles OAuth redirect
  • Captures authorization code
  • Shuts down after single use

​
Custom Port

mcp:
  servers:
    myserver:
      auth:
        redirect_port: 8080
        redirect_path: /oauth/callback

​
Port Unavailable

If the port is in use:
  1. Shows fallback URL
  2. Prompts to paste authorization code manually
Callback server unavailable. Please paste the full redirect URL:

​
Security Considerations

1

Keyring Encryption

OS keyring provides encrypted storage. Tokens are protected by system credentials.
2

In-Memory Fallback

If keyring unavailable, tokens stored in memory only. Cleared on exit.
3

PKCE Protection

PKCE prevents authorization code interception attacks.
4

Localhost Callback

Callback server only listens on localhost. Not accessible from network.
5

Token Scope

Request minimal scopes necessary for MCP server access.

​
Troubleshooting

​
Keyring Not Available

Linux: Install gnome-keyring or kwallet: 
sudo apt-get install gnome-keyring
Headless Server: Use in-memory storage: 
auth:
  persist: memory

​
Browser Not Opening

Manually open the displayed URL in your browser.

​
Callback Port in Use

Change the redirect port in configuration: 
auth:
  redirect_port: 8080

​
Token Expired

Re-authenticate: 
fast-agent auth login myserver

​
STDIO Servers

STDIO servers do not use OAuth. They are automatically excluded from auth commands.

​
Token Not Found After Login

Verify keyring is writable: 
fast-agent auth status
Check keyring backend is not “fail” or “unavailable”.

MCP OAuth

Learn about MCP OAuth implementation

Configuration

Configure MCP servers with OAuth

go Command

Use authenticated servers in sessions

Security

Security best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us