# Sharing a gateway with clients

Give client teams the gateway's address, headers and tools as one downloadable document.

The team that configures an AI agent needs three things from you - where the [MCP gateway](https://zato.io/docs/ai/mcp/index.html) 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 {#document-contents}

```json
{
    "$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](https://zato.io/docs/ai/mcp/index.html#endpoint-behavior) the gateway supports.
- `headers` lists the HTTP headers clients must send, one per [security type](https://zato.io/docs/ai/mcp/security.html) 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](https://zato.io/docs/ai/mcp/tool-schemas.html), 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-with-oauth-on}

A gateway whose [OAuth](https://zato.io/docs/ai/mcp/oauth.html) 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:

```json
{
    "_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-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 {#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](https://zato.io/docs/ai/mcp/oauth.html) 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](https://zato.io/docs/ai/mcp/index.html#clients) says which redirect URI that registration needs.

### Claude Code {#claude-code}

With a header:

```bash
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:

```bash
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](https://zato.io/docs/ai/mcp/clients/claude-code.html) page.

### Cursor {#cursor}

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

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

With OAuth, in the same file:

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

The full walkthrough is on the [Cursor](https://zato.io/docs/ai/mcp/clients/cursor.html) page.

### VS Code {#vs-code}

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

```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:

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

The full walkthrough is on the [VS Code](https://zato.io/docs/ai/mcp/clients/vscode.html) page.

### Claude.ai, Claude Desktop, ChatGPT and Microsoft 365 Copilot {#claudeai-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](https://zato.io/docs/ai/mcp/clients/claude.html), [ChatGPT](https://zato.io/docs/ai/mcp/clients/chatgpt.html) and [Microsoft 365 Copilot](https://zato.io/docs/ai/mcp/clients/microsoft-365-copilot.html) pages show the forms.

The key itself, where a gateway uses one, comes from the person who manages the [security definitions](https://zato.io/docs/ai/mcp/security.html) - 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](https://zato.io/docs/ai/connect-your-copilot.html).

## See also {#see-also}

- [Security](https://zato.io/docs/ai/mcp/security.html) - The definitions behind the headers the document lists
- [OAuth](https://zato.io/docs/ai/mcp/oauth.html) - Sign-in through your identity provider in place of a key
- [Tool schemas](https://zato.io/docs/ai/mcp/tool-schemas.html) - The schemas exported under \_meta.zato
- [Connect your copilot](https://zato.io/docs/ai/connect-your-copilot.html) - Point an AI assistant at the Zato documentation over MCP
- [MCP gateways](https://zato.io/docs/ai/mcp/index.html) - Configuration, endpoint behavior and the governance controls

## Learn more {#learn-more}

- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - Expose Python services as AI tools and connect Claude Code in minutes
- [AI Integrations overview](https://zato.io/docs/ai/) - Both directions of AI traffic in one platform, and where to start
- [MCP gateway reference](https://zato.io/docs/ai/mcp/) - Configuration, endpoint behavior and the governance controls
- [Tool schemas](https://zato.io/docs/ai/mcp/tool-schemas.html) - How a service's docstring and declared I/O become its tool definition
- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - API keys, Basic Auth and bearer tokens for AI agents
- [MCP response controls](https://zato.io/docs/ai/mcp/response-controls.html) - PII removal, prompt-injection safeguards and token-denominated size caps
- [MCP audit log](https://zato.io/docs/ai/mcp/audit-log.html) - What each agent did, when and with what outcome - payloads never recorded
- [MCP alerts](https://zato.io/docs/ai/mcp/alerts.html) - Failing backends, agents stuck in a loop and gateways with too many tools
- [Cost and limits](https://zato.io/docs/ai/cost-and-limits.html) - Every setting that caps AI cost and traffic, with worked examples
- [GitOps for AI integrations](https://zato.io/docs/ai/enmasse.html) - LLM connections and MCP gateways as YAML in version control
- [AI examples](https://zato.io/docs/ai/examples/) - Complete, runnable scenarios - one real-world need per file