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

# Connect Microsoft 365 Copilot to Ruddr

> Add Ruddr to Microsoft 365 Copilot for your organization, so every member can ask Copilot about their Ruddr work.

**NOTE:** The Ruddr Assistant [feature](https://help.ruddr.io/workspace-administration/features.md) must be enabled in workspace settings in order for this to be available in your workspace.

Ruddr is available as an app in Microsoft Marketplace. A Microsoft 365 administrator installs it once for the whole organization, and each member then connects their own Ruddr account from Copilot. Installing the app gives nobody access to Ruddr data on its own. The same app also provides the [Ruddr app for Microsoft Teams](https://help.ruddr.io/integrations/microsoft-teams-integration-overview.md) and the [Outlook calendar integration](https://help.ruddr.io/integrations/microsoft-outlook-calendar-integration.md); Copilot works on its own and does not need the workspace connection those two use (see the [Microsoft 365 Integration Setup](https://help.ruddr.io/integrations/microsoft-365-integration-setup.md) article).

> [!NOTE]
>
> Each member who uses Ruddr in Copilot needs a Microsoft 365 Copilot license. Microsoft makes MCP connectors available only with that license, so members who have Copilot Chat without it do not see Ruddr.

If your organization prefers to set up the connection itself, you can create a custom connector instead, as described in [Creating a Custom Connector](#creating-a-custom-connector).

#### Installing Ruddr from Microsoft Marketplace

1. Sign in to Microsoft 365 as an administrator, open the [Ruddr listing in Microsoft Marketplace](https://marketplace.microsoft.com/en-us/product/WA200012456), and select **Get it now** (Figure 1).
2. Confirm your details and select **Get it now** in the dialog (Figure 2). Marketplace takes you to **Settings > Integrated apps** in the Microsoft 365 admin center, where the **Deploy New App** panel opens with Ruddr in it.
3. Select **Next**, then choose who gets Ruddr under **Assign users**: **Just me**, **All users**, or **Specific users or groups** (Figure 3). Start with a few users if you want to try it before rolling it out to everyone.
4. Select **Next**, review the settings, and select **Finish deployment**. The panel reports **Deployment completed** (Figure 4).

![Get Ruddr from Microsoft Marketplace](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-1.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=e0f857198898d3658a0181eed85fe689)

Figure 1 - Get Ruddr from Microsoft Marketplace

![Confirm Your Details to Continue](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-2.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=bb28de8cfa2c2caebb1e9b453a2835a0)

Figure 2 - Confirm Your Details to Continue

![Choose Who Gets Ruddr](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-3.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=dc327d4f1f8fb92d70b15e8d64ee8ebe)

Figure 3 - Choose Who Gets Ruddr

![The Ruddr Deployment Completed](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-4.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=72caaaa85bfee560cbfc8b7a5454c76f)

Figure 4 - The Ruddr Deployment Completed

Ruddr then appears in Copilot for the users you assigned. It can take a few minutes to show up.

#### Connecting

Each member connects once for themselves, from a Copilot chat on the web, in Teams or in Outlook.

1. Select the **+** (Add content) button in the message box, then **Change data sources**.
2. Find **Ruddr** in the **Select sources** dialog and select **Connect** (Figure 5).
3. In the **Connect Ruddr** dialog, select **Continue to Ruddr** (Figure 6).
4. Sign in to Ruddr if asked, choose the workspace to connect, and select **Authorize** on Ruddr's consent page (Figure 7). See [Connecting an Application](https://help.ruddr.io/integrations/ai-connectors-overview.md#connecting-an-application) for what it is asking.

![Connect Ruddr from the Select Sources Dialog](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-5.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=e10a3ac825345ee01f6fe74171e19912)

Figure 5 - Connect Ruddr from the Select Sources Dialog

![Continue to Ruddr from the Connect Ruddr Dialog](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-6.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=e128d2bb3900a1d85ae9e66f241a71ea)

Figure 6 - Continue to Ruddr from the Connect Ruddr Dialog

![Authorize Microsoft 365 Copilot in Ruddr](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-7.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=3ae654cf7c1e4e2a1f18bf2b2ebb45bc)

Figure 7 - Authorize Microsoft 365 Copilot in Ruddr

The popup closes, Copilot confirms that Ruddr is now connected, and the Ruddr row shows a toggle, switched on (Figure 8). The member can now ask questions like "Using Ruddr, list my projects" and get answers from your workspace. Logging time from Copilot is not available yet; Microsoft is still rolling out support for actions that change data.

![Ruddr Connected in the Select Sources Dialog](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-8.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=ddec8e723de3d7cff5c19765948744c3)

Figure 8 - Ruddr Connected in the Select Sources Dialog

From then on, Copilot acts as that member. A member can only connect if they have the Ruddr Assistant enabled on their [member profile](https://help.ruddr.io/workspace-administration/member-profile.md), and once connected they see exactly the data their [security role](https://help.ruddr.io/workspace-administration/security-roles.md) allows. Members of your Microsoft 365 organization who are not members of your Ruddr workspace cannot connect at all.

> [!NOTE]
>
> In the first few minutes after Ruddr is deployed or a connector is created, **Connect** can fail with "Something went wrong while connecting the source". Wait a little and try again from the same sources menu.

> [!NOTE]
>
> If Ruddr's consent page says that an application can only be connected by a member signed in to Ruddr directly, the browser is in a Ruddr administrator's impersonation session. Sign out, sign in to Ruddr as yourself, and connect again.

If your organization ends up with more than one Ruddr entry, a member can check which connector answered. Type `-developer on` in the chat, ask the question again, and open **Agent debug info** — **Executed actions** lists each call with the connector's id.

#### Creating a Custom Connector

Instead of installing the Marketplace app, an administrator can add Ruddr to Copilot as a custom MCP connector, using the Ruddr server address:

```text theme={null}
https://www.ruddr.io/api/mcp
```

A custom connector shows a generic **RU** icon in Copilot instead of the Ruddr logo, because Microsoft does not let you upload an icon for one. Members connect to it the same way, as described in [Connecting](#connecting).

> [!WARNING]
>
> Do the setup signed in to Microsoft 365 as the account that created your Microsoft 365 organization. When an administrator added to the organization later runs it, **Authorize** can fail with "Something went wrong. Please try again." even with the Global Administrator role, while the same steps work for the original account.

Setup has three parts, in this order: register Ruddr as an OAuth client to get a client ID and secret, use those to create an OAuth client registration in the Teams Developer Portal, and then create the connector in the Microsoft 365 admin center.

Microsoft's settings and menu labels change from time to time, so treat Microsoft's own documentation as the authority on the screens themselves — what follows is what to enter when you get there.

##### Registering Ruddr as an OAuth Client

Copilot asks for an OAuth client ID and secret of your own, so you register one for your organization. Ruddr has no screen for this. Run the following command once, from any terminal.

> [!NOTE]
>
> Claude and ChatGPT register themselves with Ruddr automatically when you add Ruddr, through a standard called dynamic client registration. Microsoft 365 Copilot does not support it yet, which is why this one-time command is needed. Once Microsoft adds support, this step and the Developer Portal registration below will no longer be necessary.

```bash theme={null}
curl -s -X POST https://www.ruddr.io/api/oauth/register -H 'Content-Type: application/json' -d '{"client_name":"Microsoft 365 Copilot","redirect_uris":["https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_post","scope":"mcp:read mcp:write"}'
```

The response contains a `client_id` and a `client_secret`. The secret is shown this one time only, so copy both somewhere safe before you close the terminal — you will need them in the next step.

> [!NOTE]
>
> The `mcp:write` scope covers actions such as logging time and opening support tickets. Copilot does not offer them yet, and they become available without a new setup once Microsoft enables them. To keep Copilot to answering questions for good, use `mcp:read` alone here and in the registration below.

##### Creating the OAuth Client Registration

The client ID and secret do not go into Copilot directly. They go into an OAuth client registration in the Teams Developer Portal, which hands back a registration ID that Copilot asks for as the **Reference ID**.

1. Go to the [Developer Portal's OAuth client registration tool](https://dev.teams.microsoft.com/tools/oauth-configuration) and select **Register client**.
2. Enter a **Registration name** — `Ruddr` is a good choice — and `https://www.ruddr.io` as the **Base URL**.
3. Set **Restrict usage by org** to **My organization only**, and **Restrict usage by app** to **Any Teams app**.
4. Enter the **Client ID** and **Client secret** from the previous step.
5. Enter `https://www.ruddr.io/api/oauth/authorize` as the **Authorization endpoint**, and `https://www.ruddr.io/api/oauth/token` as both the **Token endpoint** and the **Refresh endpoint**. Ruddr uses the same address for the last two.
6. Enter `mcp:read mcp:write` as the **Scope**, with a space between the two, matching the scope you registered in the previous step.
7. Turn on the **Enable Proof Key for Code Exchange (PKCE)** switch, and leave **Client password authentication method** on **Request body parameters (default)**.
8. Save the registration (Figure 9).

![Register an OAuth Client in the Teams Developer Portal](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-9.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=68aabb8c77b33e5c77889ccb6411eee5)

Figure 9 - Register an OAuth Client in the Teams Developer Portal

Saving generates the OAuth client registration ID. Copy it — that is the Reference ID you enter in the admin center. It is not a secret, unlike the client secret above.

**NOTE:** Ruddr requires PKCE, and Copilot takes its copy of the registration at the moment the connector is created. Turn PKCE on and save before you create the connector. If it is off, **Authorize** fails on a Microsoft error page reporting error `invalid_request`, with `The code_challenge parameter is required` in the address bar, and turning it on afterwards is not picked up right away — Microsoft says changes take up to 15 minutes.

Microsoft documents this form in [Configure OAuth in Developer Portal](https://learn.microsoft.com/en-us/microsoftteams/platform/messaging-extensions/api-based-oauth#configure-oauth-in-developer-portal).

##### Creating the Connector in the Microsoft 365 Admin Center

1. In the Microsoft 365 admin center, go to **Copilot > Connectors** and open the **Gallery** tab.
2. Under **Created by your org**, select the **Create a new connector** tile (Figure 10), then select **Add**.
3. In the **Custom connector** dialog, under **Connect to MCP server**, select **Add**.

![The Create a New Connector Tile in the Gallery](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-10.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=6a2d5cffedee41e6a65d389a25bee6ba)

Figure 10 - The Create a New Connector Tile in the Gallery

The **Connect to MCP server** panel collects the rest.

1. Enter `Ruddr` as the **Display name**, and a short **Description** — the description is required.
2. Enter the Ruddr server address as the **MCP endpoint URL**.
3. Enter `Ruddr` as the **Developer name**, `https://www.ruddr.com` as the **Website URL**, `https://www.ruddr.com/privacy-policy` as the **Privacy policy URL**, and `https://www.ruddr.com/master-subscription-agreement` as the **Terms of use URL**.
4. Choose **OAuth 2.0** as the **Authentication type**. **None** would leave the server unauthenticated, and **Entra SSO** does not apply, because Ruddr is not protected by Microsoft Entra.
5. Paste the OAuth client registration ID into the **Reference ID** field, which appears once OAuth 2.0 is chosen, and select **Authorize** beneath it (Figure 11).
6. Approve the connection in the popup that opens (Figure 12). The popup closes on success and a green check appears beside the Reference ID.
7. Tick the **Notice** checkbox to consent to Microsoft's connector terms, then select **Create**. A **Success** screen reports "Created connection" and "Linking data source".

![Enter the OAuth Client Registration ID as the Reference ID](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-11.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=28b178293908b15da109b8b5cb259c30)

Figure 11 - Enter the OAuth Client Registration ID as the Reference ID

![Approve a Connection Request from Microsoft 365 Copilot](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-12.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=7caf21a8a24bcd0d5346deeebe3ac3f1)

Figure 12 - Approve a Connection Request from Microsoft 365 Copilot

Microsoft says the connection is ready to use in Copilot within about 30 minutes. You can also roll it out in stages, to selected users or groups first rather than to everyone at once.

To check on it, open **Copilot > Connectors > Your Connections** and select **Ruddr**. Its **Status** reads **Ready** once it is set up (Figure 13).

![The Ruddr Connector Ready in Your Connections](https://mintcdn.com/ruddr-help/g5VfhIdtduL3azS8/images/ai-connectors-microsoft-copilot-setup-13.png?fit=max\&auto=format\&n=g5VfhIdtduL3azS8\&q=85\&s=56880c069101538500e52b7ab26104bf)

Figure 13 - The Ruddr Connector Ready in Your Connections

Members then connect as described in [Connecting](#connecting).

#### Removing the Connection

To remove the Marketplace app, an administrator opens **Settings > Integrated apps** in the admin center, selects **Ruddr**, and removes it. A custom connector is removed from **Copilot > Connectors** instead, though the admin center's list of MCP connections does not always show custom connectors. Either way, the authorization itself lives in Ruddr, so the reliable per-member cut-off is for the member to delete the connection from their [Connected Apps](https://help.ruddr.io/integrations/ai-connectors-overview.md#managing-your-connected-apps) page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.