For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
Resources
Log inGet a demo
Get startedConnectorsAPI reference
Get startedConnectorsAPI reference
    • Overview
    • How it works
    • Quickstart
    • Use cases
  • Setup
    • Building an agent
    • Context layer for employees
    • Local development
  • Build
      • MCP integration
      • Custom MCP servers
      • Custom headers for MCP
      • Integrating with Copilot Studio
  • Secure
    • Security Gateway
    • Standard Entity Rules
    • Custom Regex Rules
    • Violations and alerts
    • Rule Tester
  • Observe
    • Tool Call Logs
    • API Request Logs
    • Audit Trail
    • Webhooks
    • Playground
  • Administer
    • Team and roles
    • Single sign-on
    • SCIM provisioning
    • Multi-factor authentication
    • Access Keys
    • Application Credentials
    • Billing and usage
  • Resources
    • Troubleshooting
    • FAQ

Get started

  • Overview
  • Introduction
  • Unified API
  • Linked Account
  • Merge Link
  • Use cases

Implementation

  • Sandboxes
  • SDKs
  • API access
  • Syncing data
  • Writing data
  • Data minimization
  • Supplemental data
  • Errors
  • Integration metadata

API reference

  • ATS
  • HRIS
  • Accounting
  • Ticketing
  • CRM
  • File Storage
  • Knowledge Base
  • Chat

Resources

  • Help Center
  • Merge.dev
  • Changelog
© Merge 2026Terms of usePrivacy policy
UnifiedAgent HandlerGateway
UnifiedAgent HandlerGateway
Resources
Log inGet a demo
On this page
  • Prerequisites
  • Values you will enter in Copilot Studio
  • Step 1: Open the agent’s Tools tab
  • Step 2: Add a new MCP tool
  • Step 3: Configure the MCP server
  • Step 4: Create a connection with your API key
  • Step 5: Verify the connection
  • Troubleshooting
  • Next
BuildConnecting agents

Integrating with Copilot Studio

Learn how to set up Agent Handler as a tool within Copilot Studio.
Was this page helpful?
Previous

Custom headers for MCP

Next

Merge CLI

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:

RequirementWhere to get it
Copilot Studio access with permission to edit the agent’s toolsMicrosoft Copilot Studio admin
Agent Handler Tool Pack IDTool Packs page - see Tool Pack guide
Agent Handler Registered User IDCreated 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.

FieldValue
Server nameAny descriptive name (e.g., Agent Handler)
Server descriptionAny description (e.g., Merge Agent Handler MCP server)
Server URLhttps://ah-api.merge.dev/api/v1/tool-packs/{Tool Pack ID}/registered-users/{Registered User ID}/mcp
AuthenticationAPI key
TypeHeader
Header nameAuthorization
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.

    Copilot Studio agent list with the Create blank agent button highlighted

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

    Copilot Studio agent overview with the Tools tab highlighted

Step 2: Add a new MCP tool

  1. Click Add a tool.

    Tools tab with the Add a tool button highlighted

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

    Add tool dialog with Model Context Protocol option highlighted

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.

Model Context Protocol server form filled out with Agent Handler values, Create button highlighted

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

  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.

    Connect to Agent Handler dialog with API key field highlighted

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

If the tools list is empty or shows an error, see Troubleshooting below.

Troubleshooting

SymptomLikely causeFix
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 serverInvalid or expired API keyGenerate a new API key in the Agent Handler dashboard and update the Connection
404 Not Found from the MCP serverTool Pack ID or Registered User ID in the Server URL is incorrectVerify 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 limitReduce 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.