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

A gateway with OAuth on

A gateway whose OAuth field is on has people sign in through your identity provider instead of sending a key. Its export lists no Authorization header for the gateway's bearer token definitions and has an oauth block under _meta.zato instead:

{
    "_meta": {
        "zato": {
            "oauth": {
                "scopes": ["openid", "profile", "api://zato-mcp/.default"],
                "resource_metadata": "https://api.example.com/.well-known/oauth-protected-resource/mcp/billing"
            }
        }
    }
}

• scopes is the gateway's oauth_scopes field, one entry per scope.
• resource_metadata is the address of the gateway's protected resource metadata document, which a client reads to find your identity provider. Clients find it on their own from the gateway's 401 response, the export names it so a person can check it.

A gateway may also have an API key or Basic Auth definition in its group next to the bearer token ones, and such a definition still appears under headers as usual.

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 uses 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. Each client has two forms - one with a header, for a gateway secured with an API key or a static bearer token, and one with an OAuth client ID, for a gateway with OAuth on. The client ID is the identifier your identity provider assigned to that client's registration, the person who manages the provider gives it to you, and the page of each client says which redirect URI that registration needs.

Claude Code

With a header:

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

With OAuth, after which /mcp inside Claude Code opens the browser sign-in:

claude mcp add --transport http \
    --client-id <client-id> --callback-port 8080 \
    billing https://api.example.com/mcp/billing

The full walkthrough is on the Claude Code page.

Cursor

With a header, in .cursor/mcp.json:

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

With OAuth, in the same file:

{
    "mcpServers": {
        "billing": {
            "url": "https://api.example.com/mcp/billing",
            "auth": {
                "CLIENT_ID": "<client-id>"
            }
        }
    }
}

The full walkthrough is on the Cursor page.

VS Code

With a header, in .vscode/mcp.json:

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

With OAuth, in the same file:

{
    "servers": {
        "billing": {
            "type": "http",
            "url": "https://api.example.com/mcp/billing",
            "oauth": {
                "clientId": "<client-id>"
            }
        }
    }
}

The full walkthrough is on the VS Code page.

Claude.ai, Claude Desktop, ChatGPT and Microsoft 365 Copilot

These products take the gateway's URL in a form rather than in a file, with a field for the client ID where the identity provider needs one, and the Claude, ChatGPT and Microsoft 365 Copilot pages show the forms.

The key itself, where a gateway uses one, 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