Fresh 2026

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 becomes callable by the Copilot Studio agent on behalf of a specific Registered User.

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 - see Tool Pack guide
Agent Handler Registered User ID	Created via API or dashboard - see Registered Users guide
Agent Handler API Key (production or test)	Merge Agent Handler dashboard

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 and select the agent you want to connect Agent Handler to. If no agent exists yet, click Create blank agent.

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

Step 2: Add a new MCP tool

1. Click Add a tool.

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

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

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.

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

   Bearer {API Key}

   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.

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

If the tools list is empty or shows an error, see 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.