Outlook Semantic MCP - Operator Manual

Overview

This guide provides IT operators with the technical information needed to deploy, configure, and maintain the Outlook Semantic MCP Server.

Note: The Outlook Semantic MCP Server is a semantic MCP server. It exposes MCP tools that allow AI assistants to search and retrieve email content. In MicrosoftGraphAndUniqueApi 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 MicrosoftGraph mode, no ingestion runs — emails are queried live from Microsoft Graph.

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

Deployment Modes

The server supports two deployment modes set via MCP_BACKEND. Choose your mode before following any other step in this guide — prerequisites, configuration, and verification differ by mode.

See Configuration — MCP_BACKEND for details.

Documentation

Architecture Overview

The diagram below shows the full Mode A (MicrosoftGraphAndUniqueApi) topology. In Mode B (MicrosoftGraph), all infrastructure components are identical but the ingestion arrows to the Unique Knowledge Base are inactive — no email content is ingested.

The Outlook Semantic MCP Server runs as a single pod that handles MCP tool requests, receives Microsoft Graph webhook notifications, processes email via RabbitMQ consumers, stores state in PostgreSQL, and ingests email content into the Unique knowledge base.

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 MCP_BACKEND for the full trade-offs:

• MicrosoftGraph — live KQL search directly against Microsoft Graph; no email ingestion into Unique KB; lighter deployment

• MicrosoftGraphAndUniqueApi(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

• fullAccessOnly — Full Access (Read & Manage) grants via Exchange admin

• granularAccess — folder-level grants (e.g. shared Inbox or RFQ folder); subsumes fullAccessOnly

Unique will provide you with the MCP server endpoint URL once the deployment is ready.

Self-Hosted

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

Mode A: MicrosoftGraphAndUniqueApi

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 with the KB_Admin role in Zitadel. Required for both cluster_local and external auth modes. See Zitadel Service Account.

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 minimal values.yaml with your secrets, Microsoft client ID, and Unique API endpoints. See Configuration Guide.

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

7. Verify the deployment is working:

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

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

10. Call verify_inbox_connection to confirm the webhook subscription is active

11. Send a test email to the connected account, wait a moment, then use search_emails to confirm it appears

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

Mode B: MicrosoftGraph

1. Register Microsoft Entra ID application — same as Mode A. See Authentication Guide.

2. Provision infrastructure — PostgreSQL 17+, RabbitMQ 4+, and Unique Knowledge Base (all three are required, same as Mode A). See Deployment — Prerequisites.

3. Create Kubernetes secrets — same as Mode A. UNIQUE_ZITADEL_CLIENT_SECRET is only needed when using external service auth mode.

4. Configure Helm values — set mcpConfig.app.mcpBackend: MicrosoftGraph. Include mcpConfig.unique (required). Omit mcpConfig.ingestion entirely. See Mode B Minimal Values Example.

5. Deploy with Helm — same command as Mode A. See Deployment — Install.

6. Verify the deployment is working:

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

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

9. Call search_emails with a simple KQL query to confirm it returns results from Microsoft Graph.

Infrastructure Requirements

See Deployment — Prerequisites for the full infrastructure requirements and version details.

Deployment Checklist

1. Infrastructure

1. Microsoft Entra ID

1. Application

1. Verification

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.

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.