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 (see Authentication for why this is needed), 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 (i.e. users who have been granted access to another user's mailbox or folders); 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 (e.g. shared Inbox or RFQ folder); subsumes full_access_only

Unique will configure your deployment using the following process:

1. Create a Zitadel service account for the MCP in your organization — see Zitadel Service Account for the required permissions

2. Deploy the MCP to your tenant and configure it according to your needs — see Deployment Guide

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. See Authentication Guide.

2. Create Zitadel service account — Create a service user and assign the required permissions. Required for both cluster_local and external auth modes in both Mode A and Mode B. See Zitadel Service Account for setup and required permissions.

3. Provision infrastructure — Set up PostgreSQL 17+, RabbitMQ 4+, and a Kubernetes namespace. See Deployment — Prerequisites.

4. Create Kubernetes secrets — Generate cryptographic secrets and store them as Kubernetes Secrets. See Deployment — Required Secrets.

5. Configure Helm values — Create a values.yaml with your secrets, Microsoft client ID, and Unique API endpoints. See Configuration Guide.

Key decisions: Set MCP_BACKEND (see Deployment Modes) and optionally DELEGATED_ACCESS_SCAN (see Configuration).

1. Deploy with Helm — Install the chart. See Deployment — Install.

2. Security checklist — Before going to production, verify the following:

For the full security architecture, see Security Documentation. For a breakdown of what data is stored where, see Data Classification and Flow.

1. Verify the deployment is working:

2. Check the OAuth metadata endpoint: curl https://<your-domain>/.well-known/oauth-authorization-server

3. Connect with an MCP client and complete the OAuth flow

4. (Mode A only) 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

5. (Mode B only) Draft a test email to the connected account, call search_emails with a simple KQL query to confirm it returns results from Microsoft Graph

6. (Optional) Enable delegated access — If your organization uses Exchange mailbox delegation (Full Access or folder-level), set delegatedAccessScan to full_access_only or granular_access in your Helm values. Both users (delegate and owner) must connect their accounts for delegated search to work. See Configuration — DELEGATED_ACCESS_SCAN.

Scaling Considerations

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

Documentation