mergeapi/merge-agent-handler:1.0.0

schemaVersion: "2"
kind: mixin
name: merge-agent-handler
version: 1.0.0
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 available in this sandbox as an MCP server
        (typically registered as `merge`). It is a single, authenticated gateway
        to hundreds of enterprise SaaS systems — CRM, HRIS, ATS, ticketing,
        accounting, file storage, and more — exposed as a catalog of tools.

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

        Discover what is actually available by listing the MCP server's tools
        before assuming a capability exists. The catalog depends on which
        connectors the operator has enabled, so it varies between deployments —
        do not 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