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 reads “Authenticated and ready” with roughly how many minutes the current access token has left. If the access token has expired but the refresh token is still valid, it’s refreshed automatically; if that isn’t possible, the tool tells you to re-authenticate.

To see which account is connected and which permissions were granted, use action: about (below).

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

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

3. 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 and tool count
• the connected mailbox (display name and address)
• timezone, test mode, the safety belts with a setup hint if they’re off, and whether read-only mode (OUTLOOK_READ_ONLY) is on. The Session limits row lists each rate-limited tool (send-email, draft, create-event, manage-rules) with its limit and how many calls it has used, or BLOCKED when its limit is 0 (or not a whole number); the Recipient Allowlist row shows OUTLOOK_ALLOWED_RECIPIENTS
• the configured and granted scopes
• shared-mailbox status: whether OUTLOOK_SHARED_MAILBOX is on and whether each .Shared scope was actually granted

It never shows the tokens themselves, so it’s safe to paste into a bug report.

Check the Plugin’s Safety Hook#

This applies only if you installed the plugin (Claude Code, GitHub Copilot or Cursor). The hook stays quiet for reads, so a working connection doesn’t show whether it’s running. To check it without changing anything:

1. Ask your AI assistant to send a short test email to yourself.
2. When the prompt appears, decline it.

In Claude Code and Copilot CLI, the prompt includes the hook’s reason, starting “Outlook Assistant:”, for example “Outlook Assistant: Sends an email to you@example.com, subject ‘Test’. It can’t be unsent.” Cursor shows its own “Run this MCP tool?” prompt without the reason. If the prompt has no “Outlook Assistant:” reason in Claude Code or Copilot, the hook isn’t running: check that the plugin is enabled. Which client shows what is set out in Supported Clients and Their Limits.

If you use a manual MCP configuration rather than the plugin, there’s no hook; your client’s own approval prompts and the server’s checks apply.

Common Connection Problems#

Symptom	Cause	Fix
auth action=status says “Not authenticated”	No saved tokens, or they can’t be refreshed	Run through the initial setup, or re-authenticate with force: true
A tool returns “Authentication required.”	Signed out, or the token expired and couldn’t be refreshed (refresh token revoked or expired; on the browser flow, a changed client secret)	Follow the “Next step” in the message: sign in with auth action: authenticate (add force: true if a session exists), then retry
Auth succeeds but API calls fail with 403	Insufficient permissions	Add missing permissions in Azure Portal, then re-authenticate with force: true to pick up new scopes. auth action=about lists what was granted
”Shared-mailbox support is turned off”	OUTLOOK_SHARED_MAILBOX isn’t set	Set it, restart, and re-authenticate with force: true — see Access Shared Mailboxes (work/school accounts only)
“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 “Microsoft Graph API credentials are not set” (a “Configuration Error” page)	Auth server does not have env vars	Create a .env file in the directory you start it from, 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
• After adding permissions or turning on OUTLOOK_SHARED_MAILBOX, re-authenticate with force: true: a token refresh keeps the scopes you were originally granted and never adds new ones
• 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. If you gave the client ID to the auth tool instead of setting OUTLOOK_CLIENT_ID, it’s saved per computer in ~/.outlook-assistant-config.json, so pass it again (auth action=authenticate clientId=<id>) on each new machine.

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#

• Connect Outlook to Your AI Assistant — initial setup walkthrough
• Supported Clients and Their Limits — what the skill and safety hook do in each client
• Azure Setup Guide — app registration and permissions
• Tools Reference — auth — full parameter reference