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
  • The MCP URL
  • Connect an MCP client
  • Build a custom MCP client (SDK)
  • Build a custom MCP client (raw protocol)
  • Custom headers
  • Common issues
  • Next
BuildConnecting agents

MCP integration

Connect an MCP client to Agent Handler, or build your own client.
Was this page helpful?
Previous

Link customization

Next

Custom MCP servers

Agent Handler exposes its tools over MCP. Most agent runtimes - Claude Desktop, Cursor, Windsurf, VS Code, ChatGPT - speak MCP natively, so connecting them is a matter of pasting a URL into a config file. If you’re building your own agent runtime, this page also covers the wire protocol.

Prerequisites

You need three things, all from your dashboard.

  • Tool Pack ID. From the Tool Packs page; copy from the URL of the pack you want to expose.
  • Registered User ID. From the Registered Users page; use a test user for development.
  • Access Key. Production key for production users, test key for test users - they don’t mix. See Access Keys.

The MCP URL

Every MCP connection points at this URL pattern:

https://ah-api.merge.dev/api/v1/tool-packs/<TOOL_PACK_ID>/registered-users/<REGISTERED_USER_ID>/mcp

The URL identifies what tools (the Tool Pack) and whose credentials (the Registered User). The Access Key in the Authorization header authorizes the call. All three values are needed on every connection.

For the Context layer for employees setup, there’s a simplified URL that handles Tool Pack and user resolution through SSO instead.

Connect an MCP client

Claude Desktop
Cursor
Windsurf
VS Code
Other clients

Open Settings → Developer → Edit Config and paste:

claude_desktop_config.json
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<TOOL_PACK_ID>/registered-users/<REGISTERED_USER_ID>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<YOUR_API_KEY>"
14 }
15 }
16 }
17}

Restart Claude Desktop. The first launch downloads mcp-remote (Node 20+ required).

Build a custom MCP client (SDK)

Use the official MCP SDK when your agent is a custom runtime. Anthropic ships an SDK in both Python and TypeScript - both handle the JSON-RPC framing, session ID generation, and streaming response handling.

Python
TypeScript
agent_runtime.py
1import asyncio
2from mcp.client.session import ClientSession
3from mcp.client.streamable_http import streamablehttp_client
4
5API_KEY = "<YOUR_API_KEY>"
6TOOL_PACK_ID = "<TOOL_PACK_ID>"
7REGISTERED_USER_ID = "<REGISTERED_USER_ID>"
8
9async def run():
10 url = (
11 f"https://ah-api.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}"
12 f"/registered-users/{REGISTERED_USER_ID}/mcp"
13 )
14 headers = {"Authorization": f"Bearer {API_KEY}"}
15
16 async with streamablehttp_client(url, headers=headers) as (read, write, _):
17 async with ClientSession(read, write) as session:
18 await session.initialize()
19 tools = await session.list_tools()
20 print(tools)
21
22 result = await session.call_tool(
23 "weather__get_forecast",
24 {"location": "Stockholm", "days": 3},
25 )
26 print(result)
27
28asyncio.run(run())

For custom transport behavior or a runtime that has no SDK, build directly against the wire protocol below.

Build a custom MCP client (raw protocol)

MCP is JSON-RPC 2.0 over HTTP. Three core methods cover the agent surface.

Python
TypeScript
custom_client.py
1import uuid
2import aiohttp
3
4class MCPClient:
5 def __init__(self, url: str, api_key: str):
6 self.url = url
7 self.session_id = str(uuid.uuid4())
8 self.request_id = 0
9 self.headers = {
10 "Authorization": f"Bearer {api_key}",
11 "Content-Type": "application/json",
12 "Accept": "application/json, text/event-stream",
13 "Mcp-Session-Id": self.session_id,
14 }
15
16 async def _send(self, method: str, params: dict | None = None) -> dict:
17 self.request_id += 1
18 payload = {"jsonrpc": "2.0", "id": self.request_id, "method": method}
19 if params:
20 payload["params"] = params
21
22 async with aiohttp.ClientSession() as http:
23 async with http.post(self.url, headers=self.headers, json=payload) as resp:
24 if "Mcp-Session-Id" in resp.headers:
25 self.session_id = resp.headers["Mcp-Session-Id"]
26 self.headers["Mcp-Session-Id"] = self.session_id
27 resp.raise_for_status()
28 return await resp.json()
29
30 async def initialize(self):
31 return await self._send("initialize", {"protocolVersion": "2024-11-05"})
32
33 async def list_tools(self):
34 return await self._send("tools/list")
35
36 async def call_tool(self, name: str, arguments: dict):
37 return await self._send("tools/call", {"name": name, "arguments": arguments})

The session ID rotates on Agent Handler’s side - read it back from the response header and use the new value for subsequent requests.

For streaming responses (large tool outputs), set Accept: text/event-stream and parse the response as Server-Sent Events. The SDKs handle this automatically; the raw clients above don’t.

Custom headers

Any header you send with an X- prefix is captured as metadata on the tool call and shown in the Tool Call Logs. Useful for tracing - set X-Chat-Id to your session ID and you can filter logs to one conversation. See Custom headers for MCP.

Common issues

  • Tools not appearing in the client. Restart the client after editing config. Some clients cache aggressively; a hard restart usually fixes it. Check the client’s MCP log for connection errors.
  • 401 on every call. Double-check the Authorization header format (Bearer is required and case-sensitive) and that the API key matches the Registered User’s environment.
  • Session ID mismatch errors. Capture and re-use the session ID from response headers. Don’t generate a new one per request.

For a full troubleshooting catalog, see Troubleshooting.

Next

For command-line tool search and execution, use the Merge CLI.