Custom MCP servers

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 that complete an MCP initialize handshake.
MCP protocol revisions 2025-03-26 and 2024-11-05. Agent Handler offers 2025-03-26 first and falls back to 2024-11-05 once for a server that won’t negotiate it.
Static authentication, a single bearer token or API key configured once at Connector creation.
OAuth 2.0 with PKCE, when enabled for your organization. A Connector can then authenticate each user through the Link flow instead of a shared token, and Agent Handler can register an OAuth client with your server automatically through dynamic client registration (RFC 7591). This is gated per organization, so contact the Merge team to turn it on.

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.

Registering a server

Open Connectors and click Add new.
Fill in:
- Name. Unique across your org’s Connectors, and not one of the Connectors Merge already ships. The check is global rather than per organization, so salesforce is taken even if you have never enabled it.
- 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.
Save. Agent Handler runs initialize against the server, then tools/list, and populates the Connector’s tool list.

If the initial discovery fails, the Connector is created but with zero tools, and the dashboard shows the error. Common causes: HTTPS isn’t reachable from Agent Handler’s network, the token format is wrong, the server never completes initialize, or it negotiates a protocol revision Agent Handler doesn’t support.

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:

Open the Connector → Application Credentials.
Replace the token.
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 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. Per-user OAuth is not a reason to avoid a custom server either, since a custom Connector can authenticate each user through Link once the capability is enabled for your organization.

Forward Agent Handler events to your own pipeline with Webhooks.