Authentication Tools

Tools for authenticating with the Assistatron MCP server. Authentication uses the WorkOS device authorization flow, which is designed for CLI and headless environments where the user cannot enter credentials directly.

These tools are always visible (even before authentication).

Authentication Flow

login
    |
    v
User opens URL in browser and enters code
    |
    v
check_login(device_code)
    |
    +---> status: "pending"   --> wait, then call check_login again
    |
    +---> status: "complete"  --> authenticated! save tokens
    |
    +---> status: "error"     --> show error, retry login

... later, when access_token expires ...

refresh_session(refresh_token)
    |
    v
New access_token + refresh_token

login

Start the WorkOS device authorization flow. Returns a verification URL and user code that the user must enter in their browser.

Parameters: None.

Response: LoginResult

{
  "user_code": "ABCD-1234",
  "verification_uri": "https://auth.assistatron.com/activate",
  "device_code": "dc_abc123...",
  "expires_in": 600,
  "interval": 5,
  "next_action": "Open https://auth.assistatron.com/activate in your browser and enter code: ABCD-1234."
}
Field Description
user_code Short code the user enters at the verification URL
verification_uri URL the user opens in their browser
device_code Opaque code passed to check_login
expires_in Seconds until the code expires (typically 600 = 10 minutes)
interval Minimum seconds between check_login calls (typically 5)

Agent behavior

  1. Present the verification_uri and user_code to the user
  2. Ask the user to open the URL and enter the code
  3. Wait for the user to confirm they have approved
  4. Call check_login(device_code=...) to complete authentication

check_login

Complete device authorization after the user has approved in their browser. Single non-blocking poll -- does not loop.

Parameter Type Required Description
device_code string Yes Device code from login

Response: CheckLoginResult

When complete (user approved):

{
  "status": "complete",
  "access_token": "at_...",
  "refresh_token": "rt_...",
  "next_steps": "Login unlocked new tools. Tell the user to save the tokens."
}

When pending (user has not yet approved):

{
  "status": "pending"
}

When failed:

{
  "status": "error",
  "message": "Authentication failed"
}

After successful authentication

  • New tools become available (onboarding tools, then trading tools after onboarding). The tool list should update automatically via the tools/list_changed notification.
  • Tell the user to save both tokens:
    • access_token: send as Authorization: Bearer <token> header for future MCP connections
    • refresh_token: use with refresh_session when the access token expires

refresh_session

Exchange an expired session for new tokens. Call this when authenticated tools return a session-expired error.

Parameter Type Required Description
refresh_token string Yes Refresh token from a previous check_login or refresh_session

Response: RefreshSessionResult

On success:

{
  "status": "ok",
  "access_token": "at_new_...",
  "refresh_token": "rt_new_..."
}

On failure:

{
  "status": "error",
  "message": "Refresh token is invalid or expired. Please login again."
}

Token rotation: both the access and refresh tokens are replaced. The old tokens are invalidated. Tell the user to update their MCP client configuration with the new tokens.

Bearer Token Usage

After authentication, pass the access token as a Bearer header on the MCP connection:

Authorization: Bearer at_...

For MCP stdio connections, the token is typically configured in the MCP client's server configuration file.

Token Lifecycle

Token Lifetime Renewal
access_token Short-lived (minutes to hours) Call refresh_session
refresh_token Long-lived (days to weeks) Rotated on each refresh
device_code 10 minutes Start a new login flow

Cross-references