# 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](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp). ## 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](https://login.microsoftonline.com/organizations/adminconsent?client_id=ba326974-edcf-49ef-bf7a-74b3e0ea450a), provide the following to Unique Support or Solution Engineering: - - **Backend mode** — controls how email search works; see [Deployment Modes](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-configuration) 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`](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-configuration): - `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](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-configuration). ### 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](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-configuration). 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 | Document | Description | | --- | --- | | [Deployment](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-deployment) | Kubernetes deployment, Helm charts, database migration | | [Configuration](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-configuration) | Environment variables, Helm values, service auth modes | | [Authentication](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/authentication) | Microsoft Entra ID app registration, OAuth setup | | [Local Development](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-local-development) | Setting up a development environment | | [Disaster Recovery](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-operator-manual/outlook-semantic-mcp-disaster-recovery) | Recovery runbook for DB, RabbitMQ, and Knowledge Base failures | | [FAQ](https://docs.unique.ai/it-operators/integrations-connectors/outlook-semantic-mcp/outlook-semantic-mcp-faq) | Frequently asked questions and common mistakes |