> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Integrating with Copilot Studio

> How to add Agent Handler as an MCP tool in Microsoft Copilot Studio and connect it with your API key.

---

This guide explains how to connect Merge Agent Handler to a Microsoft Copilot Studio agent as a Model Context Protocol (MCP) tool. Once connected, every tool exposed in your Agent Handler [Tool Pack](/merge-agent-handler/implementation-guides/tool-pack) becomes callable by the Copilot Studio agent on behalf of a specific [Registered User](/merge-agent-handler/implementation-guides/registered-users).

In Copilot Studio, an MCP integration has two parts:

* **Tool** - defines the MCP server configuration (server URL, auth type, header name).
* **Connection** - stores the credential (your Agent Handler API key) used by that tool.

You configure the Tool first, then create a Connection that supplies the API key.

## Prerequisites

Before starting, confirm you have all of the following:

| Requirement                                                     | Where to get it                                                                                                                  |
| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| Copilot Studio access with permission to edit the agent's tools | Microsoft Copilot Studio admin                                                                                                   |
| Agent Handler **Tool Pack ID**                                  | [Tool Packs page](https://ah.merge.dev/tool-packs) - see [Tool Pack guide](/merge-agent-handler/implementation-guides/tool-pack) |
| Agent Handler **Registered User ID**                            | Created via API or dashboard - see [Registered Users guide](/merge-agent-handler/implementation-guides/registered-users)         |
| Agent Handler **API Key** (production or test)                  | Merge Agent Handler dashboard                                                                                                    |

> **Note**
>
> If you are using a Test Registered User, you must also use a test API key. If you are using a Production Registered User, you must use a production API key.

## Values you will enter in Copilot Studio

You will paste these exact values into the Copilot Studio "Add a Model Context Protocol server" form. Substitute the bracketed placeholders with the IDs from the Prerequisites table above.

| Field                                                | Value                                                                                                 |
| :--------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| Server name                                          | Any descriptive name (e.g., `Agent Handler`)                                                          |
| Server description                                   | Any description (e.g., `Merge Agent Handler MCP server`)                                              |
| Server URL                                           | `https://ah-api.merge.dev/api/v1/tool-packs/{Tool Pack ID}/registered-users/{Registered User ID}/mcp` |
| Authentication                                       | `API key`                                                                                             |
| Type                                                 | `Header`                                                                                              |
| Header name                                          | `Authorization`                                                                                       |
| API key value (entered when creating the Connection) | `Bearer {API Key}`                                                                                    |

## Step 1: Open the agent's Tools tab

1. Open [Copilot Studio](https://copilotstudio.microsoft.com) and select the agent you want to connect Agent Handler to. If no agent exists yet, click **Create blank agent**.

   ![Copilot Studio agent list with the Create blank agent button highlighted](/_fern-img/a180fb9a3eda5aecba9ae67f37f1332a5c5d13fd168caed74c5d0ac8a05dc520.webp)

2. Inside the agent, click the **Tools** tab in the top navigation.

   ![Copilot Studio agent overview with the Tools tab highlighted](/_fern-img/f8423c33d4531ca27cee7033013de899426787599f0f2d65e7205d9d65889903.webp)

## Step 2: Add a new MCP tool

1. Click **Add a tool**.

   ![Tools tab with the Add a tool button highlighted](/_fern-img/4e4e2084682fe0c3dd2dcc2085745af927de05a907739eb3d7d05c003fcaed76.webp)

2. In the "Add tool" dialog, select **Model Context Protocol**.

   ![Add tool dialog with Model Context Protocol option highlighted](/_fern-img/846788a2dd7fd5cc9fe70edbbc77b0e376460b52bbe463bd86b2e7c182e3a613.webp)

## Step 3: Configure the MCP server

In the "Add a Model Context Protocol server" form, enter the values from the [Values you will enter in Copilot Studio](#values-you-will-enter-in-copilot-studio) table:

* **Server name:** any descriptive name
* **Server description:** any description
* **Server URL:** `https://ah-api.merge.dev/api/v1/tool-packs/{Tool Pack ID}/registered-users/{Registered User ID}/mcp`
* **Authentication:** select **API key**
* **Type:** select **Header**
* **Header name:** `Authorization`

Click **Create**.

![Model Context Protocol server form filled out with Agent Handler values, Create button highlighted](/_fern-img/342f3b751e3834825c343ecb5cc6e5c3fc72a3d5563a840302f5d84dd3a82bb5.webp)

## Step 4: Create a connection with your API key

After clicking Create, you will be prompted to attach a Connection (this is what stores your API key).

1. In the "Connection" dropdown, click **Create new connection**.

   ![Add tool dialog showing the Create new connection option](/_fern-img/cba8a549f2f03244d9d220f5adf34be10e64a5ada90502bcba3d009e36233dc6.webp)

2. In the "Connect to Agent Handler" dialog, paste your API key in the format below, then click **Create**.

   ```
   Bearer {API Key}
   ```

   > **Warning**
   >
   > The value must include the `Bearer ` prefix (with a trailing space) before your API key. Without it, requests to Agent Handler will fail with `401 Unauthorized`.

   ![Connect to Agent Handler dialog with API key field highlighted](/_fern-img/8befa3168d73a23986f45fb97b46b8c38e487cff03a7fc12a701065e409401c3.webp)

## Step 5: Verify the connection

Open the tool you just created. On the Tool description page, the **Tools** section should list the tools exposed by your Agent Handler Tool Pack (for example, `cms_coverage__list_local_coverage_articles`).

![Tool description page showing Agent Handler tools enabled in Copilot Studio](/_fern-img/a104dab6efa535e794a1ba6a993b6337ec1d4ebeea62816c58931461761ebc01.webp)

If the tools list is empty or shows an error, see [Troubleshooting](#troubleshooting) below.

## Troubleshooting

| Symptom                                                             | Likely cause                                                                                        | Fix                                                                                                              |
| :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| Tool list is empty or shows "Couldn't retrieve the requested items" | API key missing the `Bearer ` prefix, or the key is for the wrong environment (test vs. production) | Edit the Connection and re-enter the key as `Bearer {API Key}`, matching the environment of your Registered User |
| `401 Unauthorized` from the MCP server                              | Invalid or expired API key                                                                          | Generate a new API key in the Agent Handler dashboard and update the Connection                                  |
| `404 Not Found` from the MCP server                                 | Tool Pack ID or Registered User ID in the Server URL is incorrect                                   | Verify both IDs in the Agent Handler dashboard and update the Server URL on the Tool                             |
| Copilot Studio shows "Limiting number of tools to 70"               | Tool Pack exposes more than Copilot Studio's per-tool limit                                         | Reduce the number of tools enabled on the Tool Pack, or split into multiple Tool Packs                           |

## Next

Set up data-loss prevention rules for tool calls with the [Security Gateway](/merge-agent-handler/secure/security-gateway).