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.

You can register a server from the dashboard or from the API. Use the dashboard for a one-off server. Use the API when you provision Connectors from a script or per environment, or keep them in version control, so a new environment gets the same servers without anyone clicking through a form.

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. OAuth Connectors are registered from the dashboard only; the API accepts no authentication or a static header.

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 from the dashboard

1. Open Connectors and click Add new.
2. 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.
3. 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.

Registering a server with the API

POST /api/v1/connectors/ registers a remote MCP server in one call. It needs an access key with the management:all scope.

The API is stricter than the dashboard about failures. Agent Handler completes the MCP handshake and tools/list before it writes anything, so the call either returns a Connector with its tools already discovered or creates nothing. A script never has to clean up a half-registered Connector with zero tools.

A server with no authentication

curl -X POST https://ah-api.merge.dev/api/v1/connectors/ \
  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Docs",
    "url": "https://mcp.acme.com/mcp"
  }'

auth defaults to {"type": "none"}, so you can leave it out.

A server that expects an API key in a header

Send the key in auth.header. Agent Handler stores the value encrypted at the organization level and never returns it, and every user of the Connector reaches the server with that one key.

curl -X POST https://ah-api.merge.dev/api/v1/connectors/ \
  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Docs",
    "slug": "acme_docs",
    "url": "https://mcp.acme.com/mcp",
    "auth": {
      "type": "secret",
      "header": {
        "key": "Authorization",
        "value": "Bearer acme_live_8f2c1e"
      }
    }
  }'

The same request in Python:

import os
import requests
response = requests.post(
    "https://ah-api.merge.dev/api/v1/connectors/",
    headers={"Authorization": f"Bearer {os.environ['MERGE_AGENT_HANDLER_API_KEY']}"},
    json={
        "name": "Acme Docs",
        "slug": "acme_docs",
        "url": "https://mcp.acme.com/mcp",
        "auth": {
            "type": "secret",
            "header": {"key": "Authorization", "value": os.environ["ACME_MCP_TOKEN"]},
        },
    },
    timeout=30,
)
response.raise_for_status()
connector = response.json()
print(connector["slug"], [tool["name"] for tool in connector["tools"]])

A 201 returns the Connector with its discovered tools:

{
  "id": "084fce8e-43d3-472a-8227-e28553e73aa0",
  "name": "Acme Docs",
  "slug": "acme_docs",
  "description": "",
  "source_url": "https://mcp.acme.com/mcp",
  "categories": [],
  "auth_options": [],
  "source": "external_mcp",
  "tools": [
    { "name": "search_docs", "description": "Search the Acme documentation corpus.", "credit_type": "simple" },
    { "name": "get_page", "description": "Fetch a single documentation page by id.", "credit_type": "simple" }
  ]
}

Request fields

The slug follows the same naming rules as the dashboard. It can’t match a Connector Merge already ships or a server in the generic MCP catalog. To use a catalog server, add it from the Connectors page instead.

Retries and repeat calls

The endpoint is safe to retry after a timeout you can’t confirm. An identical repeat call for a Connector with no authentication returns 200 and the existing Connector rather than creating a second one. Anything else that targets an existing slug returns 409, including a repeat of a secret Connector, because Agent Handler can’t tell a retry from a key rotation and won’t report a rotation that didn’t happen.

Registration is limited to 60 requests a minute per organization. Each successful registration is recorded in the audit trail as CONNECTOR_IMPORTED.

The full schema is in the API reference: Register a remote MCP server.

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.

From the dashboard:

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

The API has no update call for a registered server. Sending the same registration again with a new key returns 409 rather than replacing the old key. Rotating through the API means deleting the Connector and registering it again, and deleting takes the Connector out of its Tool Packs (see the next section), so you add it back afterward. For a Connector already in use, the dashboard is the shorter path. Use the API path for servers your own provisioning code owns end to end.

Token rotation isn’t graceful. Calls in flight at the moment of rotation 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.

Deleting a server

DELETE /api/v1/connectors/{slug}/ removes a custom Connector and the credentials stored for it, and returns 204. Only Connectors your organization registered can be deleted this way. A Connector Merge ships, or one that belongs to another organization, returns 404.

curl -X DELETE https://ah-api.merge.dev/api/v1/connectors/acme_docs/ \
  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY"

The exception is a Tool Pack that sets an auth scope on the Connector. Then the delete is refused with 409, and the response names the packs holding it:

{
  "error": "The connector acme_docs is still in the tool packs Support agent. Remove it with DELETE /api/v1/tool-packs/{tool_pack_id}/connectors/acme_docs/ for each one, then delete the connector.",
  "tool_packs": [
    { "id": "5b1d6f0e-2c4a-4e8b-9a7d-3f6c2e1b8a90", "name": "Support agent" }
  ]
}

Remove it from each listed pack with Delete a Connector from a Tool Pack, then repeat the delete. Each deletion is recorded in the audit trail as CONNECTOR_DELETED. The schema is in the API reference: Delete a remote MCP server.

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.

Next

Forward Agent Handler events to your own pipeline with Webhooks.