Unique AI Documentation

Outlook Semantic MCP - Permissions

4 min read

All permissions are Delegated (not Application), meaning they act on behalf of the signed-in user and can only access data that user has access to.

Permission Summary

Permission

Type

Admin Consent

Required

Purpose

User.Read

Delegated

No

Yes

Resolve user identity and profile

Mail.ReadWrite

Delegated

No

Yes

Read emails for sync and search; create draft emails in the user's mailbox

Mail.ReadWrite.Shared

Delegated

No

Yes (requested unconditionally; only used when DELEGATED_ACCESS_SCAN is enabled)

Read emails and create drafts in mailboxes the user has been granted delegated access to via Exchange admin

MailboxSettings.Read

Delegated

No

Yes

Read mailbox settings and folder structure

People.Read

Delegated

No

Yes

Look up contacts and people for address resolution

Calendars.ReadWrite.Shared

Delegated

No

Only when CALENDAR_INTEGRATION=enabled

List calendars and read/write events, including calendars shared with the user

offline_access

Delegated

No

Yes

Obtain refresh tokens for background sync

No permission the server requests requires admin consent, calendar included — Calendars.ReadWrite.Shared is user-consentable, same as Mail.ReadWrite.Shared. Users can connect their own accounts without IT intervention.

Admin involvement is still needed in two cases: the tenant has disabled user consent for applications (a tenant-wide policy, not a property of these scopes), or the admin wants to pre-grant consent organisation-wide so users never see the consent screen. Independently of consent, Calendars.ReadWrite.Shared must be registered on the Entra app (Terraform calendar_integration = "enabled") before CALENDAR_INTEGRATION=enabled, otherwise token refresh requests a scope the app does not expose.

All permissions are standard Microsoft delegated consent, not Outlook Semantic MCP specific. Users can connect independently for both mail and calendar. Admins can optionally pre-grant consent organisation-wide, and must grant it if the tenant disables user consent for applications.

For the full consent flow explanation including admin consent and multi-tenant setup, see Authentication — Understanding Consent Flows.

Least-Privilege Justification

Each permission is the minimum required for its function. No narrower alternative exists.

User.Read

Aspect

Detail

Purpose

Retrieve the signed-in user's profile (ID, email, display name)

Used For

Identifying the user when storing tokens and creating Graph subscriptions

Why Not Less

This is the minimum permission to read any user data

Why Not User.ReadBasic.All

That permission reads other users; we only need the signed-in user

Mail.ReadWrite

Aspect

Detail

Purpose

Read and create email messages in the user's mailbox

Used For

Fetching email bodies, headers, and metadata during full sync and live catch-up; creating draft emails via the create_draft_email tool (POST /me/messages)

Why Not Mail.Read + Mail.ReadWrite

Mail.ReadWrite already includes full read access, making Mail.Read and Mail.ReadBasic redundant

Why Not Mail.Send

The server only creates drafts — sending is a deliberate user action in Outlook. Mail.Send is not requested.

Mail.ReadWrite.Shared

Aspect

Detail

Purpose

Access delegated mailboxes the user has been granted access to via Exchange admin

Used For

Powering delegated mailbox discovery and search via /users/{ownerEmail}/messages and /users/{ownerEmail}/mailFolders when DELEGATED_ACCESS_SCAN is enabled

Why Not Less

No narrower delegated-shared permission exists for read and draft access on a delegated mailbox

Note

This scope is requested unconditionally at OAuth time even when DELEGATED_ACCESS_SCAN=disabled — the consent screen always lists it, but the permission is only exercised when delegated access is configured

MailboxSettings.Read

Aspect

Detail

Purpose

Read mailbox configuration and folder structure settings

Used For

Reading the user's mail folder hierarchy for directory sync and list_folders tool

Why Not Less

No narrower permission covers folder structure access

Why Not MailboxSettings.ReadWrite

The server never modifies mailbox settings

People.Read

Aspect

Detail

Purpose

Read the user's relevant people list (contacts, colleagues, frequent contacts)

Used For

The lookup_contacts tool — searching for email addresses and display names for draft recipients

Why Not Less

This is the minimum permission for the People API

Why Not Contacts.Read

People.Read provides the Microsoft People API which returns a richer relevance-ranked result set. Contacts.Read only covers the Contacts folder, not the full people graph.

Calendars.ReadWrite.Shared

Aspect

Detail

Purpose

Read and write the signed-in user's calendars, including calendars shared with them

Used For

Calendar tools (list_calendars, search_calendar_events, check_availability, suggest_meeting_times, respond_to_invite, create_event, update_event, cancel_event). Live Graph query-through; no calendar ingest

Why Not Calendars.Read

Writes (create/update/respond/cancel) need write. Calendars.ReadWrite does not cover calendars shared with the user

Note

Requested at OAuth time only when CALENDAR_INTEGRATION=enabled. The Entra app registers the scope only when Terraform calendar_integration = "enabled". Unlike Mail.ReadWrite.Shared, this is not on the mail-only consent screen

offline_access

Aspect

Detail

Purpose

Obtain refresh tokens for long-lived sessions

Used For

Refreshing expired Microsoft access tokens without user re-authentication

Why Required

Without this, users would need to re-authenticate every ~1 hour when access tokens expire (Microsoft limit, not configurable), interrupting background email sync

Why Delegated (Not Application) Permissions

Factor

Delegated (used)

Application (not used)

User involvement

User signs in and consents

No user; admin pre-configures

Data access scope

Only the signed-in user's data

All users' data in tenant

Setup requirement

None (self-service)

Admin creates Application Access Policies via PowerShell

Least privilege

Yes — user controls their own data

No — broad tenant access

The MCP model requires self-service user connections where each user:

  1. Connects their own account

  2. Controls what data they share

  3. Can permanently delete their synced inbox data at any time via delete_inbox_data

Application permissions would require tenant administrators to create Application Access Policies for each user via PowerShell — impractical for self-service MCP connections. See Microsoft Entra ID - Authentication flows for details.

OIDC Scopes

In addition to the Graph permissions above, the OAuth flow also requests the standard OIDC scopes openid, profile, and email. These are not Microsoft Graph permissions — they are used to obtain the user's identity (ID token) during sign-in and are not subject to admin consent.

Last updated