Outlook Semantic MCP - Architecture

The Outlook Semantic MCP Server is a NestJS-based microservice that connects Microsoft Outlook email with the Unique platform through the Model Context Protocol (MCP). It syncs emails from connected mailboxes into the Unique knowledge base and exposes MCP tools for AI-assisted email search, draft creation, and contact lookup.

High-Level Architecture

System Components

Authentication

The server manages two separate authentication layers:

• MCP OAuth — Authenticates MCP clients (e.g. Claude Desktop) using OAuth 2.1 with PKCE. Issues short-lived MCP tokens that clients use for all subsequent tool calls.

• Microsoft OAuth — Authenticates with Microsoft Entra ID using delegated permissions to obtain Graph API tokens on behalf of the signed-in user. These tokens are encrypted and stored server-side — they are never exposed to MCP clients.

The user authenticates once through a browser-based flow. The server exchanges the authorization code for Microsoft tokens (using a confidential client secret), stores them encrypted, and issues a separate MCP token to the client. From that point on, the MCP client authenticates with its MCP token, and the server uses the stored Microsoft tokens internally.

Token Lifetimes: MCP tokens (60-second access, 30-day refresh) are configurable. Microsoft tokens (~1-hour access, ~90-day refresh) are set by Microsoft. The server automatically refreshes expired Microsoft access tokens. If the refresh token itself expires (~90 days of inactivity), the user must reconnect. See Security — Token TTLs for the full reference.

MCP Tools

The tools layer exposes capabilities to AI clients over the Model Context Protocol. Each tool call is authenticated via MCP OAuth and, where needed, delegates to Microsoft Graph using the stored Microsoft token.

Tools fall into these categories:

• Email search — Queries the Unique knowledge base (no live Graph API call per search)

• Draft creation — Creates drafts in the user's Outlook Drafts folder via Graph API

• Contact lookup — Searches the user's Microsoft contacts directory via Graph API

• Mailbox utilities — Lists folders and categories via Graph API for search filtering

• Connection management — Checks webhook status, reconnects, or removes the mailbox connection

See Tools Reference for the full list and behavior details.

Sync Pipeline

After a user connects, the following pipelines keep the knowledge base in sync with the user's mailbox. See Flows for sequence diagrams.

Full Sync — triggers automatically after connection; fetches historical emails in paginated batches (newest first); applies INGESTION_DEFAULT_MAIL_FILTERS; resumable via persisted Graph cursor; initializes the watermark that live catch-up depends on.

Live Catch-Up — webhook-driven; acknowledged immediately via RabbitMQ, processed async in the consumer; queries Graph for messages since the watermark; watermark defaults to now() on inbox creation so notifications are never buffered.

Directory Sync — runs on a 5-minute delta query schedule (configurable via DIRECTORY_SYNC_CRON_SCHEDULE); keeps local folder tree in sync with Outlook; powers list_mailboxes_and_directories and folder-based search filtering; detects email deletion by tracking moves to excluded folders (e.g. Deleted Items).

Subscription Management — Graph webhook subscription created automatically on connect; renewed via Microsoft lifecycle notifications (reauthorizationRequired). If subscriptionRemoved, user calls reconnect_inbox; verify_inbox_connection reports status (active, expiring_soon, expired, not_configured).

Delegated Access Discovery (optional, DELEGATED_ACCESS_SCAN) — when not disabled, two background jobs keep delegated access state current. The discovery job (both fullAccessOnly and granularAccess modes) tests each connected user's access to other connected users' mailboxes via Microsoft Graph on a configurable schedule (default: every 12 hours; for fullAccessOnly consider 4× per day since discovery is the sole revocation mechanism). The verification job (granularAccess mode only, default: every 4 hours) confirms which individual folders within each delegated mailbox are still readable. Neither job triggers email ingestion — they write permission records that search_emails reads at query time to include the owner's scope alongside the delegate's own scope. A recovery scheduler (configurable via DELEGATED_ACCESS_RECOVERY_CRON_SCHEDULE) automatically restarts either job if it stalls. See Delegated Access Discovery Flow.

Data Storage (PostgreSQL)

PostgreSQL stores all persistent state:

• User profiles — Identity, encrypted Microsoft OAuth tokens

• MCP OAuth state — Client registrations, sessions, authorization codes, access/refresh tokens with family-based revocation

• Webhook subscriptions — Active Microsoft Graph subscriptions per user

• Sync state — Full sync progress, live catch-up state, mail filters per user

• Folder structure — Outlook directory tree synced from Graph API for folder-based filtering

• Delegated access state — delegatedAccessAccounts (delegate/owner pairs with access type) and delegatedAccessDirectories (folder-level access grants for granularAccess mode)

Microsoft tokens are encrypted at rest using AES-256-GCM. MCP tokens use 512-bit cryptographically random values with TTL-based expiration.

Message Queue (RabbitMQ)

RabbitMQ decouples webhook receipt from email processing to meet Microsoft's strict webhook response deadline (< 10 seconds). When a webhook notification arrives, it is acknowledged immediately and enqueued for asynchronous processing.

Failed messages are routed to a Dead Letter Exchange for inspection and retry.

Unique Integration

The server integrates with the Unique platform to:

• Ingest emails — Uploads email content to the Unique knowledge base during both full sync and live catch-up

• Search emails — Queries the knowledge base for semantic email search (the search_emails tool)

• Manage scopes — Creates and manages the knowledge base scope to which emails are synced

Related Documentation

• Flows - User connection, subscription lifecycle, email sync flows

• Security - Encryption, authentication, and threat model

• Permissions - Required Microsoft Graph scopes and least-privilege justification

Standard References

• Microsoft Graph API - Graph API overview

• Microsoft Entra ID - Authentication and authorization

• Model Context Protocol - MCP specification