mergeapi/merge-agent-handler:latest

schemaVersion: "2"
kind: mixin
name: merge-agent-handler
version: 1.0.1
displayName: Merge Agent Handler
description: Gives a sandboxed agent access to Merge Agent Handler's tool catalog — hundreds of enterprise SaaS tools behind one MCP endpoint — with all third-party credentials held server-side by Agent Handler and the MCP OAuth token held on the host, never in the sandbox.
sourceURL: https://github.com/merge-api/docker-merge-kit
licenses:
    - Apache-2.0
agentInstructions:
    content: |
        ## Merge Agent Handler

        Merge Agent Handler is a single, authenticated gateway to enterprise SaaS
        systems — CRM, HRIS, ATS, ticketing, accounting, file storage, and more —
        exposed as a catalog of tools.

        It reaches you through the sandbox's MCP gateway, so the MCP server you
        see is named `mcp-gateway`, not `merge`. Its tools are named
        `<connector>__<action>`, for example `salesforce__list_accounts` or
        `slack__post_message`.

        ### When to reach for it

        Use Agent Handler whenever a task needs real data or an action in a
        third-party business system rather than in this repository. Typical
        cases: looking up a customer, account, or opportunity; reading or filing
        a ticket; fetching employee or candidate records; posting a message;
        listing or retrieving documents.

        ### Finding the right tool

        **Use `search_tools` first.** Describe what you want to accomplish in its
        `intent` argument. Do not start by listing every tool: the full catalog
        runs to thousands of tools, and a plain tool listing shows only the subset
        already granted to this account.

        `search_tools` returns two groups, and the difference matters:

        - `tools` — granted to this account. You can call these now.
        - `requestable_tools` — real tools that exist but this account cannot
          currently use. They are not missing capabilities.

        So a connector absent from the tool list is not proof the capability does
        not exist. If what you need is in `requestable_tools`, you can call
        `request_tool_access` for it, but the request stays pending until an
        administrator approves it — so tell the user rather than waiting on it.

        A tool returning `reauth_required` means that connector is simply not
        linked yet on the Agent Handler side. Report that; do not try to
        authenticate it yourself.

        Never guess tool names.

        ### Do not authenticate to third-party systems yourself

        Agent Handler holds the credentials for every downstream system and
        brokers the calls on your behalf. You are already authenticated through
        it.

        Because of that:

        - Do not look for, ask the user for, or use API keys, OAuth tokens,
          passwords, or session cookies for Salesforce, Slack, Workday, or any
          other downstream system.
        - Do not try to call those systems' APIs directly. This sandbox's network
          policy only permits `ah-api.merge.dev`, so such attempts will fail — and
          the correct fix is to find the right Agent Handler tool, not to request
          wider network access.
        - Do not attempt to read or exfiltrate the Agent Handler OAuth token. It
          is held on the host, outside this sandbox, by design.

        If a system you need is not in the tool catalog, say so and stop rather
        than routing around Agent Handler.
permissions:
    network:
        allow:
            - ah-api.merge.dev:443