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. Microsoft 365 Copilot reaches outside services through MCP servers. Ruddr is added as one, using the Ruddr server address:
A Microsoft 365 administrator does this once for the whole organization — individual members cannot add an MCP server themselves. Adding Ruddr gives nobody access to Ruddr data on its own; each member connects to Ruddr themselves afterwards.
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: Copilot connectors are read-only. Copilot does not expose Ruddr’s write tools, such as time tracking, even when the write scope is granted — asking for mcp:write only makes the consent page promise something Copilot cannot do.

​
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 as the Scope. The field takes a comma-separated list, so that single value is the whole entry.
  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 1).

Figure 1 - 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 2), then select Add.
  3. In the Custom connector dialog, under Connect to MCP server, select Add.

Figure 2 - 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 3).
  6. Approve the connection in the popup that opens (Figure 4). 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 3 - Enter the OAuth Client Registration ID as the Reference ID

Figure 4 - 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 5).

Figure 5 - The Ruddr Connector Ready in Your Connections

​
Connecting

Your Authorize in the admin center only confirms that the setup works. It does not connect anyone else. 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 6).
  3. In the Connect Ruddr dialog — “Let Copilot securely read your content from Ruddr” — select Continue to Ruddr (Figure 7).
  4. Approve the connection on Ruddr’s consent page, the same screen the administrator saw in Figure 4 — see Connecting an Application for what it is asking.

Figure 6 - Connect Ruddr from the Select Sources Dialog

Figure 7 - Continue to Ruddr from the Connect Ruddr Dialog

The Ruddr row then shows a toggle, switched on, and the member can ask questions like “Using Ruddr, list my projects” and get answers from your workspace. NOTE: In the first few minutes after an administrator creates the connector, Connect can fail with “Something went wrong while connecting the source”. Wait a little and try again from the same sources menu. 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. 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.

​
Removing the Connection

Removing the connector in the admin center stops Copilot from using Ruddr across your organization, though the admin center’s list of MCP connections does not always show custom connectors. 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.