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.
• 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.