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
  • What’s supported
  • What’s not supported
  • Registering a server
  • Using the custom Connector
  • Tool discovery and refresh
  • Rotating the auth token
  • When this isn’t the right fit
  • Next
BuildConnecting agents

Custom MCP servers

Bring your own MCP server in as a Connector.
Was this page helpful?
Previous

MCP integration

Next

Custom headers for MCP

When the Connector catalog doesn’t cover what you need - an in-house service, a niche SaaS, a tool you’ve built yourself - you can register a remote MCP server as a custom Connector. Agent Handler discovers its tools automatically and exposes them through the same MCP URL your agent already calls.

The trade-off: you operate the MCP server yourself. Agent Handler doesn’t host third-party code; you point it at your endpoint and Agent Handler proxies calls through.

What’s supported

  • Remote MCP servers reachable at a public HTTPS URL.
  • Static authentication - a single bearer token or API key configured once at Connector creation.

What’s not supported

  • Local MCP servers. CLI-launched servers (npx <package>) need to run on the same machine as the agent. Agent Handler is server-side and can’t reach them.
  • Dynamic OAuth. If your MCP server requires per-user OAuth flows, that’s out of scope. Each Connector has to authenticate with one static token. If you need per-user OAuth for an in-house service, contact the Merge team - it’s case-by-case work.

Registering a server

  1. Open Connectors and click Add new.
  2. Fill in:
    • Name - must be unique across your org’s Connectors.
    • Remote MCP server address - your server’s HTTPS endpoint.
    • Authorization token - the bearer token your server expects. Check your server’s docs for the format.
  3. Save. Agent Handler queries tools/list against the server immediately and populates the Connector’s tool list.

If the initial discovery fails, the Connector is created but with zero tools - the dashboard shows the error. Common causes: HTTPS not reachable from Agent Handler’s network, the token format is wrong, the server doesn’t speak MCP.

Using the custom Connector

Once tools are populated, the Connector behaves like any built-in:

  • Add it to a Tool Pack.
  • Apply description overrides and input overrides per pack.
  • Calls flow through the Security Gateway like any other tool call.
  • Show up in Tool Call Logs the same way.

The only difference is that responses come from your server, not from a third-party API Agent Handler manages.

Tool discovery and refresh

Agent Handler refreshes the tool list periodically. When you add or remove tools on your server, they show up in Agent Handler within a few minutes.

For a manual refresh, open the Connector and click Resync - Agent Handler re-queries tools/list immediately.

Rotating the auth token

When you rotate the static token on your server, update Agent Handler’s stored copy at the same time:

  1. Open the Connector → Application Credentials.
  2. Replace the token.
  3. Save.

Token rotation isn’t graceful - calls in flight at the moment of rotation will fail if they hit Agent Handler with the old token still loaded. For high-volume Connectors, time the rotation for low-traffic windows or accept brief failure.

When this isn’t the right fit

Custom MCP servers are good for internal tools that already speak MCP and for niche third parties where you can run a thin MCP shim in front of their API. Don’t reach for it to work around per-user OAuth (unsupported), to wrap heavy custom logic that should live in your agent, or in place of requesting a Connector for a third-party SaaS we’d build anyway.

Next

Forward Agent Handler events to your own pipeline with Webhooks.