Outlook Semantic MCP – Features

This page describes user-facing features of the Outlook Semantic MCP Server: what is supported, what is not, and any setup required. For per-tool input/output reference, see Tools. For environment variables and deployment configuration, see Configuration.

Deployment modes

The MCP server operates in two modes controlled by the MCP_BACKEND environment variable. Several features behave differently depending on which mode is active:

Where a feature works the same in both modes, this page says so once. Where behaviour differs, Mode A and Mode B are called out separately.

Email Search

Mode A (microsoft_graph_and_unique_api)

• search_emails runs semantic search against the Unique knowledge base and a KQL keyword search against Microsoft Graph simultaneously, then merges and deduplicates results.

• Folder filtering is supported: pass folder IDs (from list_mailboxes_and_directories) or well-known folder names (e.g. Inbox) to narrow results to a specific folder.

• A syncWarning is returned while the initial full sync is still in progress — results may be incomplete until it finishes.

Mode B (microsoft_graph)

• search_emails queries Microsoft Graph directly using KQL keyword search only. No knowledge base interaction occurs.

• Folder filtering is supported via the directories field on each msGraphKeywordSearchQueries entry. Pass a well-known folder name (e.g. Inbox) or a folder ID from list_mailboxes_and_directories. This works for the user's own mailbox and for fully delegated mailboxes (Full Access).

• Search is not supported for mailboxes where the user only has folder-level (partial) access — Microsoft Graph requires full mailbox access for $search queries. See Known limitations below.

What's not supported (both modes)

• Task or file data — only mail is in scope here. Calendar is a separate, flag-gated live Graph path; see Calendar.

See also:Tools — search_emails

Draft Creation

Available in both modes. Behaviour is identical.

What's supported

• Create draft emails in the signed-in user's Drafts folder via create_draft_email, with subject, body, recipients (To, CC, BCC), and attachments.

• The draft is not sent automatically — the tool response includes a webLink for the user to open and send from Outlook.

• Attachments can be provided as base64-encoded data URIs or Unique content URIs (cluster-local mode only).

What's not supported

• Sending email directly from the MCP — drafts must be sent manually by the user.

• Creating drafts in another user's mailbox (delegated or otherwise).

See also:Tools — create_draft_email

Contact Resolution

Available in both modes. Behaviour is identical.

What's supported

• Look up contacts in the signed-in user's Microsoft contacts directory via lookup_contacts.

• Returns display names and email addresses for address resolution.

What's not supported

• Organisation-wide directory queries beyond what the People.Read scope exposes. If a contact is not in the signed-in user's personal contacts or the People API result set, it will not appear.

See also:Tools — lookup_contacts

Mailbox & Folder Listing

Mode A (microsoft_graph_and_unique_api)

• List own mailboxes and their full folder tree via list_mailboxes_and_directories.

• When DELEGATED_ACCESS_SCAN is enabled, delegated mailboxes also appear alongside the user's own (marked with isOwn: false).

• Folder IDs returned by this tool can be passed to search_emails to narrow results to a specific folder.

Mode B (microsoft_graph)

• list_mailboxes_and_directories is available and returns the user's own folder tree plus any fully delegated mailboxes. Folder IDs returned here can be passed to the directories field of msGraphKeywordSearchQueries in search_emails to narrow results to a specific folder.

What's not supported

• Searching in mailboxes where the user only has folder-level (partial) access in Mode B — Microsoft Graph does not support $search against such mailboxes. See Known limitations below.

See also:Tools — list_mailboxes_and_directories

Delegated Access

Delegated access lets a user ("the delegate") search another user's mailbox ("the owner") when Microsoft Exchange has granted them access. The MCP server detects these relationships automatically via background scans controlled by DELEGATED_ACCESS_SCAN — no per-user configuration is needed beyond enabling that setting.

For ordinary user mailboxes, both the owner and the delegate must have connected the MCP — if the owner has not signed in, there is nothing to discover or search. Shared mailboxes listed in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS may also sign in; if they have not, only the delegates need to connect. When they have signed in, the mailbox's own token is the primary credential and Full Access delegates are the backup.

What's supported

Four delegation configurations are supported:

1. Exchange admin grants Full Access (Read & Manage) — an Exchange administrator grants a user Full Access to another user's mailbox via the Exchange admin center or PowerShell. The delegate can search the owner's entire mailbox. Supported in both Mode A and Mode B — configure DELEGATED_ACCESS_SCAN=full_access_only (or granular_access) to enable scanning.

2. User shares specific folders via Outlook desktop — a user shares individual folders (e.g. Inbox, RFQ) with another user directly from Outlook desktop, without Exchange admin involvement. Mode A only — requires DELEGATED_ACCESS_SCAN=granular_access. See Setup — User shares specific folders for the required root-mailbox visibility step.

3. Microsoft 365 shared mailbox with no sign-in — a typical shared mailbox that has no login of its own. List its address in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS. Delegates with Full Access can search it. See Setup — Shared mailboxes.

4. Sign-in-eligible mailbox used as a shared inbox — a normal user mailbox (or a shared mailbox that has sign-in enabled) that several people use. List it in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS. Users may also sign in to it during MCP authorization: the mailbox's own token is then primary and Full Access delegates are the backup. See Setup — Shared mailboxes.

What's not supported

• Application-permission based access — the MCP uses delegated permissions only (acting on behalf of a signed-in user). It does not support application-level access to mailboxes.

• Access paths not visible via the Microsoft Graph API — only access detectable via the Graph messages or mailFolders endpoints is supported. Access paths that bypass these endpoints (e.g. internal APIs used by Outlook desktop) are not visible to the MCP.

• Detecting access for users who have not connected the MCP — for ordinary user mailboxes, both the owner and the delegate must be connected. Shared mailboxes listed in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS may also sign in; if they have not, only the delegates must be connected.

• Folder-level access in Mode B — granular_access requires Mode A. In Mode B, only delegates with full mailbox access can search delegated mailboxes.

• Folder-level access on env-listed shared mailboxes — shared-mailbox profiles are discovered with Full Access only (/messages). Grant Full Access to every user who needs to search them.

Setup

1. Exchange admin grants Full Access

Use this path when an IT administrator needs to grant a user access to another user's entire mailbox.

Option A — Exchange admin center (GUI)

1. Open the Microsoft 365 admin center and navigate to Exchange admin center.

2. Go to Recipients → Mailboxes and select the target mailbox (the owner whose mailbox the delegate needs to access).

3. Open the Delegation tab (or Mailbox delegation in older versions).

4. Under Full Access, click Edit (or +) and add the delegate user.

5. Leave Auto-mapping enabled (recommended) so the mailbox appears automatically in Outlook. Click Save.

Option B — PowerShell

Add-MailboxPermission `
  -Identity "owner@example.com" `
  -User "delegate@example.com" `
  -AccessRights FullAccess `
  -InheritanceType All

Detection: Once granted, the delegate is detected on the next DELEGATED_ACCESS_DISCOVERY_CRON_SCHEDULE run (default: every 12 hours). Configure DELEGATED_ACCESS_SCAN=full_access_only (or granular_access) to enable scanning.

2. User shares specific folders (no admin needed)

Use this path when a user wants to share individual folders with a colleague without involving an Exchange administrator. Requires DELEGATED_ACCESS_SCAN=granular_access and Mode A (microsoft_graph_and_unique_api).

Step 1 — Share individual folders

1. In Outlook desktop, right-click the folder you want to share (e.g. Inbox).

2. Select Properties → Permissions tab (or Folder Permissions).

3. Click Add, search for and select the delegate user.

4. Choose an appropriate permission level (e.g. Reviewer for read-only access).

5. Click OK.

Important — mailbox root visibility (required)

After sharing individual folders, you must also grant the delegate visibility on the mailbox root — the item at the very top of your folder tree that shows your name or email address, above all folders including Inbox.

Right-click the mailbox root (your name/email at the top of the folder list, not the Inbox folder), choose Sharing Permissions or Folder Permissions, add the delegate, and set the permission level to None with Folder visible checked (sometimes labelled as a non-editing owner role, depending on your Outlook version).

Without this step, the MCP cannot enumerate the shared folders via Microsoft Graph — even though Outlook desktop may still display them (Outlook uses internal APIs that bypass the Graph endpoint the MCP relies on).

Important — full path visibility for nested folders

Every folder on the path from the mailbox root to the shared folder must have Folder visible granted to the delegate. For example, if you are sharing Inbox → Clients → Contoso → Invoices, then Inbox, Clients, and Contoso must each have Folder visible granted, in addition to whatever read permission is set on Invoices.

Without an unbroken visibility chain, Microsoft Graph cannot traverse the folder hierarchy to reach the target folder, so it remains invisible to the MCP — even though Outlook desktop may show it (Outlook uses internal shortcuts that do not require an unbroken chain). This is a silent failure mode that only surfaces in the MCP.

Detection: Folder-level access is picked up on the next DELEGATED_ACCESS_VERIFICATION_CRON_SCHEDULE run (default: every 4 hours) and only in granular_access mode. The full_access_only mode does not detect folder-level shares.

3. Shared mailboxes

Two mailbox types are supported. Pick the path that matches how the mailbox is set up in Microsoft 365.

Type 1 — Microsoft 365 shared mailbox with no sign-in. This is the usual shared mailbox: it has no password and nobody logs into it. Register it with the MCP by listing its address in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS.

Type 2 — Sign-in-eligible mailbox used as a shared inbox. A normal user mailbox, or a shared mailbox that has sign-in enabled. List it in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS. Completing MCP authorization as that account is optional and supported: the mailbox's own token becomes the primary credential and Full Access delegates remain the backup. If nobody signs in, it behaves like type 1.

Setup for type 1 and type 2 (env-listed):

1. Set DELEGATED_ACCESS_SCAN to full_access_only or granular_access.

2. Set DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS to a comma-separated list of mailbox addresses (Helm: mcpConfig.delegatedAccess.sharedMailboxEmails).

3. Grant Full Access to every user who needs to search the mailbox, using Exchange admin center or PowerShell (see Step 1 above).

4. Those users connect their own MCP accounts. The shared mailbox itself may also sign in; if it does not, ingest and Graph calls run as a Full Access delegate.

5. Wait for shared-mailbox sync (startup, or DELEGATED_ACCESS_SHARED_MAILBOX_SYNC_CRON_SCHEDULE, default every 6 hours) and then for delegated-access discovery. Discovery and Mode A ingest address the mailbox as /users/{shared-mailbox}/…. When the mailbox has signed in, its own token is tried first; on 401/403 the call rotates to a Full Access delegate.

If you later remove an address from the env list, a mailbox that had signed in stays as a normal OAuth user and ingested shared-mailbox content is deleted. A mailbox that never signed in is removed entirely.

Behavior

For a detailed description of how delegated access works at runtime, see the existing FAQ entries:

• Who has access to a shared inbox? — detection, both modes

• What happens with delegated access? — search behavior, ingestion scope, folder filtering

• When shared inbox access is revoked, are previously ingested emails still accessible? — revocation detection timing

Quick reference:

Configure scanning via DELEGATED_ACCESS_SCAN.

Calendar

Both modes, only when CALENDAR_INTEGRATION is enabled.

Live query-through to Microsoft Graph. No calendar ingest, webhooks, or calendar tables. The tools are list_calendars, search_calendar_events, check_availability, suggest_meeting_times, respond_to_invite, create_event, update_event, and cancel_event.

What's supported

• List own calendars and calendars shared with the signed-in user (that they accepted). Holiday and birthday calendars appear in the list — skip those by name.

• Search events in a time window. Relative ranges (today, thisWeek, nextWeek, next7Days, …) resolve in the mailbox timezone. Weeks start Monday. Each result includes the full plain-text body (Graph already converted; may be truncated).

• Free/busy (check_availability) and ranked slot suggestions (suggest_meeting_times).

• Create, update, cancel, and respond to invitations. Writes have no draft state. respond_to_invite notifies the organizer immediately. create_event, update_event, and cancel_event wait for Accept / Decline on the prompt, then notify attendees. cancel_event is not a silent delete. create_event / update_event body is an HTML fragment sent to Graph unchanged (not Markdown). Search still returns plain text.

• Shared calendars. A shared calendar is owned by somebody else but stored in the caller's mailbox, so it resolves under /me like any other calendar — ownerEmail is who it belongs to. Pass calendarRef / eventRef from list/search unchanged.

What's not supported yet

• All-day create/update.

• Mail-invite fusion (finding meetings by searching invite emails).

• Calendar tools on shared-mailbox profiles (those profiles are ingestion-only).

Setup

Enablement is operator-side: Entra admin consent for Calendars.ReadWrite.Shared first, then CALENDAR_INTEGRATION=enabled. Existing users must reconnect Outlook after the flag is turned on (unless tenant admin consent already covers that scope). reconnect_inbox only renews the mail webhook — it does not re-run OAuth. If a tool returns consentRequired: true, the user must reconnect Outlook; do not send them to /auth/authorize.

See also:Tools — Calendar — Configuration — CALENDAR_INTEGRATION

Known Limitations

Search does not work for mailboxes where a colleague shared folders without granting Full Access (Mode B only)

Symptom: When a colleague has shared one or more folders with you (but has not granted you Full Access to their entire mailbox), search_emails in Mode B returns no results from that mailbox and the response includes a message such as:

Could not search in mailbox colleague@example.com — Microsoft does not offer an API to search in shared folders from this mailbox.

Cause: Microsoft Graph requires full mailbox access for $search queries. When a user shares only individual folders, Microsoft Graph returns HTTP 403 to any search request against that mailbox — regardless of whether a specific folder is targeted or not. There is no Microsoft Graph API that supports keyword search scoped to a partially-delegated mailbox.

Workaround options:

• Get Full Access. Ask your colleague (or an Exchange administrator) to grant you Full Access (Read & Manage) to their mailbox. This allows $search queries against the entire mailbox, including the previously shared folders.

• Use a shared mailbox. Convert the colleague's mailbox to a Microsoft 365 shared mailbox, list it in DELEGATED_ACCESS_SHARED_MAILBOX_EMAILS, and grant Full Access to everyone who needs to search it. See Setup — Shared mailboxes.