Outlook Semantic MCP

Getting Started

• IT Operators: Start with the Operator Guide for deployment, configuration, and operations

• Technical Reference: See the Technical Reference for architecture, flows, and design decisions

• FAQ: See the FAQ for common questions

Overview

The Outlook Semantic MCP Server is a cloud-native MCP server that gives AI assistants direct access to a user's Microsoft Outlook mailbox. Users connect their Microsoft account once, after which the server syncs emails within an operator-configured time frame (with additional content and sender filters) and maintains a live, webhook-driven view of new mail. AI clients can then search emails, compose drafts, look up contacts, and list folders through 10 MCP tools (plus 4 additional debug-mode tools).

Note: This service is both an MCP server and a connector. It exposes tools for AI clients to invoke on demand, and once a user connects their account, it automatically syncs their emails (within an operator-configured time frame and filters) into the Unique knowledge base in the background.

For deployment, configuration, and operational details, see the IT Operator Guide.

Quick Summary

What it does: Provides AI clients with 10 MCP tools (plus 4 debug-mode tools) for searching emails, composing drafts, looking up contacts, listing folders, and monitoring sync status against a user's Microsoft Outlook mailbox

Deployment: Kubernetes-based NestJS microservice

Authentication: MCP OAuth 2.1 with PKCE for MCP clients; delegated Microsoft OAuth 2.0 for Microsoft Graph API access

Processing: Dual-mode — batch full sync for historical email ingestion into the Unique knowledge base, and real-time webhook-driven live catch-up for new mail

Requirements

Microsoft 365 / Outlook

Prerequisites:

• Access to Microsoft Entra ID for app registration

• Users must consent to the required delegated permissions (or admin consent can be pre-granted for organisational rollout)

Permissions

All permissions are delegated and require no admin consent. This includes Mail.ReadWrite.Shared, which is always requested at OAuth time (even when DELEGATED_ACCESS_SCAN=disabled) and enables delegated mailbox access when configured. See Permissions for the full list and least-privilege justifications.

Features

Core Capabilities

Email Search

• Unique semantic search across the user's mailbox via the search_emails tool

• Open individual emails by message ID via open_email_by_id

• Search emails using the search_emails tool. In MicrosoftGraphAndUniqueApi mode, the tool runs semantic search against the Unique knowledge base and a live KQL query against Microsoft Graph in parallel, merging the results. In MicrosoftGraph mode, the tool queries Microsoft Graph directly using KQL — no knowledge base or ingestion is involved.

Draft Creation

• Create draft emails with subject, body, recipients, and attachments via create_draft_email

• Drafts are written directly to the user's Outlook Drafts folder via Microsoft Graph

Contact Lookup

• Search the user's Microsoft contacts directory via lookup_contacts

• Returns display names and email addresses for address resolution

Mailbox Utilities

• List all accessible mailboxes and their folder trees via list_mailboxes_and_directories — folder IDs from this tool can be passed to search_emails filters

• Retrieve email categories via list_categories to obtain category names for filtering searches

Delegated Mailbox Access (Optional)

• When DELEGATED_ACCESS_SCAN is enabled, the server automatically discovers users who have been granted Exchange mailbox delegation by other users

• Delegates can search and access the inboxes of users who have granted them Full Access or folder-level delegation via Exchange admin

• See Features — Delegated Access for supported configurations and setup

• See DELEGATED_ACCESS_SCAN for configuration details

Subscription Management

• Check mailbox connection and webhook subscription status via verify_inbox_connection (returns: active, expiring_soon, expired, not_configured)

• Reconnect a mailbox after token expiry or webhook failure via reconnect_inbox

• Permanently delete synced inbox data and stop ingestion via delete_inbox_data

• Microsoft Graph webhook subscriptions created automatically on connection and renewed before expiration

Full Sync (Historical Batch Ingestion)

• After connecting, the server automatically begins a full sync to ingest emails within the operator-configured time frame and filters (see Configuration)

• Sync progress can be monitored via the sync_progress tool, which reports the current state, counters, and date range being processed

• sync_progress returns a top-level state (running, finished, error) and a detailed fullSyncState (ready, running, waiting-for-ingestion, paused, failed), along with the number of emails ingested, the date window being processed, and a warning if results may be incomplete

Live Catch-Up (Real-Time Webhook-Driven)

• Receives Microsoft Graph change notifications the moment new mail arrives

• New emails processed asynchronously via RabbitMQ to meet Microsoft's strict webhook response deadline

Advanced Features

Security

• OAuth 2.1 with PKCE for MCP client authentication (RFC 7636)

• Microsoft tokens encrypted at rest using AES-256-GCM

• Refresh token rotation with family-based revocation

• Webhook payloads validated via clientState secret

• See Security Documentation for details

Reliability

• RabbitMQ message queue for asynchronous webhook processing

• Dead Letter Exchange (DLX) for failed message inspection and retry

• Meets Microsoft's strict webhook response requirements (< 10 seconds)

Observability

• Detailed logging with trace IDs

• Sync progress reporting via sync_progress tool

Configuration

• Automatic subscription renewal via Microsoft Graph lifecycle notifications

How It Works

High-Level Architecture

See Architecture Documentation for detailed component diagrams.

User Connection Flow

The user opens their MCP client and connects to the server. The client initiates an OAuth 2.1 authorization flow with PKCE against Microsoft Entra ID. After the user grants permissions, the server exchanges the authorization code for Microsoft tokens, encrypts and stores them, and issues a separate short-lived MCP bearer token to the client. A Microsoft Graph webhook subscription and a full email sync are then triggered automatically — no further user action is needed.

See User OAuth Connection Flow for the detailed sequence diagram.

Token Refresh

Microsoft access tokens expire after approximately one hour. The server intercepts 401 responses from the Graph API and transparently refreshes the token using the stored refresh token. If the refresh token itself has expired (~90 days of inactivity), the user must reconnect via reconnect_inbox.

See Microsoft Token Refresh Flow for the detailed sequence diagram.

Subscription Lifecycle

Microsoft Graph webhook subscriptions for messages last up to 7 days. The server creates subscriptions on user connection and renews them automatically via Microsoft lifecycle notifications (reauthorizationRequired). If Microsoft removes a subscription (subscriptionRemoved), the server cleans up the associated records.

See Subscription Creation and Renewal Lifecycle for the detailed sequence diagram.

Email Sync

Email ingestion uses two concurrent pipelines:

• Full Sync — After connection, the server automatically fetches the user's historical emails (within the configured time frame and filters) from Microsoft Graph in paginated batches and uploads them to the Unique knowledge base. The sync is resumable across restarts and initializes a watermark for live catch-up. See Architecture — Sync Pipeline for details.

• Live Catch-Up — Microsoft Graph sends webhook notifications when new mail arrives. The server enqueues them via RabbitMQ (to meet Microsoft's 10-second response deadline) and processes them asynchronously, fetching new messages since the last watermark and uploading them to the knowledge base. See Architecture — Sync Pipeline for details.

Both pipelines run concurrently after connection. Live catch-up buffers notifications until full sync initializes the watermark, after which both ingest independently.

See Flows for the detailed sequence diagrams.

Directory Sync

The server continuously syncs the user's Outlook folder structure via Microsoft Graph delta queries. This enables folder-based search filtering (list_mailboxes_and_directories tool; folder filtering only applies in MicrosoftGraphAndUniqueApi mode) and tracks email movement to handle deletions — when an email moves to an excluded folder (e.g. Deleted Items), it is removed from the knowledge base.

See Directory Sync Flow for the detailed sequence diagram.

Draft Creation

The create_draft_email tool creates a draft in the user's Outlook Drafts folder via Microsoft Graph. The draft is not sent automatically — the response includes a webLink for the user to review and send from Outlook.

See Email Draft Creation Flow for the detailed sequence diagram.

User Workflow

1. User Setup (One-time) - Open MCP client and connect to Outlook Semantic MCP Server - Sign in with Microsoft account and grant required permissions - The server automatically creates a webhook subscription and starts syncing emails — no user action is needed beyond granting permissions

2. Initial Sync (Automatic) - After connecting, the server automatically begins syncing emails (within the configured time frame and filters) into the Unique knowledge base - Use sync_progress to monitor sync status — results will be partial until the sync completes - Use verify_inbox_connection to check the status of the webhook subscription

3. Live Mail (Ongoing) - New emails arrive in Outlook - Server receives Microsoft Graph webhook notification automatically - It uploads the email to Unique Knowledge Base - Email is available for search once Knowledge Base ingests it

4. AI-Assisted Email Tasks (On-demand) - Search emails with search_emails - Open specific messages with open_email_by_id - Compose drafts with create_draft_email - Look up contacts with lookup_contacts - Use list_mailboxes_and_directories and list_categories to obtain folder IDs and category names for filtering searches

Limitations and Constraints

Authentication Constraints

See Architecture — Authentication for details.

Operational Constraints

Feature Constraints

Scaling Considerations

Not Supported

• Application permissions: The server uses delegated permissions only (acting on behalf of a signed-in user). It does not support application-level permissions, so it cannot run as a background daemon accessing mailboxes without user sign-in

• Calendar or task data: Only mail and contacts are in scope

• Token introspection: MCP tokens validated locally with short TTLs for performance

Related Documentation

• FAQ - Frequently asked questions

For IT Operators

• Operator Guide - Deployment, configuration, and operations

• Deployment - Kubernetes and Helm setup

• Configuration - Environment variables and settings

• Authentication - Microsoft Entra ID setup

• Local Development - Running the server locally

Standard References

• Microsoft Graph API - Microsoft Graph documentation

• Microsoft Graph Permissions Reference - Permission details

• Microsoft Entra ID Documentation - Authentication and authorization

• Microsoft Graph Webhooks - Change notifications overview

• OAuth 2.1 - OAuth 2.1 specification

• RFC 7636 - PKCE - Proof Key for Code Exchange

• RFC 6749 - OAuth 2.0 - OAuth 2.0 Authorization Framework

• Model Context Protocol - MCP specification

• MCP Authorization - MCP authorization spec