This guide walks you through setting up Merge Agent Handler for an embdded agent product: an agent-powered product that your customers use, where each customer connects their own third-party accounts.

Constructing the Agent Handler MCP URL

The following key components make up the Agent Handler MCP URL, the entry point for connecting users to your selected connectors:

• API key — Authenticates your requests to Merge Agent Handler
• Tool Pack — Defines which connectors and tools are available
• Registered User — Identifies the user interacting with the agent

1
{
2
  "agent-handler": {
3
    "url": "https://ah-api.merge.dev/api/v1/tool-packs/[YOUR_TOOL_PACK_ID]/registered-users/[YOUR_REGISTERED_USER_ID]/mcp",
4
    "headers": {
5
      "Authorization": "Bearer [YOUR_API_KEY]"
6
    }
7
  }
8
}

API key

For any request you make when communicating with Merge Agent Handler, you will need an API key. You can find and manage your API keys here:

Tool Pack

Set up the connectors you want available to customers via Tool Packs dashboard. There, you can scope the tools that are available to your users.

Registered User

Registered Users are how Agent Handler isolates credentials and identifies the user interacting with the agent. Each Registered User contains the credentials available for making authenticated tool calls on their behalf.

Set up a POST request to register the user:

POST https://ah-api.merge.dev/api/v1/registered-users

Request body

1
{
2
  "origin_user_id": "customer_A_uuid_1234",
3
  "origin_user_name": "Yash Gogri"
4
}

Response

1
{
2
  "registered_user_id": "f9813dd5-e70b-484c-91d8-00acd6065b07"
3
}

Use the returned registered_user_id as part of your MCP URL when the given Registered User begins to interact with your agent.

Connecting your users

List your connectors

You can surface the available connectors to your user via the /connectors or /tool-packs endpoint.

Authentication

Merge’s Link integration enables users to authenticate access to Connectors. You can embed it in your application by following the guide: Merge Link

Or return it as a URL in your agent’s response to your user: Magic Link