Skip to main content

Installing the BetterUp Agent in Microsoft 365 Copilot

BetterUp® members can now run AI coaching sessions and manage their coaching right inside Microsoft 365 Copilot. This article covers how a Microsoft 365 administrator installs the BetterUp Agent in their own tenant, so members can read their coaching information, start a coaching conversation, and book or cancel a session, all without leaving Copilot or Teams.

The agent uses each member's own BetterUp account, so it only ever sees what they see. Reading data happens automatically. Anything beyond reading, like booking a session, asks the member to confirm first.

Everything below happens in a browser, across three Microsoft sites. There is nothing to install locally and no command line involved. Plan on about 30 minutes of setup, then up to 24 hours (in rare cases, up to six days) before the agent appears for your members.

Jump to: Setup Instructions | Updating later | FAQs

Setup Instructions

Before you start

Your Customer Success contact sends you two things as follows:

  • A zip file. This is the agent package itself. You do not open or edit it. You upload it as it is and change one field in a browser.
  • A client ID and a client secret. This is one pair for your whole organization, not one per member. You enter it once, and it covers everyone who uses the agent. Each member still signs in with their own BetterUp account and sees only their own data.

The client ID and secret arrive through a secure link rather than email. Treat the secret like a password. Because the pair is org-wide, only you need it. Nobody using the agent ever sees it or is asked for one. You paste it into one field in step 1 and never need it again, so there is no reason to forward it or store it anywhere else.

Let your Customer Success contact know what name you would like your members to see when they approve access. It appears on the consent screen the first time someone uses the agent, so pick something they will recognize. If you have no preference, BetterUp uses your organization's name.

On the Microsoft side you need access to three Microsoft sites. Check all three before you start, since getting access can take longer than the setup itself.

These can be the same person. If they are not, agree who does which part before you begin, so the package does not sit submitted while you track down someone with the right role.

Anyone testing the agent needs a BetterUp account with an active membership and some coaching data. Without it, the agent has nothing to show. Send your Customer Success contact the list of testing accounts so they can be confirmed before you start.

For any additional support, email at support@betterup.co. Include your Registration ID from step 1, your Microsoft tenant ID, and roughly when the failed request happened. Never send the client secret, as it is not required for BetterUp to investigate the issue.

Step 1: Register the connection in the Teams Developer Portal

This step allows the agent sign in to BetterUp. You'll only do it once.

  • Go to https://dev.teams.microsoft.com/home and sign in with your work account. This is Microsoft's Developer Portal for Teams. You do not need a developer license to use it.
  • In the left sidebar, select Tools.
  • Select OAuth client registration. If you have never used this page, the list is empty.
  • Select New OAuth client registration. A form opens.
  • Fill in the form:
    • Registration name: BetterUp Agent
    • Base URL: https://mcp.betterup.co/mcp
    • Restrict usage by organization: choose My organization only.
    • Restrict usage by Teams app: choose Any Teams app. See the warning below.
    • Client ID: the client ID BetterUp sent you.
    • Client secret: the client secret BetterUp sent you.
    • Authorization endpoint: https://app.betterup.co/oauth/authorize
    • Token endpoint: https://app.betterup.co/oauth/token
    • Refresh endpoint: https://app.betterup.co/oauth/token
    • Scope: mcp:member:read, mcp:member:write
    • Enable Proof Key for Code Exchange (PKCE): leave this off.
    • Client password authentication method: choose HTTP Basic authentication. This is not the option that is selected by default.
  • Select Save. The form closes and your registration appears in the list.
  • Copy the Registration ID from the list. You need it in step 3. It is a long string of letters and numbers. It is not a secret, so it is safe to email or paste into a ticket.

There are three specifics settings that are important to be aware of, as they are easy to miss or get wrong:

  1. “Restrict usage by Teams app" must be set to "Any Teams app." This is Microsoft's documented guidance. The setting controls which Teams apps Microsoft lets use the credentials you enter here. "Existing Teams app" allows only the app you name, but for a Model Context Protocol (MCP) connection like ours (the standard Copilot uses to connect to outside services), Microsoft cannot confirm which app is calling and never releases the credentials. Access is still limited by the "Restrict usage by organization" setting above. Reference: Configure OAuth 2.0 authentication (https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/plugin-authentication-oauth#use-the-teams-developer-portal).
  2. The refresh endpoint must be filled in. If you leave it blank, the agent works for about an hour and then stops, and the person using it has no way to recover except signing in again.
  3. Client password authentication method must be HTTP Basic authentication. The form opens with Request body parameters selected instead, and it is easy to scroll past. BetterUp registers your client to expect HTTP Basic, so this has to match or sign-in fails.

If you need to change any of this later, come back to Tools, then OAuth client registration, and select the registration by name. Editing it does not require republishing the agent.

 

Step 2: Import the package

In the Developer Portal, go to Apps, click the Import an app, then click Import zipped package, and choose the zip file which BetterUp sent you.

The app appears in your list with BetterUp as the publisher. You now own this copy of it.

Step 3: Point the package at your registration

Open the app you just imported, navigate to Configure > App package editor > ai-plugin.json.

Find the reference_id line near the bottom. It looks like as below:

"auth": {
    "type": "OAuthPluginVault",
    "reference_id": "a long placeholder value"
}

Replace the placeholder with the Registration ID from step 1, keeping the quotation marks, and save.


 

This step is not optional. The value BetterUp ships is a placeholder that points at nothing. A registration ID includes the ID of the tenant that created it, so BetterUp's own cannot work in your tenant, and yours cannot work in anyone else's.

You can also try the agent now, before anyone else sees it. Select Preview in Teams at the top right. That opens the agent for your own account only, which is the quickest way to confirm the connection works. Step 5 describes what to expect. If something is wrong, it is much easier to fix here than after your organization has it.

Step 4: Publish it to your organization

In the Developer Portal, navigate to Publish > Publish to org > Publish your app. The status changes to Submitted.

The rest happens in two admin centers. A Teams administrator does items 1 to 4 in the Teams admin center. A Global administrator or AI administrator does items 5 and 6 in the Microsoft 365 admin center.

Publishing makes the agent available to everyone in your organization by default, in both admin centers. Items 4 and 6 narrow that down, so do all six before you announce it.

  • Open the app and click Publish. This is the approval step. The page shows a Pending action warning until you do, and then fills in the Published version. Once you publish, the app no longer matches the Submitted filter. Search for it by name if you need it again.

  • Click the Users and groups tab and choose who can use the agent. You can pick everyone, specific groups, or named people.

  • Click the Users tab, and then select Available to option. Choose the same people or groups you picked in the Teams admin center, then click Save.

    Both admin centers must list the same people. The Teams admin center let people add the agent from the Teams store. The Microsoft 365 admin center let them find it in Copilot. If someone is on only one list, they see the agent but get a permissions error when they try to add it.

    There are two things to expect as follows:

  • You cannot install the agent for your people. Each person adds the agent themselves, from Built by your org in Copilot or Built for your org in Teams. Plan a short announcement, otherwise nobody will know it is there.
  • Changes can take up to 24 hours to show up, and in rare cases up to six days. Different apps update at different times. Reference: App centric management to manage user access to Teams apps (https://learn.microsoft.com/en-us/microsoftteams/app-centric-management#add-or-modify-app-availability-for-users).

Step 5: Check and Verify

Open Microsoft 365 Copilot at https://m365.cloud.microsoft/chat. Add the agent from the store under Built by your org, then start a new chat and pick it from the list.


You can also use the agent in Microsoft Teams at https://teams.cloud.microsoft/. On the Teams left bar, select the + (Apps). Then either search for BetterUp in the Apps search box, or find the agent under Built for your org.

The sign-in and the answers are the same in Teams and in Copilot.

The first time you ask the agent for anything, it asks you to sign in. Click the Sign in to BetterUp Agent. You are navigated to a BetterUp sign-in page and then a consent screen listing the two scopes. Each person does this once.

Once you approve, the agent answers from your BetterUp account. The two things below are worth trying before you announce it, because they look quite different from each other.

An answer from your BetterUp data

Ask: What upcoming coaching sessions do I have?

The agent answers in the chat with your own upcoming sessions. An empty answer means the account has no coaching data, not that the connection is broken. This is the quickest way to confirm sign-in worked.

A coaching chat inside Copilot

Ask: I'd like to talk to a BetterUp coach about a challenge I'm facing.

Copilot asks you to confirm before it opens the coaching window. Select Confirm.

A BetterUp AI Coach window opens beside the chat and the coach starts the conversation. You type into that window rather than the main Copilot box, and the coach replies there.

Open in BetterUp, at the top right of the window, moves the conversation to BetterUp if you want to carry on there.

Updating later

When BetterUp sends a new version of the package:

  1. Import the new zip in the Developer Portal, or use Upload file on the existing app.
  2. Paste your Registration ID into ai-plugin.json again. Your OAuth registration does not change, and you do not create a new one.
  3. Publish to org again, and have a Teams administrator publish the update in the admin center.

Most changes BetterUp makes on its own servers, such as how an existing tool works, do not need a new package. Adding a tool, removing one, or changing what a tool is described as doing does need a new package, and BetterUp sends one when that happens.

FAQs

Do we need developers for this?

No. Every step happens in a browser, in the Teams Developer Portal, the Teams admin center, and the Microsoft 365 admin center. There is nothing to install, no command line, and no editing files on your machine.

Is the client secret per person or for the whole organization?

For the whole organization. BetterUp issues one client ID and secret to your tenant. You paste them into the single OAuth client registration in step 1, and that one registration serves everyone. People never see the secret and are never asked to enter one.

What is per person is the sign-in. The first time someone uses the agent, they sign in to their own BetterUp account and approve the two scopes. The agent then reads only that person's data. One shared registration, separate sign-in for each person.

What do the two scopes allow?

mcp:member:read let the agent read that person's own BetterUp information: their sessions, their coaches, their growth insights, and their 360 feedback reports.

mcp:member:write let the agent start a coaching conversation on their behalf, and book or cancel a coaching session. Copilot asks them to confirm first.

Both are member-scoped. The signed in person's own data, nothing else. No access to anyone else's data, and none to organization-wide or administrative data.

What if we need the client ID and secret changed?

Ask BetterUp and you will be sent a new pair through the same kind of secure link. In the Developer Portal, go to Tools, then OAuth client registration, open your registration by name, and paste the new values over the old ones. That is the whole job. You do not create a second registration, your Registration ID does not change, and you do not re-import or republish the package.

Why do we have to paste a Registration ID? Can BetterUp not ship one that works?

No, and this is by design rather than an oversight. A registration ID contains the ID of the tenant it was created in, so a registration made by BetterUp only ever works inside BetterUp. Every organization points the package at its own.

Why must the registration allow any Teams app? We would rather restrict it.

Understandable, but it does not work for this kind of agent. Microsoft's own guidance is that Copilot does not pass the app's ID when it calls an MCP server, so a registration tied to one app has nothing to match against. Everything saves and publishes normally, and then every request fails with a 404.

The registration is still limited in two ways that matter more: it only works inside your organization, and it only works against the BetterUp server named in the Base URL.

Reference: Configure OAuth 2.0 authentication (https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/plugin-authentication-oauth#use-the-teams-developer-portal).

Can we pre-install it so it appears for everyone?

No. You control who is allowed to use it, but people add it themselves, from Built by your org in Copilot or Built for your org in Teams.

Why do tool calls stop working after about an hour?

The refresh endpoint is probably missing from your OAuth client registration. It is the same URL as the token endpoint. Add it in the Developer Portal and sign in again.

Do we need to republish when BetterUp changes its tools?

Sometimes. Changes to how an existing tool works reach you without a new package. The package carries the list of tools and what each one is for, so a new tool, a removed tool, or a changed tool description needs a new version, as do changes to the agent's instructions or its suggested prompts. BetterUp sends a new package when that happens.

Can the conversation starters differ by person?

No. Copilot shows them when the agent opens, before anyone signs in, so they cannot depend on what a person has access to. BetterUp can ship your organization a package with prompts that suit your plan.

How can we see which tool the agent picked, and why?

Type -developer on in the Copilot chat. Each turn then shows debug cards with tool matching, selection, and execution status. This is the fastest way to tell a routing problem apart from a content filter blocking the response.

Someone sees the agent but gets "You don't have permissions to add this agent." Why?

They are on the list in only one admin center. Add them in the other one, using the same people or groups.

Something is not working. Who do we contact?

Email at support@betterup.co. The three things that make a problem quick to diagnose are your Registration ID, your Microsoft tenant ID, and the time of a request that failed. If a specific person is affected, include their BetterUp account email as well. Never send the client secret.

Jump to: Setup Instructions | Updating later | FAQs