Microsoft 365

Cosmo's Microsoft 365 integration gives you access to your mail, calendar, files (OneDrive and SharePoint), and Teams conversations directly through the Microsoft Graph API. Access is read-only except for mail drafting: Cosmo can create draft emails in your Drafts folder, but it never sends mail, and it cannot modify your calendar or files. It runs as a secure local MCP process — the same pattern as Google Drive, Notion, and ClickUp — and requires no Azure portal changes beyond a standard Entra app registration.

Unlike most integrations, Microsoft 365 has a two-step gate:

1. one-time org-level admin consent
2. per-member personal sign-in

After setup, each member can only access their own Microsoft 365 data.

What Cosmo can access

All access is delegated (scoped to the signed-in user). Every scope is read-only except Mail.ReadWrite, which lets Cosmo create email drafts. Cosmo does not request a send-mail scope, so it can never send email on your behalf — a draft always requires you to review and send it from Outlook.

The only write capability is draft creation in your own mailbox. Cosmo cannot send mail, delete mail, modify calendar events, or modify files — those scopes are not requested.

Setup: two steps

Step 1 — Admin consent (one time, per organization)

A Microsoft Entra Global Administrator or Application Administrator needs to grant tenant-wide consent. This is Microsoft's standard enterprise pattern — it authorizes the app identity once, then individual users can sign in with their own accounts.

From Cosmo's Integrations screen:

1. Click Connect Microsoft 365.
2. If your organization has not granted consent yet:
   • Cosmo org OWNER or ADMIN can start consent and open Microsoft's admin-consent page.
   • Members without org admin role are blocked and prompted to ask an org admin to connect first.
3. The consenting Microsoft account must have tenant admin rights in Entra (Global Admin or Application Admin).
4. After approval, Cosmo records the tenant consent and unlocks per-user sign-in for all members in the org.

Admin consent is recorded once per Entra tenant. You don't need to redo it when new members join.

Step 2 — Personal sign-in (each member, once)

Once consent is in place, every member signs in individually:

1. Return to the Integrations screen.
2. Click Connect Microsoft 365.
3. A Microsoft sign-in window opens. Authenticate with your work account.
4. Cosmo stores your access and refresh tokens securely, scoped to your user.

Your credentials are isolated: a teammate's Cosmo session cannot read your mailbox.

What you can do

Once connected, ask Cosmo in natural language — it picks the right Graph tool.

Drafting email

Cosmo can compose a draft and save it to your Outlook Drafts folder for you to review and send:

"Draft a reply to the Q3 planning thread summarizing our three open action items, cc my manager."

• The draft is created via Mail.ReadWrite — Cosmo never sends it. Open Outlook to review and send.
• Body format is auto-detected (plain text vs HTML); you can force it. Recipient addresses are validated and capped.
• Requires the Mail.ReadWrite consent (see the upgrade note under What Cosmo can access).

SharePoint & OneDrive files

Cosmo can browse and read documents across OneDrive and SharePoint document libraries:

"Find the SharePoint site for Marketing and list the files in its Brand Assets library."

• list_sharepoint_sites — find sites you have access to by name.
• list_sharepoint_drives — list document libraries in a site.
• list_files / search_files / read_file — work against OneDrive by default, or a SharePoint library when given a drive_id.

All file access is read-only.

Self-hosted Checklist (Org Admin)

If you run your own Cosmo API, verify your Entra app registration uses this exact callback URL:

https://<COSMO_API_URL>/api/v1/microsoft-365/admin-consent/callback

If it does not match exactly, Microsoft returns AADSTS50011.

Also ensure your server has Microsoft OAuth env vars configured (COSMO_MICROSOFT_CLIENT_ID and COSMO_MICROSOFT_CLIENT_SECRET).

What to ask your admin for

If you're not a tenant admin, paste this into an email or Slack message:

Hey — I'd like to connect Cosmo to our Microsoft 365 tenant so I can ask it about my mail, calendar, and files. It needs one-time admin consent from a tenant admin (Global Admin or Application Admin).

• Scopes are read-only except mail drafting: User.Read, Mail.ReadWrite (read + create drafts, no send), Calendars.Read, Files.Read.All, Sites.Read.All, Chat.Read, ChannelMessage.Read.All, Team.ReadBasic.All.
• After you approve, each user signs in individually — you're not granting access to other people's data, just allowing them to grant it themselves.
• You can revoke consent anytime from Entra → Enterprise Applications → Cosmo.

Privacy & data handling

• Per-user isolation. Each member's tokens and data are scoped to their own Microsoft account. Cosmo does not aggregate mail or files across users unless you explicitly share output (e.g. paste a summary into a shared workspace).
• Minimal write surface. The only write scope is Mail.ReadWrite, used solely to save drafts to your own Drafts folder. There is no send-mail, calendar-write, or file-write scope, so Cosmo cannot send mail or mutate calendar/file data. Revocation is enforced by Microsoft, not just Cosmo.
• Token handling. Access and refresh tokens are stored as connector credentials on the Cosmo server and refreshed server-side when needed.
• Data path. At chat time, the desktop app spawns a local cosmo-mcp-microsoft-365 process that calls Microsoft Graph on your behalf using your delegated token. No data transits any Microsoft-hosted MCP endpoint.

Troubleshooting

"Admin consent required" appears for me even after my admin approved. Wait ~30 seconds and refresh. Entra propagation can take a moment. If it persists, sign out of Cosmo and back in so your session reflects the new org-level consent.

"Microsoft 365 requires one-time setup by an org admin" appears. Your Cosmo user is not an org OWNER or ADMIN, or your org has not completed consent yet. Ask an org admin to connect Microsoft 365 first.

"AADSTS65004: User declined to consent" or similar. Your admin either cancelled or doesn't have permission to grant tenant-wide consent. Ask a Global Admin or Application Admin to retry.

"AADSTS50011: redirect URI does not match" appears. Ensure the Entra app redirect URI exactly matches your Cosmo API callback: https://<COSMO_API_URL>/api/v1/microsoft-365/admin-consent/callback

My mailbox is empty in Cosmo responses but works in Outlook. Conditional access policies (e.g. device compliance, location restrictions) may be blocking the app. Ask your admin to check the sign-in logs in Entra for the Cosmo app.

I'm on a GCC High / DoD tenant. The Microsoft Graph API is available on GCC High and DoD clouds. Contact support — we can configure the alternate Graph endpoints on request.

Revoking access

• As a member: remove the Microsoft 365 connector from Cosmo's Integrations screen. Your tokens are deleted immediately and cached data is purged.
• As an admin: revoke tenant consent at Entra → Enterprise Applications → Cosmo → Properties → Delete, or use Permissions → Revoke admin consent. Existing member tokens will fail on next refresh after tenant consent is revoked.