Skip to content
Leverage AI Developer Support

Microsoft Contacts Connector

Use this page when you need the Microsoft-side setup details for the Microsoft Contacts connector. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

Section titled “Runtime Shape”
  • Implemented modes: fixed live
  • Auth binding: Better Auth generic OAuth provider id microsoft
  • Callback URI examples:
    • http://localhost:3001/api/auth/oauth2/callback/microsoft
    • https://auth.example.com/api/auth/oauth2/callback/microsoft
  • Setup console URL:
  • Required connector scopes:
    • People.Read
    • Contacts.Read

Provider-Specific Gotchas

Section titled “Provider-Specific Gotchas”
  • Microsoft Contacts is a separate connector key: microsoft-contacts. Do not reuse, rename, or broaden the existing outlook mail connector.
  • The runtime uses Microsoft Graph Search API POST /v1.0/search/query with entityTypes: ["person"] for focused people search, because Microsoft directs future people-search investment toward Search rather than /people.
  • Broad saved-contact list prompts use Microsoft Graph /me/contacts with delegated Contacts.Read.
  • Microsoft Search person results are relevance-ranked people/contact results, not a complete tenant directory dump. Custom sort and aggregation are not supported for person.
  • The connector uses delegated People.Read and Contacts.Read. Do not add User.ReadBasic.All, stronger directory scopes, or application permissions unless the product explicitly accepts the added semantics and admin-consent/privacy model.
  • Microsoft Contacts, Outlook, and OneDrive share the same connector auth binding. Reauthorization under an existing linked microsoft account requests the full scope set needed by sibling Microsoft connectors under that account.
  • Contact grounding must preserve Microsoft source semantics: /me/contacts results are saved-contact, Graph Search results may be directory-person, organization-contact, saved-contact, or relevant-person depending on provider metadata.

Canonical Sources

Section titled “Canonical Sources”
  • packages/domain/src/connectors/connectorRegistry.ts
  • apps/auth/src/genericOAuthProviders.ts
  • apps/api/src/mastra/tools/microsoftContactsLiveQuery.ts
  • apps/api/src/connectors/liveAccessContactContracts.ts
  • docs/features/connectors/spec.md
  • docs/features/live-query/spec.md

Official Docs

Section titled “Official Docs”