Skip to content

verify-your-connection.md

Latest commit

 

History

History
131 lines (89 loc) · 6.67 KB

verify-your-connection.md

File metadata and controls

131 lines (89 loc) · 6.67 KB
title How to Verify Your Outlook Connection
description Check your authentication status, re-authenticate after token expiry, and confirm which account is connected.
tags
outlook-assistant
getting-started
how-to

How to Verify Your Outlook Connection

Check whether Outlook Assistant is authenticated, see which account is connected, and re-authenticate when tokens expire.

Check Authentication Status

Ask your AI assistant:

"Check my Outlook auth status"

The auth tool is called:

tool: auth
params:
  action: status

A healthy response shows:

  • Authenticated: Yes
  • Account: your-email@outlook.com
  • Token expires: date and time
  • Scopes: the permissions granted

If the token has expired, the tool will report it and suggest re-authenticating.

Auth tool status output showing authenticated user

Re-authenticate After Token Expiry

Tokens auto-refresh in the background (proactive refresh with a 5-minute buffer before expiry). You rarely need to manually re-authenticate. If refresh fails, re-authenticate:

  1. Ask your AI assistant:

"Re-authenticate my Outlook account"

tool: auth
params:
  action: authenticate
  force: true

  1. By default, this uses the device code flow — you'll get a code to enter at microsoft.com/devicelogin. No auth server needed.

  2. After signing in, tell your AI assistant to complete the flow:

tool: auth
params:
  action: device-code-complete

Alternative: For browser redirect flow, add method: browser to step 1 and start the auth server first.

Check Server Information

To see the server version and capabilities:

"Show Outlook Assistant server info"

tool: auth
params:
  action: about

This returns the server version, available tools, and configuration details.

Common Connection Problems

Symptom Cause Fix
"Not authenticated" No token file exists Run through the initial setup
"Token expired" with auto-refresh failure Refresh token revoked or client secret changed Re-authenticate with force: true
Auth succeeds but API calls fail with 403 Insufficient permissions Add missing permissions in Azure Portal, then delete ~/.outlook-assistant-tokens.json and re-authenticate to pick up new scopes
"AADSTS700082" Refresh token expired (>90 days inactive) Re-authenticate with force: true
"AADSTS7000215" Client secret is wrong (using Secret ID instead of Value) or has expired Check Azure Setup Guide — Client Secret
"Need admin approval" during OAuth Organisation requires admin consent Ask your IT admin to grant consent — see Admin Consent
Token file exists but auth reports failure Corrupted token file Delete ~/.outlook-assistant-tokens.json and re-authenticate
Auth server says "missing client ID" Auth server does not have env vars Create a .env file or export OUTLOOK_CLIENT_ID/OUTLOOK_CLIENT_SECRET in your shell — see Connect guide
Device code "invalid_client" Public client flows not enabled Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings
"No pending device code flow" Called device-code-complete before authenticate, or server restarted (pre-v3.7.2) Call auth with action: authenticate first. In v3.7.2+, device code state persists across server restarts.
"wrongplace" page after device code sign-in Normal — means sign-in completed but Microsoft doesn't know where to redirect Close the browser tab. The device code flow completed successfully. Call device-code-complete to finish.
Device code sign-in redirects to localhost Cached browser session interfering with device code flow Use a private/incognito browser window for microsoft.com/devicelogin
device-code-complete hangs silently The tool is polling Microsoft (not a permission prompt) — sign-in may not have completed Wait 10-15 seconds. If still hanging, press Escape, get a new code, sign in with incognito browser, and try again
search-emails returns no results Personal account $search limitation Use subject, from, to, receivedAfter filters instead of query — see Known Limitations

Tips

  • Tokens auto-refresh in the background — you rarely need to manually re-authenticate
  • If you switch Microsoft accounts, use force: true to authenticate with the new account
  • The token file at ~/.outlook-assistant-tokens.json contains sensitive credentials — don't share or commit it

Frequently Asked Questions

How often do I need to re-authenticate?

Rarely. Access tokens expire after about 1 hour, but the MCP server automatically refreshes them using the refresh token stored in ~/.outlook-assistant-tokens.json. Refresh tokens last up to 90 days of inactivity. You only need to manually re-authenticate if:

  • You have not used Outlook Assistant for more than 90 days
  • You changed your Microsoft account password
  • Your client secret expired (check the expiration date in Azure Portal)
  • An admin revoked your app's consent

Can I use Outlook Assistant on multiple computers?

Yes, but each computer needs its own authentication. The token file (~/.outlook-assistant-tokens.json) is stored locally and is not shared between machines. Run through the authentication steps on each computer.

Your Azure app registration and client credentials (OUTLOOK_CLIENT_ID/OUTLOOK_CLIENT_SECRET) are the same across all computers — only the token file differs.

What is the auth server and do I need it running all the time?

No. The auth server (port 3333) is only needed if you use the browser redirect auth flow (method=browser). With the default device code flow, you don't need the auth server at all. See Understanding the Processes for details.

My client secret is expiring soon — how do I rotate it?

See When Your Secret Expires in the Azure Setup Guide.

Related