Connect Claude Code to a gateway

Claude Code reaches an MCP gateway 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.

With an API key

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

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

With OAuth

For a gateway with OAuth 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:

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

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

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

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, in the Reason column of the auth-failed event, next to the person's name.

See also

Learn more