> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Graph

Microsoft Graph connects your organization's Microsoft 365 data to Airia agents, covering mail, calendar, contacts, files, OneNote, tasks, Teams, and more.

<Note>
  Microsoft Graph shows up as **two separate servers** in the Airia catalogue: **Microsoft Graph** and **Microsoft Graph (BYO)**. They're not the same connection with two names. Each is added to a Gateway or Deployment on its own, and which one you pick changes both how setup works and which tools an agent can actually use. Read the comparison below before adding either one.
</Note>

## Two Ways to Connect

|                            | Microsoft Graph                                               | Microsoft Graph (BYO)                                                                            |
| -------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Azure app registration** | Owned and managed by Airia                                    | Registered and owned by you, in your own Microsoft Entra ID tenant                               |
| **Setup**                  | Click **Connect** and sign in                                 | Register an app in Entra ID, then enter your Client ID, Client Secret, and Tenant in Airia       |
| **Permissions**            | A fixed set of permissions covering the most common scenarios | Fully customizable. You choose exactly which permissions to grant                                |
| **Tool coverage**          | Most tools, listed below                                      | Every tool, including Teams chat, meeting transcripts, room booking, and SharePoint site listing |
| **Sign-in restriction**    | Any Microsoft account                                         | Can be restricted to only your organization's accounts                                           |
| **Best for**               | Getting started quickly with common scenarios                 | Full control over permissions, or unlocking every tool                                           |

If you're not sure which to pick, start with **Microsoft Graph**. You can add **Microsoft Graph (BYO)** later, or instead, if you run into a tool that needs a permission the quick connect option doesn't grant, each tool's required permission is called out in the [tool reference](#tools-and-required-permissions) below.

## What It Can Do

| Category                  | Capability                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Mail**                  | Search, read, send, reply to, forward, and organize Outlook mail, including drafts, folders, and inbox rules. |
| **Calendar**              | Read and create events, check free/busy time, find meeting times, and respond to invitations.                 |
| **Contacts**              | Read, create, update, delete, and bulk manage contacts.                                                       |
| **Files (OneDrive)**      | Browse, search, upload, download, and share files and folders.                                                |
| **SharePoint**            | Browse SharePoint sites, document libraries, and files.                                                       |
| **Excel**                 | Read and update worksheets, ranges, and tables in workbooks stored in OneDrive or SharePoint.                 |
| **OneNote**               | Read notebooks, sections, and pages, and create new pages and sections.                                       |
| **Tasks (To Do)**         | Read and manage To Do lists and tasks.                                                                        |
| **Teams and Chat**        | Read channels and chats, send channel and chat messages, and read meeting transcripts.                        |
| **People and Directory**  | Look up colleagues, search the organization directory, and explore reporting structure.                       |
| **Rooms and Places**      | Look up meeting rooms and book them as calendar resources.                                                    |
| **Identity and Presence** | Read the signed-in user's profile and availability status.                                                    |

## Connecting

### Microsoft Graph (Quick Connect)

This is the server that uses Airia's own Microsoft app registration, so there's no Azure setup on your end.

<Steps>
  <Step title="Add Microsoft Graph">
    Find **Microsoft Graph** in the server catalogue when building an MCP Deployment or MCP Gateway, or add it from **Server Management**.
  </Step>

  <Step title="Sign in">
    Click **Connect** and sign in with your Microsoft account when prompted. You'll be asked to authorize the permissions listed under [Quick Connect permissions](#quick-connect-permissions) below.
  </Step>
</Steps>

<Note>
  A few of the requested permissions, like reading SharePoint sites, require a Microsoft 365 administrator to approve them for the whole organization before any individual can authorize them. If sign in fails with an error mentioning "need admin approval," ask your admin to consent on your organization's behalf, or use **Microsoft Graph (BYO)** instead.
</Note>

Quick Connect is always a personal connection, tied to the Microsoft account you sign in with. See [Tenant vs. Personal Level App Credentials](/mcps/admin-controls/tenant-vs-personal-app-credentials) for what that means for your organization.

### Microsoft Graph (BYO)

This is the server that uses your own Azure app registration. You decide exactly which permissions to grant. Pick this one if you want to restrict sign in to your own organization, limit which Microsoft 365 data agents can touch, or unlock tools that Quick Connect doesn't cover.

<Steps>
  <Step title="Register an app">
    Go to [Azure Entra ID app registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and click **New registration**.
  </Step>

  <Step title="Choose account types and set the redirect URI">
    Give the app a name and choose which accounts can sign in (see [Account Types](#account-types) below, single tenant is recommended for most organizations). Under **Redirect URI**, select **Web** and enter:

    ```
    https://auth.airia.ai/OAuth/callback
    ```

    Then click **Register**.
  </Step>

  <Step title="Add API permissions">
    Go to **API permissions > Add a permission > Microsoft Graph > Delegated permissions** and add the permissions you need. See [Tools and Required Permissions](#tools-and-required-permissions) below to decide which ones, or use the [full coverage list](#granting-every-permission) to unlock every tool at once.
  </Step>

  <Step title="Grant admin consent">
    Still on the API permissions page, click **Grant admin consent for \[your organization]**. This is required for any permission ending in `.All`, or the connection will fail for anyone who isn't an admin.
  </Step>

  <Step title="Create a client secret">
    Go to **Certificates & secrets > New client secret** and copy the **Value** immediately. Azure only shows it once.
  </Step>

  <Step title="Copy your IDs">
    From the app's **Overview** page, copy the **Application (client) ID** and, if you chose single tenant, the **Directory (tenant) ID**.
  </Step>

  <Step title="Add it to Airia">
    Add **Microsoft Graph (BYO)** as a server on a Gateway or Deployment, then enter your **Client ID**, **Client Secret**, and **Tenant** value. Complete the sign in flow to finish connecting.
  </Step>
</Steps>

Because BYO uses an app registration you control, the Client ID and Client Secret can be shared at the Tenant level so this setup only happens once for your organization. Each person who connects still signs in with their own Microsoft account. See [Tenant vs. Personal Level App Credentials](/mcps/admin-controls/tenant-vs-personal-app-credentials) for more on how that works.

#### Account Types

Azure offers four options when you register the app, and each one expects a different Tenant value in Airia:

| Account type                                                             | Tenant value in Airia      |
| ------------------------------------------------------------------------ | -------------------------- |
| Accounts in this organizational directory only (single tenant)           | Your Directory (tenant) ID |
| Accounts in any organizational directory (multitenant)                   | `organizations`            |
| Accounts in any organizational directory and personal Microsoft accounts | `common`                   |
| Personal Microsoft accounts only                                         | `consumers`                |

Single tenant is recommended if you want to restrict sign in to people in your own organization.

## Tools and Required Permissions

Every tool below needs a specific Microsoft Graph permission before it will work. Tool names are what an agent actually calls, the same names you'd see in an agent's tool call log. The **Works with** column tells you whether the required permission is already included in Quick Connect's fixed set, or whether you need Microsoft Graph (BYO) with that permission added.

<Note>
  Most tools accept more than one permission, listed with **or**. Any one of them is enough, and broader permissions (ending in `.All` or `.Shared`) work just as well as the narrower one. A few tools, called out with **and**, need every listed permission granted at the same time. If a permission ends in `.All`, granting it through Bring Your Own also requires the [admin consent step](#connecting) covered above.
</Note>

### Mail

| Tool                                       | What it does                                                                 | Scope(s) required                                                          | Works with   |
| ------------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_search_emails_kql`        | Searches emails using Microsoft Graph KQL full-text search.                  | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_filter_emails`            | Filters emails using Microsoft Graph OData structured filtering.             | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_get_email`                | Retrieves a specific email by its ID.                                        | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_list_message_attachments` | Lists attachments for an Outlook email.                                      | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_get_message_attachment`   | Downloads a specific attachment from an Outlook email.                       | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_create_draft_email`       | Creates a new email draft.                                                   | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_send_email`               | Sends an email directly without creating a draft first.                      | `Mail.Send` or `Mail.Send.All`                                             | Both servers |
| `microsoft_graph_reply_to_email`           | Creates a reply to an existing email message.                                | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_forward_email`            | Forwards an existing email message to new recipients.                        | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_send_draft`               | Sends a previously created draft email message.                              | `Mail.ReadWrite` or `Mail.Send` or `Mail.ReadWrite.All` or `Mail.Send.All` | Both servers |
| `microsoft_graph_update_draft`             | Updates properties of an existing draft email message.                       | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_list_mail_folders`        | Lists mail folders with hierarchy and item counts.                           | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_get_mail_folder`          | Gets detailed information about a specific mail folder.                      | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_list_child_folders`       | Lists child folders under a specific parent folder.                          | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_list_drafts`              | Lists all draft emails in the user's Drafts folder.                          | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_get_draft`                | Gets a specific draft email by its ID.                                       | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_get_recent_draft`         | Gets the most recently modified draft email.                                 | `Mail.Read` or `Mail.Read.Shared` or `Mail.Read.All`                       | Both servers |
| `microsoft_graph_move_message`             | Moves an email message to another mail folder.                               | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_copy_message`             | Copies an email message to another mail folder.                              | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_set_message_read`         | Marks an email message as read or unread.                                    | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_move_messages_bulk`       | Moves multiple email messages to the same destination folder at once.        | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_create_mail_folder`       | Creates a new Outlook mail folder.                                           | `Mail.ReadWrite` or `Mail.ReadWrite.Shared` or `Mail.ReadWrite.All`        | Both servers |
| `microsoft_graph_create_message_rule`      | Creates a server-side Outlook rule that runs automatically on incoming mail. | `MailboxSettings.ReadWrite`                                                | BYO only     |

### Calendar

| Tool                                     | What it does                                                                  | Scope(s) required                                                                                    | Works with   |
| ---------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_create_calendar_event`  | Creates a new event in the user's default calendar.                           | `Calendars.ReadWrite` or `Calendars.ReadWrite.Shared` or `Calendars.ReadWrite.All`                   | Both servers |
| `microsoft_graph_find_meeting_times`     | Finds possible meeting times based on attendee availability.                  | `Calendars.Read` or `Calendars.ReadWrite` or `Calendars.Read.Shared` or `Calendars.ReadWrite.Shared` | Both servers |
| `microsoft_graph_list_calendar_events`   | Retrieves events from the calendar, with date range filtering and pagination. | `Calendars.Read` or `Calendars.ReadWrite` or `Calendars.Read.Shared` or `Calendars.ReadWrite.Shared` | Both servers |
| `microsoft_graph_get_single_event`       | Retrieves detailed information about a specific calendar event.               | `Calendars.Read` or `Calendars.ReadWrite` or `Calendars.Read.Shared` or `Calendars.ReadWrite.Shared` | Both servers |
| `microsoft_graph_update_calendar_event`  | Updates properties of an existing calendar event.                             | `Calendars.ReadWrite` or `Calendars.ReadWrite.Shared`                                                | Both servers |
| `microsoft_graph_delete_calendar_event`  | Removes a calendar event, sending cancellations to attendees for meetings.    | `Calendars.ReadWrite` or `Calendars.ReadWrite.Shared`                                                | Both servers |
| `microsoft_graph_respond_to_meeting`     | Accepts, tentatively accepts, or declines a meeting invitation.               | `Calendars.ReadWrite` or `Calendars.ReadWrite.Shared`                                                | Both servers |
| `microsoft_graph_get_free_busy_schedule` | Retrieves free/busy availability for users or resources.                      | `Calendars.Read` or `Calendars.Read.Shared`                                                          | Both servers |

### Contacts

| Tool                                      | What it does                                                         | Scope(s) required                                                               | Works with   |
| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_search_contacts`         | Searches personal contacts by name, email, phone, or other criteria. | `Contacts.Read` or `Contacts.Read.Shared` or `Contacts.Read.All`                | Both servers |
| `microsoft_graph_get_contact`             | Retrieves complete information for a specific contact.               | `Contacts.Read` or `Contacts.Read.Shared` or `Contacts.Read.All`                | Both servers |
| `microsoft_graph_create_contact`          | Creates a new contact.                                               | `Contacts.ReadWrite` or `Contacts.ReadWrite.Shared` or `Contacts.ReadWrite.All` | Both servers |
| `microsoft_graph_update_contact`          | Updates an existing contact's information.                           | `Contacts.ReadWrite` or `Contacts.ReadWrite.Shared` or `Contacts.ReadWrite.All` | Both servers |
| `microsoft_graph_list_contacts`           | Retrieves a list of contacts with filtering and pagination.          | `Contacts.Read` or `Contacts.Read.Shared` or `Contacts.Read.All`                | Both servers |
| `microsoft_graph_delete_contact`          | Removes a contact.                                                   | `Contacts.ReadWrite` or `Contacts.ReadWrite.Shared` or `Contacts.ReadWrite.All` | Both servers |
| `microsoft_graph_bulk_contact_operations` | Creates, updates, or deletes multiple contacts in one operation.     | `Contacts.ReadWrite` or `Contacts.ReadWrite.Shared` or `Contacts.ReadWrite.All` | Both servers |

### Files (OneDrive)

| Tool                                                | What it does                                                     | Scope(s) required                                                                      | Works with   |
| --------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_get_drive`                         | Retrieves the user's OneDrive quota, usage, and owner details.   | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_list_drive_items`                  | Lists files and folders in OneDrive.                             | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_list_shared_with_me`               | Lists files and folders other users have shared with the user.   | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_get_file_metadata`                 | Retrieves metadata about a specific file or folder.              | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_create_folder`                     | Creates a new folder in OneDrive.                                | `Files.ReadWrite` or `Files.ReadWrite.All`                                             | Both servers |
| `microsoft_graph_delete_item`                       | Deletes a file or folder from OneDrive.                          | `Files.ReadWrite` or `Files.ReadWrite.All`                                             | Both servers |
| `microsoft_graph_create_shared_link`                | Creates a sharing link for a file or folder.                     | `Files.ReadWrite` or `Files.ReadWrite.All`                                             | Both servers |
| `microsoft_graph_search_drive`                      | Searches OneDrive by file name and content.                      | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_download_file_content`             | Downloads the content of a file from OneDrive or SharePoint.     | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All`         | Both servers |
| `microsoft_graph_upload_file`                       | Uploads a file to OneDrive or SharePoint from a source URL.      | `Files.ReadWrite` or `Files.ReadWrite.All` or `Sites.ReadWrite.All`                    | Both servers |
| `microsoft_graph_get_drive_item_sensitivity_labels` | Reads the Microsoft Purview sensitivity label applied to a file. | `Files.Read.All` or `Files.ReadWrite.All` or `Sites.Read.All` or `Sites.ReadWrite.All` | BYO only     |

### SharePoint

| Tool                                       | What it does                                                           | Scope(s) required                                    | Works with   |
| ------------------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------- | ------------ |
| `microsoft_graph_sharepoint_url_to_path`   | Converts a SharePoint file URL into a path usable by other file tools. | `Files.Read` or `Files.Read.All` or `Sites.Read.All` | Both servers |
| `microsoft_graph_list_sharepoint_sites`    | Lists SharePoint sites the user has access to.                         | `Sites.Read.All`                                     | BYO only     |
| `microsoft_graph_list_sharepoint_drives`   | Lists document libraries in a SharePoint site.                         | `Files.Read` or `Files.Read.All` or `Sites.Read.All` | Both servers |
| `microsoft_graph_list_sharepoint_files`    | Lists files and folders in a SharePoint document library.              | `Files.Read` or `Files.Read.All`                     | Both servers |
| `microsoft_graph_get_sharepoint_file_info` | Gets metadata for a specific SharePoint file.                          | `Files.Read` or `Files.Read.All`                     | Both servers |

### Excel

| Tool                                       | What it does                                                     | Scope(s) required                                                              | Works with   |
| ------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------ |
| `microsoft_graph_list_excel_worksheets`    | Lists worksheets in a workbook stored in OneDrive or SharePoint. | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_get_excel_worksheet`      | Gets detailed information about a specific worksheet.            | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_get_excel_used_range`     | Gets the range of a worksheet that contains data.                | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_get_excel_range`          | Gets a specific range of cells from a worksheet.                 | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_update_excel_range`       | Updates a range of cells with new values.                        | `Files.ReadWrite` or `Files.ReadWrite.All`                                     | Both servers |
| `microsoft_graph_list_excel_tables`        | Lists tables in a workbook.                                      | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_get_excel_table`          | Gets detailed information about a specific table.                | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_list_excel_table_rows`    | Lists rows in a specific table.                                  | `Files.Read` or `Files.ReadWrite` or `Files.Read.All` or `Files.ReadWrite.All` | Both servers |
| `microsoft_graph_add_excel_table_row`      | Adds a new row to a table.                                       | `Files.ReadWrite` or `Files.ReadWrite.All`                                     | Both servers |
| `microsoft_graph_create_excel_session`     | Creates a workbook session for batching multiple operations.     | `Files.ReadWrite` or `Files.ReadWrite.All`                                     | Both servers |
| `microsoft_graph_calculate_excel_workbook` | Triggers recalculation of all formulas in the workbook.          | `Files.ReadWrite` or `Files.ReadWrite.All`                                     | Both servers |

### OneNote

| Tool                                  | What it does                                                    | Scope(s) required                                            | Works with   |
| ------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ | ------------ |
| `microsoft_graph_list_notebooks`      | Lists notebooks accessible to the user.                         | `Notes.Read` or `Notes.Read.All`                             | Both servers |
| `microsoft_graph_list_sections`       | Lists sections across notebooks, or within a specific notebook. | `Notes.Read` or `Notes.Read.All`                             | Both servers |
| `microsoft_graph_search_pages`        | Searches pages across all notebooks.                            | `Notes.Read` or `Notes.Read.All`                             | Both servers |
| `microsoft_graph_get_page_content`    | Retrieves the full HTML content of a specific page.             | `Notes.Read` or `Notes.Read.All`                             | Both servers |
| `microsoft_graph_create_page`         | Creates a new page in a specified section.                      | `Notes.Create` or `Notes.ReadWrite` or `Notes.ReadWrite.All` | Both servers |
| `microsoft_graph_list_section_pages`  | Lists pages within a specific section.                          | `Notes.Read` or `Notes.Read.All`                             | Both servers |
| `microsoft_graph_add_content_to_page` | Adds new content to an existing page.                           | `Notes.Create` or `Notes.ReadWrite` or `Notes.ReadWrite.All` | Both servers |
| `microsoft_graph_create_section`      | Creates a new section within a notebook.                        | `Notes.Create` or `Notes.ReadWrite` or `Notes.ReadWrite.All` | Both servers |

### Tasks (To Do)

| Tool                               | What it does                                 | Scope(s) required                                                                                                                 | Works with   |
| ---------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_get_todo_lists`   | Gets all To Do lists for the signed-in user. | `Tasks.Read` or `Tasks.ReadWrite` or `Tasks.Read.Shared` or `Tasks.ReadWrite.Shared` or `Tasks.Read.All` or `Tasks.ReadWrite.All` | Both servers |
| `microsoft_graph_get_todo_tasks`   | Gets tasks from a specific To Do list.       | `Tasks.Read` or `Tasks.ReadWrite` or `Tasks.Read.Shared` or `Tasks.ReadWrite.Shared` or `Tasks.Read.All` or `Tasks.ReadWrite.All` | Both servers |
| `microsoft_graph_create_todo_task` | Creates a new task in a specific list.       | `Tasks.ReadWrite` and `Tasks.ReadWrite.Shared` and `Tasks.ReadWrite.All`                                                          | BYO only     |
| `microsoft_graph_update_todo_task` | Updates an existing task.                    | `Tasks.ReadWrite` and `Tasks.ReadWrite.Shared` and `Tasks.ReadWrite.All`                                                          | BYO only     |
| `microsoft_graph_delete_todo_task` | Deletes a task.                              | `Tasks.ReadWrite` and `Tasks.ReadWrite.Shared` and `Tasks.ReadWrite.All`                                                          | BYO only     |
| `microsoft_graph_create_todo_list` | Creates a new To Do list.                    | `Tasks.ReadWrite` and `Tasks.ReadWrite.Shared` and `Tasks.ReadWrite.All`                                                          | BYO only     |
| `microsoft_graph_delete_todo_list` | Deletes a To Do list.                        | `Tasks.ReadWrite` and `Tasks.ReadWrite.Shared` and `Tasks.ReadWrite.All`                                                          | BYO only     |

<Note>
  Reading tasks and lists works on both servers. Creating, updating, or deleting a task or list needs all three `Tasks.ReadWrite` permissions granted together, which currently only Microsoft Graph (BYO) can provide.
</Note>

### Teams and Chat

| Tool                                             | What it does                                                         | Scope(s) required                                                                         | Works with   |
| ------------------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_list_teams`                     | Lists Microsoft Teams the user has joined.                           | `Team.ReadBasic.All` or `Team.ReadAll.All`                                                | BYO only     |
| `microsoft_graph_list_channels`                  | Lists channels in a specific Team.                                   | `Channel.ReadBasic.All` or `ChannelMessage.Read.All`                                      | Both servers |
| `microsoft_graph_send_message`                   | Sends a message to a Teams channel.                                  | `ChannelMessage.Send` or `ChannelMessage.ReadWrite.All`                                   | Both servers |
| `microsoft_graph_list_chats`                     | Lists one-on-one, group, and meeting chats the user is in.           | `Chat.Read` or `Chat.ReadBasic` or `Chat.Read.All`                                        | BYO only     |
| `microsoft_graph_send_chat_message`              | Sends a message to an existing Teams chat.                           | `Chat.ReadWrite` or `ChatMessage.Send`                                                    | BYO only     |
| `microsoft_graph_create_or_get_chat`             | Creates or retrieves a one-on-one chat with a specific user.         | `Chat.ReadWrite` or `Chat.Create`                                                         | BYO only     |
| `microsoft_graph_list_meeting_transcripts`       | Lists transcripts available for a Teams meeting.                     | `OnlineMeetings.Read` or `OnlineMeetings.ReadWrite` or `OnlineMeetingTranscript.Read.All` | BYO only     |
| `microsoft_graph_get_meeting_transcript`         | Gets metadata for a specific meeting transcript.                     | `OnlineMeetings.Read` or `OnlineMeetings.ReadWrite` or `OnlineMeetingTranscript.Read.All` | BYO only     |
| `microsoft_graph_get_meeting_transcript_content` | Gets the full transcript content, including timestamps and speakers. | `OnlineMeetings.Read` or `OnlineMeetings.ReadWrite` or `OnlineMeetingTranscript.Read.All` | BYO only     |

### People and Directory

| Tool                                        | What it does                                                               | Scope(s) required                                                       | Works with   |
| ------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------ |
| `microsoft_graph_find_colleagues`           | Surfaces people most relevant to the user based on collaboration patterns. | `People.Read` or `People.Read.All`                                      | Both servers |
| `microsoft_graph_search_directory`          | Searches the directory by name, email, title, or department.               | `User.Read` or `User.ReadBasic.All` or `User.Read.All`                  | Both servers |
| `microsoft_graph_get_manager_chain`         | Retrieves the management hierarchy above a specific user.                  | `User.Read` or `User.ReadBasic.All` or `User.Read.All`                  | Both servers |
| `microsoft_graph_view_team_structure`       | Shows direct reports for a specific manager.                               | `User.Read` or `User.ReadBasic.All` or `User.Read.All`                  | Both servers |
| `microsoft_graph_get_detailed_user_profile` | Retrieves a user's professional background, skills, and contact info.      | `User.Read` or `User.ReadBasic.All` or `User.Read.All`                  | Both servers |
| `microsoft_graph_find_people_with_skills`   | Searches the organization by listed skills or expertise.                   | `User.Read` or `User.ReadBasic.All` or `User.Read.All`                  | Both servers |
| `microsoft_graph_explore_org_context`       | Combines directory data to explain a person's role and relationships.      | `User.Read` or `People.Read` or `User.ReadBasic.All` or `User.Read.All` | Both servers |

### Rooms and Places

| Tool                                      | What it does                                                       | Scope(s) required                                  | Works with   |
| ----------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------- | ------------ |
| `microsoft_graph_list_available_rooms`    | Lists rooms in the tenant with capacity, equipment, and location.  | `Place.Read.All`                                   | BYO only     |
| `microsoft_graph_check_room_availability` | Checks free/busy status for a room or piece of equipment.          | `Calendars.Read` or `Calendars.Read.All`           | Both servers |
| `microsoft_graph_book_room_resource`      | Books a room by adding it as an attendee on a calendar event.      | `Calendars.ReadWrite` or `Calendars.ReadWrite.All` | Both servers |
| `microsoft_graph_get_room_details`        | Retrieves equipment, accessibility, and booking policy for a room. | `Place.Read.All`                                   | BYO only     |
| `microsoft_graph_list_room_lists`         | Retrieves rooms grouped by building or floor.                      | `Place.Read.All`                                   | BYO only     |
| `microsoft_graph_list_calendars`          | Lists calendars available to the user.                             | `Calendars.Read` or `Calendars.Read.All`           | Both servers |
| `microsoft_graph_get_calendar_details`    | Retrieves properties and settings for a specific calendar.         | `Calendars.Read` or `Calendars.Read.All`           | Both servers |

### Identity and Presence

| Tool                                | What it does                                                           | Scope(s) required                                                                                  | Works with   |
| ----------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ |
| `microsoft_graph_get_user_profile`  | Retrieves the signed-in user's name, email, job title, and department. | `User.Read` or `User.ReadWrite` or `User.ReadBasic.All` or `User.Read.All` or `User.ReadWrite.All` | Both servers |
| `microsoft_graph_get_user_presence` | Retrieves the signed-in user's availability and status message.        | `Presence.Read` or `Presence.Read.All`                                                             | Both servers |

## Quick Connect Permissions

Quick Connect always requests this fixed set of permissions:

```
Calendars.Read Calendars.ReadWrite Channel.ReadBasic.All ChannelMessage.Send Contacts.Read Contacts.ReadWrite email Files.Read Files.ReadWrite Mail.Read Mail.ReadWrite Mail.Send Notes.Read Notes.ReadWrite People.Read Presence.Read Tasks.Read Tasks.ReadWrite User.Read offline_access openid
```

## Granting Every Permission

If you want Microsoft Graph (BYO) to unlock every tool listed above, add all of the following delegated permissions to your app registration, then grant admin consent:

```
openid offline_access Calendars.Read Calendars.ReadWrite Channel.ReadBasic.All ChannelMessage.Send Chat.Read Chat.ReadWrite Contacts.Read Contacts.ReadWrite Files.Read Files.ReadWrite Files.Read.All Mail.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite Notes.Create Notes.Read OnlineMeetings.Read People.Read Place.Read.All Presence.Read Sites.Read.All Tasks.Read Tasks.ReadWrite Tasks.ReadWrite.Shared Tasks.ReadWrite.All Team.ReadBasic.All User.Read
```

<Warning>
  Always include `openid` and `offline_access`. Without `offline_access`, Airia can't refresh the connection once the access token expires (about an hour), and users will have to reconnect constantly.
</Warning>

### Extending Beyond Your Own Data

By default, every tool acts on the signed-in user's own mailbox, calendar, files, and so on. Several tools accept a parameter to act on another user's data instead, for delegate, shared mailbox, or admin scenarios. That only works if you grant the broader version of the permission on your Bring Your Own app:

| Area           | Broader permission                                                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mail           | `Mail.Read.All`, `Mail.ReadWrite.All`, `Mail.Read.Shared`, `Mail.ReadWrite.Shared`                                                                                      |
| Calendar       | `Calendars.Read.All`, `Calendars.ReadWrite.All`, `Calendars.Read.Shared`, `Calendars.ReadWrite.Shared`                                                                  |
| Contacts       | `Contacts.Read.All`, `Contacts.ReadWrite.All`, `Contacts.Read.Shared`, `Contacts.ReadWrite.Shared`                                                                      |
| Files          | `Files.ReadWrite.All`                                                                                                                                                   |
| OneNote        | `Notes.ReadWrite`, `Notes.Read.All`, `Notes.ReadWrite.All`                                                                                                              |
| Identity       | `User.Read.All`, `User.ReadBasic.All`, `User.ReadWrite`, `User.ReadWrite.All`, `Presence.Read.All`                                                                      |
| People         | `People.Read.All`                                                                                                                                                       |
| Teams and chat | `ChannelMessage.Read.All`, `ChannelMessage.ReadWrite`, `Chat.Read.All`, `Chat.ReadBasic`, `Chat.Create`, `OnlineMeetings.ReadWrite`, `OnlineMeetingTranscript.Read.All` |

## Admin Consent

Any permission ending in `.All` and many `.Shared` variants require tenant admin consent before individual users can grant them. Without it, the OAuth flow surfaces `AADSTS65001 "need admin approval"`.

Two ways to grant admin consent:

1. From the app's **API permissions** page, click **Grant admin consent for \[tenant]** (one-time, organization-wide).
2. Have a tenant admin navigate to this URL after replacing the placeholder values:

   ```
   https://login.microsoftonline.com/{tenant}/adminconsent?client_id={your-client-id}
   ```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sign in fails with an admin approval error" icon="user-lock">
    This means one of the requested permissions needs tenant admin consent. For Quick Connect, ask a Microsoft 365 admin to approve the connection for your organization, or switch to Bring Your Own. For BYO, go back to your app's API permissions page and click **Grant admin consent**.
  </Accordion>

  <Accordion title="A whole category of tools is missing" icon="magnifying-glass">
    Some categories, like Teams chat, meeting transcripts, and room booking, aren't included in Quick Connect's fixed permission set. Check the [tool reference](#tools-and-required-permissions) above. If a tool is marked **BYO only**, switch to Microsoft Graph (BYO) and add the listed permission.
  </Accordion>

  <Accordion title="The connection stops working after about an hour" icon="clock-rotate-left">
    This happens when `offline_access` wasn't included in the granted permissions, so Airia has no way to refresh the session. For BYO, add `offline_access` to your app's permissions, grant consent again, and reconnect.
  </Accordion>

  <Accordion title="A specific action fails, like sending mail or reading files" icon="triangle-exclamation">
    The signed in account is missing the underlying permission for that action. Check the [tool reference](#tools-and-required-permissions) above for the exact permission the tool needs. For BYO, add it to your app registration, grant admin consent if it's a `.All` or `.Shared` permission, and have users reconnect.
  </Accordion>
</AccordionGroup>

## Learn More

* [Microsoft Graph API reference](https://docs.microsoft.com/en-us/graph/)
* [Microsoft Graph permissions reference](https://docs.microsoft.com/en-us/graph/permissions-reference)
* [Graph Explorer, try API calls in the browser](https://developer.microsoft.com/en-us/graph/graph-explorer)