Outlook Semantic MCP — Operator Manual

Overview

The Outlook Semantic MCP Server exposes MCP tools that allow AI assistants to search and retrieve email content. In microsoft_graph_and_unique_api mode (the default), it also runs background pipelines that ingest emails from connected Microsoft 365 accounts into the Unique knowledge base via Microsoft Graph webhooks and RabbitMQ. In microsoft_graph mode, no ingestion runs — emails are queried live from Microsoft Graph.

For end-user and administrator documentation, see the Outlook Semantic MCP Overview.

Architecture

The connector runs as a single pod that handles MCP tool requests, stores state in PostgreSQL, and authenticates users via Microsoft Entra ID. The deployment mode (MCP_BACKEND) determines whether emails are ingested into the Unique knowledge base or queried live from Microsoft Graph.

Mode A — microsoft_graph_and_unique_api

After a user connects, the pod creates a Microsoft Graph webhook subscription and runs background pipelines (full sync and live catch-up) that ingest emails into the Unique knowledge base. search_emails runs semantic search against the knowledge base and KQL keyword search against Microsoft Graph in parallel, then merges the results. RabbitMQ decouples webhook receipt from email processing so the service can respond to Microsoft within the required deadline.

Mode B — microsoft_graph

No ingestion pipeline runs — no webhook subscriptions are created and no email content is written to the Unique knowledge base. search_emails queries Microsoft Graph directly using KQL keyword search. The Unique knowledge base is still required for scope management and to attach email attachments to outgoing drafts. RabbitMQ remains a required infrastructure dependency but is not part of the email data path.

Quick Start

Unique SaaS

After granting admin consent, provide the following to Unique Support or Solution Engineering:

-

• Backend mode — controls how email search works; see Deployment Modes for the full trade-offs:
  • microsoft_graph — live KQL search directly against Microsoft Graph; no email ingestion into Unique KB; lighter deployment
  • microsoft_graph_and_unique_api (default) — emails ingested into Unique KB; semantic search merged with live KQL results; heavier but richer
• • Delegated access scan — only relevant if your organization uses Exchange mailbox delegation; see DELEGATED_ACCESS_SCAN:
    • disabled (default) — no delegation scanning
    • full_access_only — Full Access (Read & Manage) grants via Exchange admin
    • granular_access — folder-level grants;

Unique will configure your deployment using the following process:

1. Create a Zitadel service account for the MCP in your organization.
2. Deploy the MCP to your tenant and configure it according to your needs.
3. The MCP server endpoint URL will be sent to you once everything is configured.

For full configuration capabilities, see the Configuration Guide.

Self-Hosted

Follow these steps to go from zero to a running deployment:

1. Register Microsoft Entra ID application — Create an app registration with the required delegated permissions.
2. Create Zitadel service account — Create a service user and assign the required permissions.
3. Provision infrastructure — Set up PostgreSQL 17+, RabbitMQ 4+, and a Kubernetes namespace.
4. Create Kubernetes secrets — Generate cryptographic secrets and store them as Kubernetes Secrets.
5. Configure Helm values — Create a values.yaml with your secrets, Microsoft client ID, and Unique API endpoints.

Key decisions: Set MCP_BACKEND and optionally DELEGATED_ACCESS_SCAN.

1. Deploy with Helm — Install the chart.
2. Security checklist — Before going to production, verify the following:
   • ENCRYPTION_KEY is a cryptographically random 64-character hex string
   • See Configuration — Required Secrets.
3. Verify the deployment is working:
   • Check the OAuth metadata endpoint.
   • Connect with an MCP client and complete the OAuth flow.
   • Call verify_inbox_connection to confirm the webhook subscription is active.
   • Draft a test email to the connected account, wait a moment, then use search_emails to confirm it appears.
   • Draft a test email to the connected account, then call search_emails with a simple KQL query to confirm it returns results from Microsoft Graph.
   • (Optional) Enable delegated access — If your organization uses Exchange mailbox delegation, set delegatedAccessScan in your Helm values.

Scaling Considerations

• Directory sync processes a maximum of 10 users per scheduled run (every 5 minutes). For large deployments with many connected users, account for the fact that folder sync updates are distributed across multiple runs.

Documentation