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

# Microsoft overview

> One-time Microsoft 365 tenant setup shared by the Dema Agent's Teams, Outlook, and SharePoint integrations.

export const MicrosoftPreviewNote = () => <Note>
    Microsoft integrations are in <strong>preview</strong>, and so are the Agent 365 / Work IQ MCP servers behind them. Tools can change without notice. Your workspace might need preview integrations enabled before these show up.
  </Note>;

export const McpUrlPlaceholderNote = () => <Note>
    Replace the whole <code>{'{tenant_id}'}</code> placeholder, braces included. Dema rejects a URL that still has braces in it. A tenant ID is a GUID, like <code>8f7a1b2c-3d4e-4f56-a7b8-9c0d1e2f3a4b</code>.
  </Note>;

## Overview

Dema connects to Microsoft 365 through Microsoft's hosted **Agent 365 / Work IQ** MCP servers. Three integrations are available, and all three use one tenant setup, one sign-in, and one permission model:

<CardGroup cols={3}>
  <Card title="Microsoft Teams" icon="https://mintcdn.com/demaai/-QBoxgr91D2DfDZm/images/integrations/microsoft-teams.svg?fit=max&auto=format&n=-QBoxgr91D2DfDZm&q=85&s=9564e19b6a969b4b43bc80b891980978" href="/guides/agent/integrations/microsoft-teams" width="24" height="24" data-path="images/integrations/microsoft-teams.svg">
    Chats, channels, messages, threads, and members
  </Card>

  <Card title="Microsoft Outlook" icon="https://mintcdn.com/demaai/-QBoxgr91D2DfDZm/images/integrations/microsoft-outlook.svg?fit=max&auto=format&n=-QBoxgr91D2DfDZm&q=85&s=27c70f1d558a00d59abfa6353181f84f" href="/guides/agent/integrations/microsoft-outlook" width="24" height="24" data-path="images/integrations/microsoft-outlook.svg">
    Mail: read, search, organize, compose, and send
  </Card>

  <Card title="Microsoft SharePoint" icon="https://mintcdn.com/demaai/-QBoxgr91D2DfDZm/images/integrations/microsoft-sharepoint.svg?fit=max&auto=format&n=-QBoxgr91D2DfDZm&q=85&s=d7ee234abe4be7825b2db06b9f489d3e" href="/guides/agent/integrations/microsoft-sharepoint" width="24" height="24" data-path="images/integrations/microsoft-sharepoint.svg">
    Sites, lists, document libraries, files, and sharing
  </Card>
</CardGroup>

Each integration talks to a server address unique to your Microsoft 365 tenant, which is why connecting takes an **MCP URL** and not just a sign-in. The agent acts only when you ask it to, and Dema asks you to confirm sensitive changes first. It signs in as whoever authorized the connection, so it cannot reach anything that person cannot open.

<MicrosoftPreviewNote />

***

## Prerequisites

| What you need                                                    | Why                                                                                       |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| A **Microsoft 365** work or school account                       | Personal Microsoft accounts cannot reach Agent 365 servers                                |
| A **Microsoft 365 Copilot** license for each person who connects | Microsoft's Work IQ servers run on the Copilot Chat API and reject tool calls without one |
| A **Global Administrator** in Microsoft Entra                    | For the one-time tenant setup below                                                       |
| Your **Entra tenant ID**, a GUID                                 | It goes into the MCP URL                                                                  |

<Tip>
  Find your tenant ID in the [Entra admin center](https://entra.microsoft.com) under **Overview → Tenant ID**, or run `az account show --query tenantId -o tsv`.
</Tip>

***

## One-time tenant setup

An admin does this **once per Microsoft 365 tenant**, not once per integration. Afterwards, anyone with a Copilot license can connect Teams, Outlook, and SharePoint.

<Steps>
  <Step title="Provision the Agent 365 Tools service principal">
    Microsoft exposes its Agent 365 tools through a shared resource called **Agent 365 Tools**, application ID `ea9ffc3e-8a23-4a7d-836d-234d7c7565c1`. Its service principal is not created in your tenant automatically, so a Global Administrator adds it once. Either method works:

    <Tabs>
      <Tab title="Azure CLI">
        With the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed, signed in as an admin:

        ```bash Provision the service principal theme={null}
        az ad sp create --id ea9ffc3e-8a23-4a7d-836d-234d7c7565c1
        ```

        <Check>
          The command prints the new service principal as JSON. `Another object with the same value for property appId already exists` means it was already provisioned.
        </Check>
      </Tab>

      <Tab title="Graph Explorer">
        No CLI needed. Open [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer), sign in as an admin, and send:

        ```http Request theme={null}
        POST https://graph.microsoft.com/v1.0/servicePrincipals
        Content-Type: application/json

        {
          "appId": "ea9ffc3e-8a23-4a7d-836d-234d7c7565c1"
        }
        ```

        <Check>
          A `201 Created` response means it worked. A `409 Conflict` means it was already provisioned.
        </Check>
      </Tab>
    </Tabs>

    <Warning>
      Skip this and connecting fails with **AADSTS650052**, *"your organization lacks a service principal"*, and the `McpServers` permissions never appear in Entra.
    </Warning>
  </Step>

  <Step title="Decide who approves the permission">
    Whoever connects is asked to approve one permission during sign-in:

    | Integration          | Permission                  |
    | -------------------- | --------------------------- |
    | Microsoft Teams      | `McpServers.Teams.All`      |
    | Microsoft Outlook    | `McpServers.Mail.All`       |
    | Microsoft SharePoint | `McpServers.SharePoint.All` |

    If your tenant does not allow users to approve permissions themselves, that step fails and a Global Administrator grants it for everyone once. Replace `{tenant_id}` with your tenant ID, open the URL, and sign in as an admin:

    ```text Admin consent URL theme={null}
    https://login.microsoftonline.com/{tenant_id}/adminconsent?client_id=a268336e-61fb-483f-a9f9-df76dff26c93
    ```

    <Info>
      One grant covers all three integrations, and nobody in the tenant sees a consent prompt afterwards.
    </Info>
  </Step>
</Steps>

***

## Build your MCP URL

Every Microsoft integration asks for an MCP URL. Copy the one for the integration you are connecting, and replace `{tenant_id}` with your Entra tenant ID:

<CodeGroup>
  ```text Microsoft Teams theme={null}
  https://agent365.svc.cloud.microsoft/agents/tenants/{tenant_id}/servers/mcp_TeamsServer
  ```

  ```text Microsoft Outlook theme={null}
  https://agent365.svc.cloud.microsoft/agents/tenants/{tenant_id}/servers/mcp_MailTools
  ```

  ```text Microsoft SharePoint theme={null}
  https://agent365.svc.cloud.microsoft/agents/tenants/{tenant_id}/servers/mcp_SharePointRemoteServer
  ```
</CodeGroup>

<McpUrlPlaceholderNote />

***

## Connect in Dema

<Steps>
  <Step title="Open the integration">
    In Dema, go to **Agents → Settings → Integrations**, find the Microsoft integration you want, and click **Connect**.
  </Step>

  <Step title="Enter the MCP URL">
    Paste the URL you built above, then click **Add**.
  </Step>

  <Step title="Sign in and approve">
    Sign in with a Microsoft **work or school** account belonging to the same tenant as the URL, and approve the permission Dema asks for.

    <Check>
      You are returned to Dema with the integration marked as Active.
    </Check>
  </Step>
</Steps>

<Tip>
  Connecting a second Microsoft integration repeats only these three steps, since the tenant setup is already done.
</Tip>

***

## When the connection expires

Access tokens last about an hour, and Dema refreshes them in the background. A connection lapses only if the refresh window passes while Dema is disconnected, if the authorizing user's account is disabled, or if an admin revokes consent for the Dema app. When that happens, reconnect from **Agents → Settings → Integrations**.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dema says the MCP URL is invalid" icon="link-slash">
    The URL still contains the placeholder. Replace `{tenant_id}` and its braces with your tenant GUID, so the address ends in `/agents/tenants/<your-guid>/servers/<server-name>`. Check the server name matches [the list above](#build-your-mcp-url) exactly, including capitalization.
  </Accordion>

  <Accordion title="AADSTS650052: your organization lacks a service principal" icon="shield-halved">
    The Agent 365 Tools service principal is missing from your tenant. An admin runs the provisioning step in [One-time tenant setup](#one-time-tenant-setup).
  </Accordion>

  <Accordion title="Sign-in says approval is required by an administrator" icon="user-lock">
    Your tenant does not allow users to approve permissions themselves, usually reported as **AADSTS65001** or **AADSTS90094**. A Global Administrator grants it once with the [admin consent URL](#one-time-tenant-setup), and connecting works normally afterwards.
  </Accordion>

  <Accordion title="Sign-in is rejected" icon="right-to-bracket">
    Two things to check:

    * You signed in with a **personal** Microsoft account. Only work or school accounts are supported.
    * The account belongs to a **different tenant** than the one in your MCP URL. They have to be the same organization.
  </Accordion>

  <Accordion title="The connection is Active but the agent sees nothing, or gets a 403" icon="id-card">
    This is usually a missing **Microsoft 365 Copilot** license for the user who authorized the connection. Assign one, wait for it to propagate, then ask again. If it still fails, reconnect so Dema picks up a fresh token.
  </Accordion>

  <Accordion title="The permission does not appear in Entra" icon="key">
    An Entra admin has to register or consent the relevant Work IQ MCP server in your tenant before anyone can grant its `McpServers` permission.
  </Accordion>
</AccordionGroup>

Still stuck? Contact [support](mailto:info@dema.ai) with the error message, including the Entra `AADSTS` code if you have one.

***

## Additional resources

* [Set up the Agent 365 Tools service principal](https://learn.microsoft.com/microsoft-agent-365/developer/tooling)
* [Manage tools for agents in the Microsoft 365 admin center](https://learn.microsoft.com/microsoft-agent-365/bring-your-own-mcp)
* [Work IQ API permissions](https://learn.microsoft.com/microsoft-365/copilot/extensibility/work-iq/permissions)