How to Verify Your Outlook Connection

Check your authentication status, re-authenticate after token expiry, and confirm which account is connected.

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:

Ask your AI assistant:

“Re-authenticate my Outlook account”

tool: auth
params:
  action: authenticate
  force: true

By default, this uses the device code flow — you’ll get a code to enter at microsoft.com/devicelogin. No auth server needed.
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.

Connect Outlook to Your AI Assistant — initial setup walkthrough
Azure Setup Guide — app registration and permissions
Tools Reference — auth — full parameter reference