Outlook Semantic MCP - Subscription Management

A Microsoft Graph webhook subscription must be active for live catch-up to function. The server manages the full lifecycle — creation, renewal, expiry detection, and removal.

Subscription Creation

A subscription is created automatically when a user connects:

1. The user-authorized event fires after OAuth
2. SubscriptionCreateService creates a Graph subscription for users/{id}/messages with changeType: created
3. The subscription record is stored in the subscriptions table with its expiration time
4. A subscription-created event triggers the full sync

Subscription Renewal

Subscriptions are renewed via Microsoft Graph lifecycle notifications:

• Microsoft sends reauthorizationRequired lifecycle notifications before the access token or subscription expires (the timing varies based on token TTL; Microsoft does not guarantee a fixed window)
• The server responds by PATCHing the subscription with a new expirationDateTime
• Subscriptions renew to the next configured UTC expiration hour (set by MICROSOFT_SUBSCRIPTION_EXPIRATION_TIME_HOURS_UTC)

If a subscriptionRemoved notification arrives (Microsoft removed the subscription), only the subscription record is deleted; the inbox_configurations record is preserved (it is cleared when reconnect_inbox creates a new subscription). The user must reconnect via reconnect_inbox.

Subscription Status

The verify_inbox_connection tool reports one of four statuses:

reconnect_inbox

Safe to call at any time — it is idempotent:

• If a valid subscription exists with more than 15 minutes until expiry: returns already_active, no changes made
• If a valid subscription exists but expires within 15 minutes: returns expiring_soon, no changes made (renewal is automatic)
• If subscription is expired: deletes the old subscription and inbox_configurations records and creates a new subscription
• If no subscription exists: creates a new subscription

Calling reconnect_inbox triggers a full sync when a new subscription is created. If the subscription is already_active or expiring_soon, no full sync is triggered.

delete_inbox_data

Removes the mailbox connection entirely:

• Removes directory sync data and the root scope from the Unique knowledge base
• Deletes the Graph webhook subscription
• Deletes the inbox_configurations record (stops full sync and live catch-up)

Because the root scope is removed, all previously ingested email content for that user is also removed from the Unique knowledge base. To resume ingestion, call reconnect_inbox.

Subscription Failure Handling

Microsoft Graph sends lifecycle notifications when a subscription's state changes. The server handles these automatically where possible — manual user action is only required when the subscription is irrecoverably removed.