Skip to main content
NOTE: The Ruddr Assistant feature 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.
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.

​
Installing Ruddr from Microsoft Marketplace

  1. Sign in to Microsoft 365 as an administrator, open the Ruddr listing in Microsoft Marketplace, 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).

Figure 1 - Get Ruddr from Microsoft Marketplace

Figure 2 - Confirm Your Details to Continue

Figure 3 - Choose Who Gets Ruddr

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 for what it is asking.

Figure 5 - Connect Ruddr from the Select Sources Dialog

Figure 6 - Continue to Ruddr from the Connect Ruddr Dialog

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, and log time by asking Copilot to do it.

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, and once connected they see exactly the data their security role allows. Members of your Microsoft 365 organization who are not members of your Ruddr workspace cannot connect at all.
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.
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:
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.
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.
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.
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 lets members log time and open support tickets from Copilot. To keep Copilot to answering questions, 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 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).

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.
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.

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”.

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

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).

Figure 13 - The Ruddr Connector Ready in Your Connections

Members then connect as described in 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 page.