Outlook Semantic MCP - FAQ

General

What type of MCP server is this?

Answer: The Outlook Semantic MCP Server is both an MCP server and a connector. It exposes 10 tools in microsoft_graph_and_unique_api mode (plus 4 debug-mode tools), or 6 tools in microsoft_graph mode. Once a user connects their account, it automatically syncs their emails into the Unique knowledge base in the background (Mode A only).

What it does:

• Automatically ingests the user's email history into the Unique knowledge base after connection, based on the configured filters.
• Exposes 10 tools (plus 4 debug-mode tools) for searching emails, managing drafts, listing folders, and monitoring sync status.
• Keeps the knowledge base up to date in real time via webhook-driven live catch-up.
• Requires no manual setup beyond the initial connection.

What the user sees:

• An initial OAuth consent screen to connect their Outlook account.
• 10 MCP tools available in their AI client immediately after connection (14 with debug mode enabled).
• Search results that may be incomplete while the initial full sync is running (a syncWarning is returned by search_emails).

What tools are available?

Answer: The server exposes 10 user-facing tools:

An additional 4 tools are available only when the server is running in debug mode (MCP_DEBUG_MODE=enabled): run_full_sync, pause_full_sync, resume_full_sync, restart_full_sync. These are intended for development and troubleshooting and are not exposed in production deployments.

In microsoft_graph mode, only the first 6 categories are available (Email Search, Draft Creation, Contact Lookup, Mailbox Utilities). Subscription Management and Sync Monitoring tools are not registered.

Do I need to do anything after connecting?

Answer: No. After granting consent, the server automatically creates a Microsoft Graph subscription and starts ingesting emails within the operator-configured time frame and filters. The 10 tools become available immediately (14 with debug mode enabled). Search results may be incomplete while the initial full sync is running.

Data Privacy & Storage

Does the MCP server store my emails?

Answer: No. The Outlook Semantic MCP Server stores no email content in its own database. Emails are fetched from Microsoft Graph into memory and forwarded directly to the Unique knowledge base for ingestion. Nothing from the email body, subject, sender, or recipients is written to the MCP server's PostgreSQL database.

Where is my email content stored?

Answer: Email content (subject, body, sender, recipients, and metadata) is stored in the Unique knowledge base, not in the MCP server itself. It is ingested there for semantic search and is accessible via the search_emails tool.

Who can access my email data once it is ingested?

Answer: Access to ingested email data operates at two levels:

Via the MCP server (tool layer): The search_emails tool returns results from the authenticated user's own email scope. When DELEGATED_ACCESS_SCAN is enabled and the user has been granted delegated access to another user's mailbox in Microsoft 365, search_emails also returns results from that owner's scope.

Via the Unique platform (platform layer): Email content stored in the Unique knowledge base is subject to Unique's own access control model.

Can an operator with database access read my emails?

Answer: No — not from the MCP server's PostgreSQL database. It contains no email content. An operator with direct database access would see only encrypted OAuth tokens, opaque random bearer tokens, sync state, and folder metadata.

What happens to my email data when I disconnect?

Answer: Calling delete_inbox_data deletes the Microsoft Graph subscription, removes the per-user root scopes from the Unique knowledge base, and clears the inbox configuration and folder sync data from PostgreSQL.

What email data is actually ingested into the knowledge base?

Answer: The following fields from each email are ingested:

• Subject
• Body (plain text and/or HTML)
• Sender (name and email address)
• To, CC, and BCC recipients
• Received date and time
• Folder Id
• Microsoft-assigned email ID and web link
• Attachments (supported types listed below)

Shared Inbox & Delegated Access

How do I set up delegated access?

Answer: Delegated access setup happens in Microsoft 365, not in the MCP. The MCP supports three configurations: an Exchange admin grants Full Access, a user shares specific folders via Outlook desktop, or a shared inbox is configured as a normal mailbox and connected to the MCP.

Who has access to a shared inbox?

Answer: Any user whose Microsoft 365 account has been granted access to another user's mailbox — either Full Access or folder-level delegation.

What happens with delegated access?

Answer: When a user has been granted delegated or shared mailbox access in Microsoft 365, the connector's background jobs detect this and make the delegated mailbox searchable. No additional ingestion occurs.

When shared inbox access is revoked, are previously ingested emails still accessible?

Mode A: No — access records are deleted on detection of revocation.

Mode B: Revocation takes effect immediately at query time — no results are returned from the revoked mailbox.

Why can't I search emails in a mailbox my colleague shared folders from?

Answer: This is a known Microsoft Graph API limitation that affects Mode B only. When a colleague shares individual folders without granting Full Access, Microsoft Graph rejects $search against that mailbox.

Supported Email Attachment Types

Answer: This section applies to Mode A only. In microsoft_graph mode, attachments are not ingested.

Documents

• PDF (.pdf)
• Word (.doc, .docx, .dotx)
• PowerPoint (.ppt, .pptx)
• Excel (.xls, .xlsx)

Text-based

• Plain text (.txt)
• HTML (.html, .htm)
• Markdown (.md)

Emails excluded by inbox filters are never ingested.

Tool Usage

How does search_emails search?

Mode A: search_emails runs two searches in parallel — semantic search against the Unique knowledge base and a KQL keyword search against Microsoft Graph. It supports natural-language queries and returns semantically relevant results.

Mode B: search_emails queries Microsoft Graph directly using KQL keyword search only.

How do I filter search results to a specific folder?

Use the list_mailboxes_and_directories tool to get the folder tree, then pass the folder ID in the directories field for filtering.

Can I attach files when creating a draft email?

Answer: Yes. The create_draft_email tool accepts attachments as an array of objects. The data field accepts a base64-encoded data URI or a Unique content URI.

Can I create drafts in a shared mailbox?

Answer: Yes. Pass the shared mailbox UPN as the mailbox parameter. The signed-in user must have been granted at least Send As or Full Access permissions to the shared mailbox in Microsoft 365.

Why does a reply draft in a shared mailbox appear in Drafts instead of in the thread in Outlook Web?

Answer: This is a known Outlook Web quirk. Reply drafts in a shared mailbox appear in the shared mailbox Drafts folder rather than inline.

What does reconnect_inbox do?

Answer: reconnect_inbox creates a new Microsoft Graph subscription only if none exists or the existing one has expired.

What does delete_inbox_data do?

Answer: delete_inbox_data permanently removes the user's inbox connection and all associated data, including ingested email content in the Unique knowledge base.

Sync

What is the difference between full sync and live catch-up?

How do I check sync progress?

Answer: Use the sync_progress tool to return the current fullSyncState, counters, and ingestion stats.

Why is my full sync stuck in waiting-for-ingestion?

Answer: Full sync enters waiting-for-ingestion after uploading all email batches and waits for confirmation from the Unique knowledge base.

Why is my full sync stuck in running?

Answer: The most common causes are large mailboxes, transient Microsoft Graph rate limits, and network issues.

What happens if full sync is interrupted (restart, crash)?

Answer: Full sync is resumable. The sync resumes from the stored cursor rather than starting over.

Why are new emails not appearing in search results?

Answer: Check active subscription, live catch-up state, and inbox filters.

What happens to emails sent during full sync?

Answer: Live catch-up processes new emails immediately while full sync is also running.

Why are deleted emails still appearing in search results?

Answer: Email deletion detection is asynchronous and may have a brief delay before removal.

Authentication & Permissions

Do any permissions require admin consent?

Answer: No. All permissions are delegated and do not require admin consent. Users can connect and grant consent themselves.

Why does the server need Mail.ReadWrite if it mostly reads emails?

Answer: Mail.ReadWrite is necessary for both reading and creating email messages in the user's mailbox.

Why can't I use application permissions instead of delegated?

Answer: Application permissions require tenant administrators to create access policies and defeat the self-service model.

Why do I need a client ID and client secret?

Answer: Microsoft Graph API uses OAuth 2.0. The CLIENT_ID identifies your app registration and the CLIENT_SECRET proves to Microsoft that your server is legitimate.

What is the "login flicker" when users reconnect?

Answer: Users may see a brief "flicker" when reconnecting as part of the OAuth process.

What happens when a user's Microsoft refresh token expires?

Answer: The server can no longer refresh access tokens for that user until reconnected through the reconnect_inbox tool.

Security

How are Microsoft tokens stored?

Answer: Microsoft access and refresh tokens are encrypted at rest.

How are MCP tokens stored?

Answer: MCP tokens are opaque random values and stored directly for comparison.

Why does the server use PKCE?

Answer: PKCE prevents authorization code interception, enhancing security.

What happens if a refresh token is stolen?

Answer: The token family revocation mechanism detects reuse and revokes the entire token family.

Configuration

What redirect URI should I configure in Entra ID?

Answer: The redirect URI must be exactly https://<your-domain>/auth/callback.

Why do I need a webhook secret?

Answer: The webhook secret validates that incoming notifications originate from Microsoft Graph.

What happens if I change the encryption key?

Answer: All stored Microsoft tokens become unreadable, and all users must reconnect.

What happens if I change the webhook secret?

Answer: All existing Microsoft Graph subscriptions will fail validation until recreated.

What happens if I change the client secret?

Answer: Update the Kubernetes secret and restart the pods. Users do not need to reconnect.

What does INGESTION_DEFAULT_MAIL_FILTERS do?

Answer: It controls which emails are ingested during full sync and live catch-up using JSON filters.

Deployment

Why is RabbitMQ required?

Answer: RabbitMQ decouples receipt from processing for webhook notifications.

What happens if RabbitMQ is unavailable?

Answer: Webhook trigger notifications cannot be published, which may lead to missed notifications.

What happens if PostgreSQL is unavailable?

Answer: Operations requiring database access will fail until PostgreSQL is restored.

Can one deployment serve multiple Microsoft tenants?

Answer: Yes. Configure the Entra ID app registration accordingly.

Disaster Recovery

What do I do if a core infrastructure component fails?

Answer: Each failure scenario requires specific user actions for re-authentication or restoring services based on the service mode.