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

# Connect Microsoft Copilot

> Set up OnboardMe in Microsoft 365 Copilot and Teams with a Copilot Studio agent. Steps for the person building the agent and for the Microsoft 365 admin.

Microsoft 365 Copilot reaches the OnboardMe MCP server through an agent built in **Microsoft Copilot Studio**. You add OnboardMe as an MCP tool on the agent, publish the agent to Teams and Microsoft 365 Copilot, and your Microsoft 365 admin approves it for your organisation.

Each person who uses the agent signs in with their own OnboardMe account (**Sign in with OnboardMe**, OAuth). The agent then acts as that person, with their role and the access they chose at sign-in, the same as Claude or ChatGPT.

The steps take about 15 minutes. The examples use the ANZ server. Replace it with your [region's URL](/mcp/regions) if your practice is in the UK or South Africa.

## Who does what

| Step | Who |
| - | - |
| Build the agent and add the OnboardMe tool in Copilot Studio | Agent builder (anyone with Copilot Studio access) |
| Sign in to OnboardMe the first time the agent needs it | Each person who uses the agent |
| Allow the connector, approve the agent and roll it out | Microsoft 365, Teams or Power Platform admin |

## Before you start

* **Microsoft 365 Copilot** licences for the people who will use the agent, and access to [Copilot Studio](https://copilotstudio.microsoft.com) for the agent builder.
* An OnboardMe login for everyone who will use the agent.
* The MCP server URL for your region, for example `https://anzmcp.onboardme.app/mcp`.
* Power Platform apps allowed in Teams. Your admin controls this in the [Teams admin center](https://learn.microsoft.com/microsoftteams/manage-power-platform-apps).
* If your organisation uses Power Platform **data policies**, they must allow custom connectors in the agent's environment. Copilot Studio MCP tools are Power Platform connectors, so a policy that blocks custom connectors also blocks OnboardMe.

## 1. Create the agent

1. Sign in to [Copilot Studio](https://copilotstudio.microsoft.com) and choose the environment your admin set up for agents.
2. Select **Create**, then **New agent**. Name it **OnboardMe**.
3. Add instructions that tell Copilot when to use it, for example:
   ```text theme={null}
   You help staff at our accounting practice work in OnboardMe.
   Use the OnboardMe tools to look up clients, leads, proposals, onboardings, bills and payments.
   Always search for a client before acting on it. Ask before creating or sending anything.
   ```
4. Select **Create**.

## 2. Add OnboardMe as an MCP tool

1. Open the agent's **Tools** page and select **Add a tool**.
2. Select **New tool**, then **Model Context Protocol**. The MCP onboarding wizard opens.
3. Fill in the server details:
   | Field | Value |
   | - | - |
   | Server name | `OnboardMe` |
   | Server description | `Clients, leads, proposals, onboardings, eForms, ID verification, bills and payments for our practice in OnboardMe.` |
   | Server URL | `https://anzmcp.onboardme.app/mcp` |
4. Under **Authentication**, choose **OAuth 2.0**, then set **Type** to **Dynamic discovery**.
5. Select **Create**. Copilot Studio finds the OnboardMe sign-in endpoints and registers itself. There is no client ID, secret or callback URL to copy.

Copilot reads the description to decide when to call OnboardMe, so keep it specific to what your team will ask.

## 3. Create your connection

1. On **Add tool**, select **Create a new connection**, then **Create**.
2. A window opens on the OnboardMe consent page, which names the app **Microsoft Copilot Studio**. Sign in, choose the practice, and choose **Read-only** or **Read & write**.
3. Select **Allow**. The window closes and the connection is created.
4. Select **Add to agent**.
5. Open the OnboardMe tool's settings, check **Credentials to use** is **End user credentials**, and save. Each person then signs in as themselves the first time the agent uses OnboardMe.

<Warning>
  Don't switch the tool to **Maker-provided credentials**. Everyone who uses the agent would then act as you, with your role and your practice access.
</Warning>

## 4. Test the agent

In the **Test** pane, ask:

> Validate my OnboardMe connection.

The agent calls `auth_validate` and replies with your name, your practice and whether writes are allowed. Then try a real question, such as *"Find the client Smith and list their proposals"*.

## 5. Publish to Teams and Microsoft 365 Copilot

1. Select **Publish** and confirm.
2. Open **Channels**, select **Teams and Microsoft 365 Copilot**, keep **Make agent available in Microsoft 365 Copilot** ticked, and select **Add channel**.
3. Select **See agent in Teams** to install it for yourself and check it works. In Microsoft 365 Copilot, type **@OnboardMe** to use it.
4. To roll it out, select **Availability options**, then either:
   * **Show to my teammates and shared users** for a small group you've [shared the agent with](https://learn.microsoft.com/microsoft-copilot-studio/admin-share-bots), or
   * **Show to everyone in my org**, then **Submit for admin approval**.

The first time someone asks the agent something that needs OnboardMe, Copilot shows a sign-in card. They sign in to OnboardMe and choose their access, and Copilot keeps the connection after that.

Microsoft's full guide: [Connect and configure an agent for Teams and Microsoft 365 Copilot](https://learn.microsoft.com/microsoft-copilot-studio/publication-add-bot-to-microsoft-teams).

## For Microsoft 365 admins

When the agent builder submits the agent for approval:

1. In the [Teams admin center](https://admin.teams.microsoft.com), go to **Teams apps → Manage apps**, find the **OnboardMe** agent (status **Submitted**), review it and select **Publish**. See [Publish a custom app submitted by a user](https://learn.microsoft.com/microsoftteams/submit-approve-custom-apps).
2. Choose who can install it with an app permission policy, or assign it to specific users and groups.
3. Optional: add it to an **app setup policy** to install and pin it for the team automatically.

The approved agent then appears under **Built for your org** in Teams and in the Microsoft 365 Agent Store.

Also check:

* **Power Platform data policies** allow custom connectors in the agent's environment.
* The OnboardMe tool uses **End user credentials**, so nobody uses the maker's OnboardMe access.

## Read-only agent

To expose only read tools, whatever people choose at sign-in, add `?profile=readonly` to the server URL in step 2:

```text theme={null}
https://anzmcp.onboardme.app/mcp?profile=readonly
```

Build a second agent with the full URL if a smaller group needs to create or send things. Users with the **Read Only** role in OnboardMe always get read access, whichever agent they use.

## Several regions

If your firm has practices in more than one region, add one OnboardMe tool per region, each with its own [server URL](/mcp/regions), and name them clearly, for example **OnboardMe ANZ** and **OnboardMe UK**. People sign in to each region separately.

## Revoke access

* Each person can see and revoke their Copilot connection under **Profile → Connected apps** in OnboardMe, where it's listed as **Microsoft Copilot Studio**.
* Practice administrators can revoke any connection from **Settings → Integrations**. Revocation takes effect within about 30 seconds, and the person is asked to sign in again next time.
* Deactivating a user in OnboardMe also stops their Copilot connection.

## Use an API key instead

If your organisation can't use OAuth connectors, the wizard also accepts **API key** authentication with a practice [API client](/authentication). Everyone using the agent then acts as that API client, not as themselves, so prefer OAuth where you can.

1. Build the header value: the word `Basic`, a space, then `ClientID:ClientSecret` encoded as Base64.

   <Tabs>
     <Tab title="Windows (PowerShell)">
       ```powershell theme={null}
       $pair = "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
       "Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
       ```
     </Tab>

     <Tab title="macOS / Linux">
       ```bash theme={null}
       printf 'Basic %s\n' "$(printf '%s' 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)"
       ```
     </Tab>
   </Tabs>
2. In step 2, choose **API key**, set **Type** to **Header** and the header name to `Authorization`.
3. When you create the connection, paste the value, including `Basic` and the space, and set **Credentials to use** to **Maker-provided credentials**.

Treat the value exactly like the secret. To cut off access, deactivate the API client in OnboardMe.

## Troubleshooting

| Problem | Fix |
| - | - |
| **Model Context Protocol** is missing from **New tool** | The MCP wizard isn't enabled for your tenant or region yet. Ask your admin, or contact Microsoft support. |
| "Could not discover authorization server metadata" | Check the server URL ends in `/mcp` and matches your [region](/mcp/regions). |
| The sign-in window says the application is not recognised | Delete the tool and add it again so Copilot Studio registers again. If it keeps happening, contact [support@onboardme.app](mailto:support@onboardme.app). |
| "You do not have access to this practice" | Your OnboardMe login isn't active in that practice, or the server URL is for a different [region](/mcp/regions). |
| The tool is blocked or can't be added | A Power Platform data policy is blocking custom connectors in this environment. |
| Write tools are missing | You chose **Read-only** at sign-in, your role is **Read Only**, or the URL has `?profile=readonly`. To change your choice, revoke the connection under **Connected apps** and sign in again. |
| `403` on a tool | Your OnboardMe role doesn't allow that action. |
| Teams shows `SystemError` after you republish | Teams is using an old version. See Microsoft's [known issues](https://learn.microsoft.com/microsoft-copilot-studio/publication-add-bot-to-microsoft-teams#known-limitations). |
| `429 Too Many Requests` | You hit the per-user [rate limit](/mcp/authentication#rate-limits). Wait for the `Retry-After` time. |


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