Microsoft 365 Graph
Read mail and Teams chats through the built-in Microsoft 365 Graph MCP server, and choose which AI agents can send
An agent with Microsoft 365 Graph can read mail, calendars, and Teams chats, but it can also send mail and Teams messages, change inbox rules, and delete messages. It needs no Microsoft 365 Copilot license. Adding Microsoft 365 Graph here puts each tool behind a policy rule and records each call in the audit log, so you decide which agents can send and delete and which can only read.
Credential modes
Microsoft 365 Graph supports bring your own app only. It does not support dynamic client registration, so your organization registers its own Entra app in Azure and supplies the client ID and secret. See Credential modes for how the modes compare.
Before you begin
- A Microsoft Entra admin able to register an application in your tenant, and to grant admin consent for it. Any user can register an app by default unless your tenant restricts this, but the consent step needs an admin.
- Administrator access to your Agent Authority workspace, to add the resource.
Setup moves between two consoles. You copy a redirect URI in the Agent Authority console, register an app in Microsoft Entra and grant consent, then return to the console and paste the credentials. Keep both tabs open as you work.
Two Entra settings needed before anyone can connect
Register the app for multiple tenants, in Register the
app, and grant admin consent, in Grant admin
consent. If AADSTS50194 appears when you or a user
connects, the app isn't set to multiple tenants. If AADSTS65001 appears,
admin consent hasn't been granted for every permission the connector requests.
Setup
1. Copy the redirect URI
In the Agent Authority console, go to Resources → Add Resource and select Microsoft 365 Graph. This resource is bring-your-own-app only, so the credentials form opens as soon as you select it, with no mode to pick.
Copy the Redirect URI shown on the form.
It includes your tenant's region, so copy it rather than typing it.
It takes the form https://oauth.aisecurity.services.<region>.connect.secureauth.com/auth/callback.
Leave this page open. You come back to it in step 4.
2. Register an Entra app in Azure
Sign in to portal.azure.com and go to Microsoft Entra ID → App registrations → New registration.
Register the app
Configure:
- Name – your preferred name, for example
<your-company> Agent Authority - Microsoft 365 Graph - Supported account types – Multiple Entra ID tenants, with Allow all tenants as the sub-option, which is the default.
Multi-tenant is required because the gateway's OAuth flow uses Microsoft's
/commonendpoint, which rejects a single-tenant app withAADSTS50194. - Redirect URI – choose the Web platform and paste the Redirect URI from the form in the Agent Authority console, using the Copy button next to it
Click Register.
Already registered the app for your tenant only?
Open the app in App registrations, go to Authentication, and change Supported account types to the multitenant option. The client ID stays the same, so nothing changes in the Agent Authority console.
Add the API permissions
On the new app's API permissions page, click Add a permission → Microsoft Graph → Delegated permissions, and add the scopes listed under Required scopes.
The three OpenID Connect scopes (offline_access, openid, profile) live under the OpenId permissions section near the bottom of the picker, which is easy to miss because they are not in the main alphabetical list.
Create a client secret
On Certificates & secrets, click New client secret and set an expiry. Copy the secret value immediately, because Microsoft only displays it once. This is your Client Secret.
Then copy the Application (client) ID from the app's Overview page. This is your Client ID.
3. Grant admin consent
On the API permissions page, click Grant admin consent for <your tenant> at the top of the permissions list.
Admin consent is required
Several of the Teams scopes can only be granted by an admin, so users can't
grant them when they connect. Until you grant admin consent, connecting fails
for you and your users with an AADSTS65001 consent error.
Admin consent covers the permissions the app lists when you grant it. When a release adds a tool that needs another permission, follow When new tools need new permissions.
4. Finish in the console
Back on the Microsoft 365 Graph form in the Agent Authority console, paste the Client ID and Client Secret. Leave Token Endpoint Authentication on Auto-detect. Then click Add.
The resource is added with all tools and scopes pre-configured, and an Admin setup required dialog appears with a Setup guide button linking back to this page.
When new tools need new permissions
Each time you or a user connects, the gateway asks Microsoft for every permission this connector's tools need, whatever your app registration lists. When a release adds a tool that needs a permission your app doesn't list, the next time you or a user connects, Microsoft shows a consent screen for it. A user who isn't allowed to consent sees an error telling them to ask an administrator.
To stop the consent screen for everyone:
- Compare the app's API permissions page with Required scopes, and add any that are missing.
- Click Grant admin consent for
<your tenant>again. - Ask each user to reconnect once, so their sign-in carries the new permissions.
An Entra admin can grant the same consent from the consent screen instead: connect through the gateway, select the option to consent on behalf of the whole organization, and accept. Microsoft shows that option only to admins allowed to grant consent for the whole organization.
Keep agents read-only
Leaving write permissions off your app registration doesn't keep agents read-only. The gateway still requests those permissions, and Microsoft asks users to consent to them. To keep agents from writing, use a policy instead: see Read-only access by policy tag in Policy examples. The token still carries write permissions, so the policy is what blocks the write calls.
Past permission changes
- Teams – 13 delegated scopes for Teams chats, channels, and teams. Until a connection is re-authenticated, the Teams tools don't appear on it.
- Microsoft To Do –
Tasks.ReadWrite. Until a user reconnects, To Do calls fail with a Microsoft Graph403error, because the user's token doesn't carry the new scope.
Verify the connection
The gateway syncs the Microsoft 365 tools automatically. To check the connection end to end, ask your agent to run a request:
Show my Microsoft 365 profileIf your name and email come back, the connection is working.
How users connect
Access is per user. Each additional user connects their own Microsoft 365 account the first time their agent calls a Microsoft 365 tool: the gateway returns a sign-in link, the user authorizes once, and the tools work from then on. Go to Connections to manage linked accounts.
Each call uses the signed-in user's own token, so Microsoft 365's own permissions control what they can reach. The gateway does not widen access beyond what the authenticated user could already do in Microsoft 365.
Connect to some upstreams only
Each group of tools is an upstream you can connect to on its own, which keeps an agent's tool list short.
Append ?upstreams= to the resource's gateway URL with one or more upstream IDs, separated by commas:
https://your-gateway-url/gateway/mcp/microsoft365-graph?upstreams=mail,calendarThe agent sees only the tools of the upstreams you list.
The upstream IDs are mail, calendar, teams, chats, contacts, onenote, meetings, files, people, search, profile, tasks, and uncategorized.
tasks holds the Microsoft To Do tools and uncategorized holds the rest.
An unknown ID returns 404.
In the connect dialog, pick this resource under Connect to, then pick one or more under Upstreams.
Available tools
All 157 tools ship with the catalog entry, so they appear in tool lists and policy pickers as soon as the resource is installed. Each is a direct pass-through to a Microsoft Graph operation, so the agent composes them the same way it would call Graph.
Mail – search & read
| Tool | Tags | Description |
|---|---|---|
list_messages | read-only | List messages in the mailbox, newest first; select/top/filter/search supported |
get_messages | read-only | Get a single message by ID |
list_mail_folders | read-only | List mail folders (Inbox, Drafts, Sent Items, and so on) |
list_mail_child_folders | read-only | List child folders of a mail folder |
list_mail_folder_messages | read-only | List messages within a specific mail folder |
Mail – drafts & sending
| Tool | Tags | Description |
|---|---|---|
create_draft | write | Create a draft message (send later with send_draft) |
send_draft | write, external | Send an existing draft by ID |
send_mail | write, external | Send a message directly |
reply_message | write, external | Reply to the sender; saved to Sent Items |
reply_all_message | write, external | Reply to all recipients; saved to Sent Items |
create_reply_draft | write | Create a draft reply to the sender, without sending it |
create_reply_all_draft | write | Create a draft reply to all recipients, without sending it |
forward_message | write, external | Forward a message to new recipients |
Mail – manage & organize
| Tool | Tags | Description |
|---|---|---|
update_message | write | Update a message by ID (mark read/unread, flag) |
delete_message | destructive | Delete a message by ID |
move_mail_message | write | Move a message to another folder |
create_mail_folder | write | Create a mail folder |
create_mail_child_folder | write | Create a child folder inside a mail folder |
update_mail_folder | write | Rename a mail folder |
delete_mail_folder | destructive | Delete a mail folder |
Mail – inbox rules
| Tool | Tags | Description |
|---|---|---|
list_mail_rules | read-only | List inbox message rules |
create_mail_rule | write, external | Create an inbox rule (conditions and actions) |
update_mail_rule | write, external | Update an inbox rule by ID |
delete_mail_rule | destructive | Delete an inbox rule by ID |
Mail – attachments
| Tool | Tags | Description |
|---|---|---|
list_attachments | read-only | List attachment metadata for a message |
get_attachment | read-only | Get a single attachment (includes base64 content for file attachments) |
add_attachment | write | Add an attachment to a message or draft (inline, under 3 MB) |
delete_attachment | destructive | Delete an attachment from a message by ID |
Calendar – events
| Tool | Tags | Description |
|---|---|---|
list_events | read-only | List event objects in the mailbox |
list_calendar_view | read-only | List events in a time range, with recurrences expanded |
get_events | read-only | Get a single event's properties |
create_events | write, external | Create an event |
update_event | write, external | Update an event by ID |
delete_event | destructive, external | Delete an event by ID |
cancel_event | destructive, external | Cancel an organized event, notifying attendees |
Calendar – invitations
| Tool | Tags | Description |
|---|---|---|
accept_event | write, external | Accept an event invitation |
decline_event | write, external | Decline an event invitation |
tentatively_accept_event | write, external | Tentatively accept an event invitation |
forward_event | write, external | Forward an event to additional recipients |
Calendar – calendars & scheduling
| Tool | Tags | Description |
|---|---|---|
list_calendars | read-only | List the user's calendars |
create_calendar | write | Create a secondary calendar |
update_calendar | write | Rename or recolor a calendar |
delete_calendar | destructive | Delete a calendar |
get_schedule | read-only | Get free/busy for one or more people over a window |
find_meeting_times | read-only | Suggest meeting times from attendee free/busy |
Contacts
| Tool | Tags | Description |
|---|---|---|
list_contacts | read-only | List personal contacts |
get_contact | read-only | Get a single contact by ID |
create_contact | write | Create a contact |
update_contact | write | Update a contact by ID |
delete_contact | destructive | Delete a contact by ID |
list_contact_folders | read-only | List contact folders |
create_contact_folder | write | Create a contact folder |
update_contact_folder | write | Rename a contact folder |
delete_contact_folder | destructive | Delete a contact folder |
list_contact_folder_child_folders | read-only | List child folders of a contact folder |
create_contact_child_folder | write | Create a child folder inside a contact folder |
create_contact_in_folder | write | Create a contact inside a specific folder |
list_folder_contacts | read-only | List contacts within a specific folder |
Teams meetings
| Tool | Tags | Description |
|---|---|---|
create_online_meeting | write | Create a Teams online meeting |
get_online_meeting | read-only | Get an online meeting by ID |
update_online_meeting | write | Update an online meeting by ID |
delete_online_meeting | destructive | Delete an online meeting by ID |
list_online_meetings | read-only | Find online meetings; filter by join URL to resolve an ID |
list_recordings | read-only | List recording metadata for an online meeting |
list_transcripts | read-only | List transcripts available for an online meeting |
get_transcript_content | read-only | Get a transcript's content (WebVTT) |
list_attendance_reports | read-only | List attendance reports for a meeting (one per session) |
list_attendance_records | read-only | List per-attendee attendance records for a report |
Teams – chats
| Tool | Tags | Description |
|---|---|---|
list_chats | read-only | List the chats the signed-in user is part of |
create_chat | write | Create a new one-on-one or group chat |
get_chat | read-only | Get a single chat by ID |
list_chat_members | read-only | List a chat's members |
list_chat_messages | read-only | List messages in a chat |
get_chat_message | read-only | Get a single message or reply from a chat |
send_chat_message | write, external | Send a message in a chat |
reply_to_chat_message | write, external | Reply to a message in a chat |
list_chat_message_replies | read-only | List replies to a chat message |
list_chat_message_hosted_contents | read-only | List hosted content (for example, inline images) on a chat message |
set_chat_message_reaction | write | Add a reaction to a chat message |
unset_chat_message_reaction | write | Remove a reaction from a chat message |
list_pinned_chat_messages | read-only | List messages pinned in a chat |
pin_chat_message | write | Pin a message in a chat |
unpin_chat_message | write | Unpin a message from a chat |
Teams – teams & channels
| Tool | Tags | Description |
|---|---|---|
list_joined_teams | read-only | List the teams the signed-in user has joined |
list_my_associated_teams | read-only | List teams the user is associated with, including shared-channel host teams |
get_team | read-only | Get a team by ID |
list_team_members | read-only | List a team's members |
list_team_channels | read-only | List a team's channels |
get_team_channel | read-only | Get a single channel by ID |
create_team_channel | write | Create a channel in a team |
update_team_channel | write | Update a channel's properties |
list_channel_messages | read-only | List messages in a channel |
get_channel_message | read-only | Get a single message from a channel |
send_channel_message | write, external | Send a message in a channel |
reply_to_channel_message | write, external | Reply to a message in a channel |
list_channel_message_replies | read-only | List replies to a channel message |
list_channel_message_hosted_contents | read-only | List hosted content on a channel message |
set_channel_message_reaction | write | Add a reaction to a channel message |
unset_channel_message_reaction | write | Remove a reaction from a channel message |
list_channel_tabs | read-only | List the tabs configured in a channel |
get_channel_files_folder | read-only | Get the drive folder backing a channel's Files tab |
list_my_installed_teams_apps | read-only | List Teams apps installed in the signed-in user's personal scope |
OneNote
| Tool | Tags | Description |
|---|---|---|
list_onenote_notebooks | read-only | List the user's OneNote notebooks |
create_onenote_notebook | write | Create a notebook |
get_onenote_notebook_from_web_url | read-only | Resolve a notebook from its web URL |
list_onenote_notebook_sections | read-only | List the sections in a notebook |
create_onenote_section | write | Create a section in a notebook |
list_all_onenote_sections | read-only | List all sections across notebooks |
list_onenote_section_groups | read-only | List section groups |
list_onenote_section_pages | read-only | List pages in a section |
list_onenote_pages | read-only | List all pages |
get_onenote_page_content | read-only | Get a page's HTML content |
delete_onenote_page | destructive | Delete a page by ID |
Microsoft To Do – lists & tasks
Start with list_todo_lists to find a list's ID, then pass it to the task tools.
Every user has a default Tasks list.
| Tool | Description |
|---|---|
list_todo_lists | List the user's task lists |
get_todo_list | Get a single task list by ID |
create_todo_list | Create a task list |
update_todo_list | Rename a task list |
delete_todo_list | Delete a task list and the tasks in it |
list_todo_tasks | List the tasks in a list, with status, importance, and due dates |
get_todo_task | Get a single task by ID |
create_todo_task | Create a task in a list |
update_todo_task | Update a task, for example to mark it completed or change its due date |
delete_todo_task | Delete a task by ID |
Microsoft To Do – checklist items, links & attachments
| Tool | Description |
|---|---|
list_todo_checklist_items | List a task's checklist items (subtasks) |
get_todo_checklist_item | Get a single checklist item by ID |
create_todo_checklist_item | Add a checklist item to a task |
update_todo_checklist_item | Check off or rename a checklist item |
delete_todo_checklist_item | Delete a checklist item |
list_todo_linked_resources | List a task's links back to its source item, such as an email |
get_todo_linked_resource | Get a single linked resource by ID |
create_todo_linked_resource | Link a task to an item in another app |
update_todo_linked_resource | Update a linked resource |
delete_todo_linked_resource | Delete a linked resource |
list_todo_attachments | List a task's file attachments |
get_todo_attachment | Get a single attachment, including its base64 content |
add_todo_attachment | Add a file attachment to a task (inline, under 3 MB) |
delete_todo_attachment | Delete an attachment from a task |
Files & search (OneDrive + SharePoint)
Read-only file access and search across the user's OneDrive and any SharePoint document libraries they can reach.
To search a specific library, resolve its drive-id first.
Use list_drives for the user's own OneDrive and list_site_drives for a SharePoint site's document libraries.
File results leave out Microsoft's pre-authenticated download link (@microsoft.graph.downloadUrl), because a caller holding that link can fetch the file without the gateway seeing it.
| Tool | Tags | Description |
|---|---|---|
list_drives | read-only | List the signed-in user's own drives (their OneDrive) |
list_site_drives | read-only | List a SharePoint site's document libraries by site-id |
get_drive_root_item | read-only | Get a drive's root item: the starting point for browsing a library |
search_drive | read-only | Search a drive (OneDrive or a SharePoint document library) for files by query |
search_folder | read-only | Search within a specific folder for files by query |
list_recent_files | read-only | List the files the user most recently used across OneDrive and SharePoint |
list_shared_with_me | read-only | List files and folders shared with the user, including SharePoint items |
Excel workbooks
Finding a spreadsheet is not the same as reading it.
These tools list the worksheets, tables and named items of an Excel workbook and return its cell values as JSON, so an agent can answer from a sheet without downloading the file.
Each tool takes the drive-id and driveItem-id of an .xlsx workbook.
search_drive and list_recent_files return them as the item's id and parentReference.driveId.
| Tool | Tags | Description |
|---|---|---|
list_workbook_worksheets | read-only | List a workbook's worksheets with their ids, names, and visibility |
get_worksheet_range | read-only | Get a range of a worksheet by address, such as A1:B2 |
get_worksheet_used_range | read-only | Get the smallest range that covers every cell with a value or formatting |
list_workbook_tables | read-only | List the tables in a workbook |
list_table_columns | read-only | List a table's columns and their values |
list_table_rows | read-only | List a table's rows and their values |
list_workbook_named_items | read-only | List the workbook's named ranges and constants |
Only .xlsx workbooks work, not .xls.
get_worksheet_used_range works with work or school accounts only.
list_table_rows and list_table_columns take the $top and $skip query parameters (how many rows to return and how many to skip) to page through large tables.
People, presence & search
| Tool | Tags | Description |
|---|---|---|
list_relevant_people | read-only | List the people most relevant to the signed-in user |
get_my_presence | read-only | Get the signed-in user's Teams presence |
search_query | read-only | Run a Microsoft Search query across content types: use entityTypes: ["driveItem"] to find SharePoint & OneDrive documents by keyword |
Profile & settings
| Tool | Tags | Description |
|---|---|---|
user_get_user | read-only | Get the signed-in user's profile |
get_mailbox_settings | read-only | Get time zone, working hours, language, and auto-reply configuration |
update_mailbox_settings | write, external | Update mailbox settings (time zone, working hours, auto-reply) |
Known limitations
A few Graph operations can't be driven by a pure JSON pass-through tool, so they aren't exposed:
- OneNote page creation is not available. You can create notebooks and sections and list, read, and delete pages, but creating a page requires a multipart HTML request body that a pass-through tool can't send.
- Meeting recording content download is not available.
list_recordingsreturns recording metadata; downloading the recording video is a binary stream, not a pass-through call. Transcript content is available viaget_transcript_content. - Large attachment upload is not available.
Uploading files over 3 MB requires a chunked upload session.
Attachments under 3 MB work via
add_attachmentfor mail andadd_todo_attachmentfor To Do tasks. - To Do open extensions are not exposed. Graph's custom-data extensions on task lists and tasks are a developer feature with no To Do user-facing equivalent, so they're left out.
- Online-meeting AI insights are not available. Microsoft's Copilot-generated meeting summaries and action items are a beta-only API, not present in the pinned Graph spec this connector generates from.
Required scopes
Add all of these under API permissions as delegated permissions, in step 2. Each tool requests the least-privilege scope Microsoft's own permissions data maps to its operation, and the catalog requests the collapsed union across all tools.
openid,profile– sign-in identityoffline_access– maintain access when the user is offlineUser.Read– read the signed-in user's profileMail.ReadWrite– list, search, read, draft, update, move, and delete mail, folders, and attachmentsMail.Send– send mail directly, reply, reply all, and forwardCalendars.ReadWrite– read, create, update, delete, cancel, and respond to calendar events and calendarsCalendars.Read.Shared– suggest meeting times and read free/busy from attendees' shared calendarsContacts.ReadWrite– read, create, update, and delete contacts and contact foldersMailboxSettings.ReadWrite– read and update mailbox settings, and manage inbox rulesNotes.ReadWrite– read and create OneNote notebooks, sections, and pagesTasks.ReadWrite– read, create, update, and delete Microsoft To Do task lists, tasks, checklist items, linked resources, and attachmentsFiles.Read.All– list OneDrive drives and SharePoint document libraries, search and browse their files, and read the contents of Excel workbooksOnlineMeetings.ReadWrite– create, read, update, and delete the user's online meetingsOnlineMeetingTranscript.Read.All– list and read Teams meeting transcriptsOnlineMeetingRecording.Read.All– list Teams meeting recordingsOnlineMeetingArtifact.Read.All– read meeting attendance reports and recordsPeople.Read– read the user's relevant people listPresence.Read– read the user's presenceChat.Create– create new chatsChat.ReadWrite– read and write chat messagesChatMember.Read– list chat membersChatMessage.Send– send and react to chat messagesChannelMessage.Send– send and react to channel messagesTeam.ReadBasic.All– list and read teamsTeamMember.Read.All– list team membersChannel.ReadBasic.All– list and read channelsChannel.Create– create channelsChannelSettings.ReadWrite.All– update channel propertiesChannelMessage.Read.All– read channel messagesTeamsTab.Read.All– list a channel's tabsTeamsAppInstallation.ReadForUser– list the user's installed Teams apps
Policy examples
Rules are evaluated top to bottom and the first match wins. Allow rules on their own restrict nothing, your org starts with a seeded Allow all rule, so any tools your allows don't cover still fall through to it. A restrictive recipe needs a catch-all deny scoped to this resource, ordered below the allows. New rules are inserted at the top of the list, so create them in reverse order or drag them into place. See Policies.
- Read-only access.
Allow
list_*,get_*, andfind_*, then deny*below them. - Read-only access by policy tag.
Deny the built-in
writepolicy tag and thedestructivepolicy tag (Tools pill) for this resource (MCP pill), above any allow rules. Every tool on this connector carries exactly one ofread-only,write, ordestructive, so these two rules leave only the read-only tools. - Block sending and replies.
Deny
send_*,reply_*, andforward_*above any allow rules. - Block destructive operations.
Deny
delete_*,cancel_*,move_*, andupdate_*. - Allow mail triage but block calendar changes.
Allow
*message*,get_*, andlist_*, then deny*event*, then deny*(list_eventsstill reads if you allow it explicitly above the*event*deny). - Allow reading Teams meeting artifacts only.
Allow
list_transcripts,get_transcript_content,list_recordings, andlist_attendance_*, then deny*. - Allow reading Teams chats and channels, block sending.
Allow
list_chat*,get_chat*,list_channel*,get_channel*,list_team*,get_team*,list_joined_teams,list_my_*,list_pinned_chat_messages, then deny*. - Allow reading To Do tasks only.
Allow
list_todo_*andget_todo_*, then deny*. The catalog still requestsTasks.ReadWriteat sign-in, so the policy, not the token, is what keeps To Do read-only. - Allow full access for a specific agent.
Scope an allow rule for
*to that agent on this MCP server. - Block destructive tools.
Add a deny rule with the built-in
destructivetag (Tools pill) for this resource (MCP pill).
Tool patterns are case-sensitive and match exactly unless they contain *.
This connector's tools are snake_case, for example list_messages.
Next steps
- Create a policy – start from the read-only pattern in Policy examples above.
- Connections – manage the Microsoft 365 accounts your users have linked.