# Connect Claude Code to a gateway

Add an MCP gateway to Claude Code with one command, with an API key or with a sign-in through your identity provider.

Claude Code reaches an [MCP gateway](https://zato.io/docs/ai/mcp/index.html) through one `claude mcp add` command, after which the gateway's tools are available in every session in the project. The command has two forms, and which one you run depends on how the gateway is [secured](https://zato.io/docs/ai/mcp/security.html).

## With an API key {#with-an-api-key}

For a gateway secured with an API key or a static bearer token, the command carries the header:

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

## With OAuth {#with-oauth}

For a gateway with [OAuth](https://zato.io/docs/ai/mcp/oauth.html) on, the command carries the client ID that the person managing your identity provider registered for Claude Code, and the port the sign-in returns to:

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

Without `--client-id`, Claude Code tries to register itself with the provider, which works with Keycloak when dynamic registration is on and never with Entra ID.

## What the identity provider needs {#what-the-identity-provider-needs}

The registration for Claude Code is a public client with one redirect URI, built from the port the command names:

- `http://localhost:8080/callback`

Any free port works, as long as the port in the command and the port in the redirect URI are the same. Claude Code asks for a token for the gateway's URL, so with Entra ID the registration also needs the API's scope among its permissions - the steps are on the [OAuth](https://zato.io/docs/ai/mcp/oauth.html#microsoft-entra-id) page.

## The sign-in {#the-sign-in}

1. Inside Claude Code, run `/mcp`. The gateway is listed as needing authentication.
2. Selecting it opens the browser at your identity provider's sign-in page.
3. After the sign-in, the browser returns to Claude Code and `/mcp` shows the gateway as connected, with its tools.

Claude Code keeps the token and refreshes it on its own until the provider's session ends. `/mcp` is also where the gateway can be signed out of and `claude mcp remove billing` drops it.

## When access is refused {#when-access-is-refused}

A person whose token the gateway does not accept - outside the group the gateway's bearer definition lists, or signed in to the wrong tenant - sees the gateway as failed in `/mcp`, with a 401 in the details, and can start the sign-in again from there. The reason is in the gateway's [audit log](https://zato.io/docs/ai/mcp/audit-log.html), in the **Reason** column of the `auth-failed` event, next to the person's name.

## See also {#see-also}

- [OAuth](https://zato.io/docs/ai/mcp/oauth.html) - How the sign-in works and how to set up Entra ID or Keycloak
- [Sharing with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) - The export with the gateway's address and the other clients' snippets
- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - A gateway built and called from Claude Code, end to end

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