Outlook Plugin — Operator Guide

The outlook plugin gives the admin agent read-only access to Microsoft 365 / Outlook.com via Microsoft Graph. Per-account OAuth (Auth Code + PKCE), encrypted token storage, automatic refresh.

Quickstart

1. Register an Entra app once per Maxy install — see platform/plugins/outlook/references/auth.md for full steps. Set OUTLOOK_CLIENT_ID (and OUTLOOK_TENANT_ID, default common) in the operator's environment.
2. Per account: register the Outlook account — in admin chat, ask the agent to "register my Outlook account". The agent runs outlook-account-register, which prints an authorization URL.
3. Open the URL in the VNC browser — sign in to your Microsoft account, consent to the requested scopes (offline_access, User.Read, Mail.Read, Calendars.Read, Contacts.Read).
4. Done. Subsequent tool calls (mail, calendar, contacts) use the persisted refresh token transparently.

Tools

Observability

All log lines start with [outlook-mcp] and write to server.log. They are key=value, account-scoped:

Diagnostic paths

# All outlook lines for one account, last 50
ssh laptop 'grep -E "^\[outlook-mcp\]" ~/.maxy/logs/server.log | grep "account=<id>" | tail -50'

# Token-leak audit — must always return zero
grep -rn -iE "Bearer |access_token=" ~/.maxy/logs/server.log | head

Latency triage: mail-list count=0 elapsedMs<200 consistent → permissions issue; elapsedMs > 5000 → Graph slowness or DNS.

Failure modes

Out of scope

Write tools (send, draft, move, flag), OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (User.Read.All, AuditLog.Read.All), public-agent exposure, multi-tenant federation. See platform/plugins/outlook/PLUGIN.md for the full out-of-scope list.