Sharing a gateway with clients

The team that configures an AI agent needs three things from you - where the MCP gateway is, how to authenticate and what tools it serves. The Export link in each gateway's row on the gateway list downloads all three as one server.json document in the official MCP server registry format.

Document contents

{
    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
    "name": "com.example/billing",
    "description": "MCP gateway billing",
    "version": "1.0.0",
    "remotes": [
        {
            "type": "streamable-http",
            "url": "https://api.example.com/mcp/billing",
            "protocolVersions": ["2025-06-18", "2026-07-28"],
            "headers": [
                {"name": "X-API-Key", "description": "API key", "isRequired": true, "isSecret": true}
            ]
        }
    ],
    "_meta": {
        "zato": {
            "tools": [
                {"name": "billing.get-invoice", "description": "...", "inputSchema": {}, "outputSchema": {}}
            ],
            "security": [
                {"name": "partner.key", "type": "apikey"}
            ]
        }
    }
}

• The remotes entry names the endpoint URL and the two protocol revisions the gateway speaks.
• headers lists the HTTP headers clients must send, one per security type assigned to the gateway. Secrets themselves are never exported, only the fact that a header is required and secret.
• The registry format has no top-level place for tools or security definitions, so the full details live under _meta.zato, its extension point - every tool with its description and both schemas, and the names and types of the security definitions. A service assigned to the gateway but not currently deployed is reported with a Not deployed note in place of its schemas.
• The document's name is the host of the server's address in reverse-DNS form plus a slug of the gateway's name.

The externally visible address

The URL in remotes is built from the Zato_Server_Address environment variable, e.g. https://api.example.com - set it on the server to the address clients reach the gateway under. Without it, the export falls back to the server's own IP address and plain HTTP port, which is right for local work and wrong behind any proxy.

Connect a client

Connecting a client takes one command or one configuration block. Claude Code:

claude mcp add --transport http billing https://api.example.com/mcp/billing \
    --header "X-API-Key: the-actual-key"

Clients configured through JSON, e.g. Cursor or Claude Desktop, take the same two facts in their mcpServers block:

{
    "mcpServers": {
        "billing": {
            "url": "https://api.example.com/mcp/billing",
            "headers": {"X-API-Key": "the-actual-key"}
        }
    }
}

The key itself comes from the person who manages the security definitions - the export never contains it.

To connect a copilot to the Zato documentation itself, rather than to your own gateways, see connect your AI copilot.

See also

Learn more