Connect Claude to the AI Identity Gateway

Connect Claude Desktop, Claude Code, or claude.ai to the AI Identity Gateway so that Claude can discover and invoke MCP tools with full identity, authentication, and authorization on every call. When Claude connects to the AI Identity Gateway as an MCP client, it goes through the standard OAuth discovery flow — discovering the authorization server from the Gateway’s protected resource metadata (RFC 9470), authenticating the user, and obtaining an access token. From there, Claude can discover and invoke any MCP tools the Gateway exposes through MCP Bridge or MCP Proxy apps.

How Claude’s Token Works

Claude authenticates the user and sends a standard OAuth access token where the sub claim is the authenticated user. The token does not include delegation semantics — there is no act claim or separate agent identity. From the token alone, the Gateway cannot distinguish “Claude acting on behalf of the user” from “the user directly.” This has implications for how the Gateway evaluates and processes requests:

Inbound authorization policies operate on the token as received. Since Claude does not perform a token exchange before calling the Gateway, inbound OPA policies see only the claims in the access token — by default, user identity claims (sub, email, groups, etc.). The token does not carry agent identity unless the Auth Provider Orchestrator is configured to include it via a buildAccessTokenClaimsSE service extension — for example, by adding the client_id as a custom claim or constructing an act claim to simulate delegation semantics. These values are not cryptographically verified — they are set by the Auth Provider based on the OAuth request context. Care should be taken in the service extension to derive them from a trusted source rather than upstream identity provider attributes that could be manipulated.
Outbound token exchange is where the Gateway adds delegation semantics. When the Gateway performs RFC 8693 token exchange to call upstream APIs via MCP Bridge or MCP Proxy, it can mint delegation tokens with an act claim that includes the agent’s client identity. This gives upstream services visibility into both the user and the agent that initiated the request.

Today, Claude’s client_id is a self-asserted string (e.g., "claude") with no cryptographic proof of the agent’s identity. Because Claude is a closed platform, customers are limited to what Claude supports out of the box — unlike custom agents or other AI clients, which can implement proof of possession, delegation chains, workload attestation, and other advanced identity patterns directly.Several emerging standards aim to address agent identity and delegation:

OAuth Client ID Metadata Documents (CIMD) strengthen client identity by using an HTTPS URL as the client_id. The authorization server fetches and validates the metadata document, providing verified (rather than self-asserted) client identity for policy decisions.
WIMSE (Workload Identity in Multi-System Environments) and SPIFFE (Secure Production Identity Framework For Everyone) provide cryptographically attested workload identity, enabling agents to prove who they are independently of OAuth client registration.
The AI Agent Authentication and Authorization IETF draft ties these together, proposing that agents are workloads with WIMSE/SPIFFE identifiers and that access tokens carry dual identity: client_id as the agent’s verifiable workload identity and sub as the delegated user.

None of these standards solve delegation in isolation, but together they define a path toward tokens that carry both verified agent identity and user identity. Realizing this requires Claude to both establish a verifiable agent identity (via CIMD, WIMSE, or SPIFFE) and perform a token exchange before calling the Gateway — producing a token that carries the user as the subject and the agent as the actor. Without token exchange, the token represents only the user regardless of how the agent identifies itself during the OAuth flow.Until Claude natively supports these patterns, the Gateway’s inbound policies for Claude traffic are limited to the claims present in the access token. By default, this includes only user identity claims (sub, email, groups, etc.). The client_id is available to token minting policies on the Auth Provider Orchestrator but is not included in the access token by default — customers can use service extensions such as buildAccessTokenClaimsSE to add client_id, an act claim, or other context to the token so the Gateway’s inbound policies can evaluate it. This can simulate delegation semantics by constructing an act claim with the client identity as the actor. The service extension should derive these values from a trusted source within the Auth Provider’s request context, not from upstream identity provider attributes that could be manipulated.

Prerequisites

A running AI Identity Gateway — Follow the AI Identity overview to set up the Auth Provider Orchestrator and AI Identity Gateway Orchestrator with at least one MCP Bridge or MCP Proxy app configured. The Gateway must use the Streamable HTTP transport — SSE is not supported by Claude’s connector infrastructure.
OAuth authorization enabled on the MCP Provider — The Gateway’s mcpProvider.authorization.oauth must be enabled so Claude can authenticate. See the AI Identity Gateway reference for configuration details.
Claude Desktop, Claude Code, or a claude.ai account — Any Claude client that supports remote MCP servers works with this guide.

Claude requires an interactive OAuth flow where a user authenticates via the browser. The client_credentials grant type (machine-to-machine OAuth with no user interaction) is not supported by Claude’s MCP connector infrastructure. Register Claude with the authorization_code and refresh_token grant types. See the Anthropic Connectors Directory FAQ for details on Claude’s connector requirements.

Choose a Client Type

When you register Claude as an OAuth client with the Auth Provider Orchestrator, you choose between a confidential client or a public client. This choice affects how Claude authenticates to the authorization server.

	Confidential Client	Public Client
Authentication	Client ID + client secret	Client ID + PKCE (no secret)
Security	Stronger — the secret proves the client’s identity	Weaker — relies on PKCE alone to protect the authorization code flow
Best for	Claude Code (CLI), server-side integrations	Environments where a client secret cannot be securely stored
Grant types	Authorization Code, Refresh Token	Authorization Code (with PKCE), Refresh Token

Use a confidential client whenever possible. Confidential clients authenticate with a client secret, which proves the client’s identity to the authorization server and prevents unauthorized applications from exchanging authorization codes for tokens. Public clients rely solely on PKCE, which protects against code interception but does not authenticate the client itself.OAuth Client ID Metadata Documents (CIMD) address this gap by allowing public clients to use a verifiable HTTPS URL as their client_id, giving the authorization server a way to verify the client’s identity without a shared secret. As the MCP ecosystem adopts CIMD and authorization servers add support, public clients will be able to provide verified identity comparable to confidential clients. Until then, use a confidential client when the deployment allows it, and pair public clients with token minting policies to compensate.

Register Claude as an OAuth Client

Register Claude as an OIDC application on the Auth Provider Orchestrator — the same orchestrator deployment that issues tokens for the AI Identity Gateway. This gives Claude the credentials it needs to authenticate and obtain access tokens.

Confidential Client (Recommended)
Public Client

Console UI
Configuration

Navigate to Applications

Go to Applications in the sidebar and click Create. Select OIDC-based from the application type list.

Set the application name

Enter a Name for the application (e.g., Claude).

Configure client credentials

Enter a Client ID (e.g., claude). Leave Client Authentication Method set to Client Secret. Click Add Client Secret and enter a strong secret or a secret provider reference (e.g., <vault.claude_secret>).

Store client secrets in a secret provider rather than entering them directly. Use secret reference syntax so the Orchestrator resolves the value at runtime.

Add redirect URLs

Click Add Redirect URL and add the redirect URLs for the Claude clients you plan to use:

claude.ai and Claude Desktop: https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback
Claude Code: http://localhost:{PORT}/callback where {PORT} is a fixed port you choose (e.g., http://localhost:29352/callback). Users must pass --callback-port {PORT} when adding the MCP server in Claude Code. See the Connect Claude Code section for details.
Claude Desktop via mcp-remote: http://localhost:{PORT}/oauth/callback (e.g., http://localhost:3334/oauth/callback). Note the /oauth/callback path — this differs from Claude Code’s /callback path.

Configure grant types

Under Grant Types, ensure the following are checked:

Authorization Code (under Recommended and Modern Flows)
Refresh Token (under Recommended and Modern Flows)

Uncheck Client Credentials — it is not needed for Claude’s user-facing OAuth flow.

Configure access token settings

Leave Type set to JWT. Optionally set Lifetime Seconds (default is 1 hour).

Enable refresh tokens

Under Refresh Token Settings, toggle Allow Offline Access on. This lets Claude refresh expired access tokens without requiring you to re-authenticate.

Save

Click Save to create the OIDC application.

Add a new OIDC app to the Auth Provider Orchestrator’s configuration. The client uses the authorization_code and refresh_token grant types with a client secret for authentication.

maverics.yaml

apps:
  - name: claude
    type: oidc
    clientID: claude
    credentials:
      secrets:
        - <claude.clientSecret>
    grantTypes:
      - authorization_code
      - refresh_token
    redirectURLs:
      # claude.ai and Claude Desktop web connectors (routed through Anthropic)
      - https://claude.ai/api/mcp/auth_callback
      - https://claude.com/api/mcp/auth_callback
      # Claude Code -- fixed port via --callback-port (connects directly from user's machine)
      - http://localhost:29352/callback
      # Claude Desktop via mcp-remote -- note /oauth/callback path differs from Claude Code
      - http://localhost:3334/oauth/callback
    accessToken:
      type: jwt
      lifetimeSeconds: 3600
    refreshToken:
      allowOfflineAccess: true
      lifetimeSeconds: 86400
    authentication:
      idps:
        - upstream-idp
    claimsMapping:
      email: upstream-idp.email
      name: upstream-idp.name
      sub: upstream-idp.sub

The redirectURLs include all Claude clients:

claude.ai and Claude Desktop both use https://claude.ai/api/mcp/auth_callback. Include the claude.com variant as well to future-proof the configuration.
Claude Code uses http://localhost:{PORT}/callback. By default, Claude Code picks a random port, but since redirect URLs must be pre-registered, you must choose a fixed port (e.g., 29352) and have users specify --callback-port 29352 when adding the MCP server.
Claude Desktop via mcp-remote uses http://localhost:{PORT}/oauth/callback (note the /oauth/callback path, which differs from Claude Code’s /callback). The default port is 3334.

Store the client secret in a secret provider. Never hardcode secrets in configuration files.

Console UI
Configuration

Navigate to Applications

Go to Applications in the sidebar and click Create. Select OIDC-based from the application type list.

Set the application name

Enter a Name for the application (e.g., Claude Public).

Configure client credentials

Enter a Client ID (e.g., claude-public). You do not need to add a client secret — public clients authenticate using PKCE instead.

Enable public client mode

Under Application Security Settings, toggle Public Client on. This disables client secret authentication and restricts the available grant types to Authorization Code (with PKCE), Refresh Token, and Implicit flows.

Public clients cannot authenticate themselves to the authorization server. Any application that knows the client ID can initiate an authorization flow. Only use public clients when you cannot securely distribute a client secret.

Add redirect URLs

Click Add Redirect URL and add the redirect URLs for the Claude clients you plan to use:

claude.ai and Claude Desktop: https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback
Claude Code: http://localhost:{PORT}/callback where {PORT} is a fixed port you choose (e.g., http://localhost:29352/callback). Users must pass --callback-port {PORT} when adding the MCP server in Claude Code.
Claude Desktop via mcp-remote: http://localhost:{PORT}/oauth/callback (e.g., http://localhost:3334/oauth/callback). Note the /oauth/callback path — this differs from Claude Code’s /callback path.

Leave PKCE enabled

Ensure the Bypass Proof Key for Code Exchange (PKCE) toggle is off (the default). Public clients must use PKCE to protect the authorization code flow.

Configure grant types

Under Grant Types, ensure the following are checked:

Authorization Code (under Recommended and Modern Flows)
Refresh Token (under Recommended and Modern Flows)

Configure access token settings

Leave Type set to JWT. Optionally set Lifetime Seconds (default is 1 hour).

Enable refresh tokens

Under Refresh Token Settings, toggle Allow Offline Access on.

Save

Click Save to create the OIDC application.

Add a new OIDC app to the Auth Provider Orchestrator’s configuration with public: true. Public clients do not use a client secret — they rely on PKCE to protect the authorization code flow.

maverics.yaml

apps:
  - name: claude-public
    type: oidc
    clientID: claude-public
    public: true
    grantTypes:
      - authorization_code
      - refresh_token
    redirectURLs:
      # claude.ai and Claude Desktop web connectors (routed through Anthropic)
      - https://claude.ai/api/mcp/auth_callback
      - https://claude.com/api/mcp/auth_callback
      # Claude Code -- fixed port via --callback-port (connects directly from user's machine)
      - http://localhost:29352/callback
      # Claude Desktop via mcp-remote -- note /oauth/callback path differs from Claude Code
      - http://localhost:3334/oauth/callback
    accessToken:
      type: jwt
      lifetimeSeconds: 3600
    refreshToken:
      allowOfflineAccess: true
      lifetimeSeconds: 86400
    authentication:
      idps:
        - upstream-idp
    claimsMapping:
      email: upstream-idp.email
      name: upstream-idp.name
      sub: upstream-idp.sub

Create a User Flow

After creating the OIDC application, you need to connect it to an identity connector and associate it with the Auth Provider deployment. In the Console UI, this is done by creating a User Flow. In YAML, the authentication.idps field on the app handles this directly.

Console UI
Configuration

Create a User Flow

Navigate to User Flows in the sidebar and click Create. Enter a name (e.g., Claude Auth) and select your Claude application from the Select an application dropdown, then click Create.

Configure the authentication source

On the User Flow page, find the Sign On Policy card and click Edit. Under Authentication, select your identity connector from the Select an authentication source dropdown. This is the identity connector configured on the Auth Provider Orchestrator (e.g., your Entra ID, Okta, or Keycloak connector). Click Save.

Publish the configuration

Navigate to the deployment’s Settings page and click Publish Preview in the footer bar. Review the configuration diff, optionally add a revision note, and click Publish. The Orchestrator picks up the new configuration on its next poll cycle.See Publishing Deployment Configs for details on the publishing lifecycle.

No additional step is needed. The authentication.idps field in the OIDC app configuration (shown in the previous step) already binds the app to your identity connector. The Orchestrator reads this directly from the configuration file.

Connect Claude to the Gateway

Once Claude is registered as an OAuth client and associated with your identity connector, configure your Claude client to connect to the AI Identity Gateway’s MCP endpoint. Claude will automatically discover the authorization server via the Gateway’s protected resource metadata and prompt you to authenticate. How you connect depends on whether the AI Identity Gateway is publicly accessible or on a private network:

Publicly accessible Gateway — All client tabs below work. Use a confidential client (client ID + secret) so the secret proves the client’s identity to the authorization server. The Organization (Team / Enterprise) tab configures a web connector that routes through Anthropic’s infrastructure — both the Gateway and Auth Provider Orchestrator must be reachable from the public internet.
Private / internal Gateway — Select the Claude Code or Claude Desktop tab below. These clients connect directly from your machine, so local and private network URLs work. Use a public client (client ID + PKCE, no secret) to avoid distributing and managing secrets across individual machines.

Claude Code
Claude Desktop
Organization (Team / Enterprise)

Add the AI Identity Gateway as a remote MCP server using the Claude Code CLI. Claude Code connects directly from your machine, so the Gateway does not need to be publicly accessible. The Auth Provider Orchestrator requires pre-registered OAuth clients rather than Dynamic Client Registration (DCR), giving administrators full control over which applications can request tokens. You must pass the OAuth client credentials explicitly when adding the server. You also need --callback-port to fix the OAuth redirect URI to match the pre-registered redirect URL.

Public Client
Confidential Client

If you registered Claude as a public client on the Auth Provider Orchestrator, pass only --client-id. Claude Code uses PKCE (Proof Key for Code Exchange) to protect the authorization code flow — no client secret is needed.

claude mcp add \
  --transport http \
  --client-id claude-public \
  --callback-port 29352 \
  ai-identity-gateway https://your-gateway.example.com/mcp

--client-id claude-public provides the OAuth client ID so Claude Code can authenticate without DCR.
--callback-port 29352 fixes the OAuth redirect URI to http://localhost:29352/callback, matching the redirect URL registered in the OIDC app. Without this flag, Claude Code picks a random port that would not match.

Public clients are a good fit when Claude Code connects directly to a Gateway on a local or private network, since there is no client secret to manage or protect on each user’s machine.

If you registered Claude as a confidential client, pass both --client-id and --client-secret. This is the recommended approach when the Gateway is publicly accessible, as the secret proves the client’s identity to the authorization server.

claude mcp add \
  --transport http \
  --client-id claude \
  --client-secret YOUR_CLIENT_SECRET \
  --callback-port 29352 \
  ai-identity-gateway https://your-gateway.example.com/mcp

Replace YOUR_CLIENT_SECRET with the client secret you configured in the OIDC app on the Auth Provider Orchestrator.

--client-id claude and --client-secret provide the OAuth credentials so Claude Code can authenticate without DCR.
--callback-port 29352 fixes the OAuth redirect URI to http://localhost:29352/callback, matching the redirect URL registered in the OIDC app. Without this flag, Claude Code picks a random port that would not match.

The --client-secret flag stores the secret in Claude Code’s MCP configuration file. For shared or production environments, consider using a secret that can be rotated, and restrict file permissions on the configuration file.

When you start a Claude Code session, Claude connects to the Gateway, discovers the authorization server, and opens your browser for OAuth authentication.Managing the connection:

# List all configured MCP servers
claude mcp list

# View details for the Gateway server, including OAuth config
claude mcp get ai-identity-gateway

# Remove the server
claude mcp remove ai-identity-gateway

Inside a Claude Code session, use the /mcp slash command to check server status, authenticate, and manage connections:

Authenticate — Run /mcp and select the AI Identity Gateway to open the browser OAuth flow. Claude Code stores tokens securely and refreshes them automatically.
View available tools — After authenticating, Claude automatically discovers tools from the Gateway. Ask Claude to list available tools or use /mcp to check the server’s connection status and tool count.
Clear authentication — Run /mcp, select the AI Identity Gateway, and choose Clear authentication to revoke the stored OAuth tokens. Use this when switching users, troubleshooting token issues, or revoking access.
Reauthenticate — After clearing authentication, run /mcp again and select the Gateway to start a fresh OAuth flow.

For more details on Claude Code’s MCP support, see Connect Claude Code to tools via MCP.

Claude Desktop routes all remote MCP traffic through Anthropic’s cloud infrastructure. This means the AI Identity Gateway and Auth Provider Orchestrator must both be publicly accessible for Claude Desktop to reach them — this applies to all remote MCP servers, not just those requiring OAuth. To connect Claude Desktop to the AI Identity Gateway, use one of the following approaches:

Organization web connector (Team / Enterprise plans) — See the Organization (Team / Enterprise) tab. Admins configure the Gateway URL and OAuth credentials centrally. Requires a publicly accessible Gateway.
mcp-remote proxy — Use the open-source mcp-remote package as a local stdio proxy that handles the OAuth flow and MCP communication on your behalf. Because Claude Desktop treats mcp-remote as a local stdio server, the actual network connection to the Gateway happens directly from the user’s machine — so the Gateway does not need to be publicly accessible.

Connect with mcp-remote

mcp-remote is a local stdio proxy that bridges Claude Desktop to remote MCP servers. It handles OAuth discovery, PKCE, token storage, and token refresh locally, then forwards MCP requests to the Gateway. Because it runs as a local process, it connects directly from the user’s machine, bypassing Anthropic’s cloud infrastructure.

mcp-remote is an open-source third-party component not maintained by Strata. Strata does not attest to its security, compliance, or suitability for any purpose, and provides no warranty or guarantees regarding its use. Evaluate it against your organization’s security requirements before deploying.If you are interested in a Strata-supported Claude Desktop extension that can be centrally distributed across your enterprise, contact us. See Building Desktop Extensions with MCPB for background on the desktop extension model.

Open MCP server settings

Open Claude Desktop and navigate to Settings > Developer > Edit Config. This opens the claude_desktop_config.json file.

Add the AI Identity Gateway via mcp-remote

Add an entry under mcpServers that runs mcp-remote as a local stdio server. Use the --static-oauth-client-info flag to provide the pre-registered OAuth client credentials, since the Auth Provider Orchestrator requires pre-registered clients rather than Dynamic Client Registration (DCR). Include a port number after the Gateway URL to fix the OAuth callback port — by default mcp-remote uses port 3334, but you can choose any available port. The redirect URL registered in the OIDC app must match http://localhost:{PORT}/oauth/callback.Use --transport http-only since the AI Identity Gateway uses Streamable HTTP. Without this flag, mcp-remote defaults to http-first which attempts an SSE fallback on failure, potentially causing duplicate connections and authentication issues.

Public Client
Confidential Client

If you registered Claude as a public client on the Auth Provider Orchestrator, provide only the client_id. mcp-remote uses PKCE (Proof Key for Code Exchange) to protect the authorization code flow — no client secret is needed.

claude_desktop_config.json

{
  "mcpServers": {
    "ai-identity-gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-gateway.example.com/mcp",
        "3334",
        "--transport", "http-only",
        "--static-oauth-client-info",
        "{\"client_id\":\"claude-public\"}"
      ]
    }
  }
}

Public clients are a good fit when Claude Desktop connects to a Gateway on a local or private network, since there is no client secret to manage or protect on each user’s machine.

To avoid JSON escaping issues in claude_desktop_config.json, you can store the OAuth client info in a separate file and reference it with the @ prefix:

oauth_client_info.json

{ "client_id": "claude-public" }

claude_desktop_config.json

"args": [
  "mcp-remote",
  "https://your-gateway.example.com/mcp",
  "--static-oauth-client-info",
  "@/path/to/oauth_client_info.json"
]

If you registered Claude as a confidential client, provide both the client_id and client_secret in the static OAuth client info. This is the recommended approach when the Gateway is publicly accessible, as the secret proves the client’s identity to the authorization server.

claude_desktop_config.json

{
  "mcpServers": {
    "ai-identity-gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-gateway.example.com/mcp",
        "3334",
        "--transport", "http-only",
        "--static-oauth-client-info",
        "{\"client_id\":\"claude\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}"
      ]
    }
  }
}

Replace YOUR_CLIENT_SECRET with the client secret you configured in the OIDC app on the Auth Provider Orchestrator.

The client_secret is embedded in the configuration file in plain text. Restrict file permissions on claude_desktop_config.json and consider using a secret that can be rotated. You can also store the credentials in a separate file and reference it with @/path/to/oauth_client_info.json.

Restart Claude Desktop

Close and reopen Claude Desktop to pick up the new configuration. When you start a conversation, mcp-remote connects to the Gateway, discovers the authorization server via protected resource metadata (RFC 9470), and opens your browser for OAuth authentication. Tokens are stored locally in ~/.mcp-auth/ and refreshed automatically.

For more details on configuring MCP servers in Claude Desktop, see Connect to local MCP servers.

On Claude Team and Enterprise plans, an organization Owner can add the AI Identity Gateway as a managed web connector that is available to all team members. This centralizes the configuration — admins set the Gateway URL and OAuth credentials once, and individual members just click Connect and authenticate with their own identity.

Web connectors route traffic through Anthropic’s infrastructure. The AI Identity Gateway and Auth Provider Orchestrator must both be accessible from the public internet. Local or private network URLs (e.g., localhost, 127.0.0.1, private DNS) will not work with web connectors. For private or internal gateways, use the Claude Code or Claude Desktop tabs instead.

The Add dialog in Organization settings offers both Web and Desktop connector types. Choose Web for the AI Identity Gateway. The Desktop option is for uploading packaged desktop extensions (.mcpb files) that run locally on users’ machines — it is not used for remote MCP servers.

Admin setup:

Open Organization Connectors

In claude.ai, go to Organization settings > Connectors.

Add the AI Identity Gateway as a web connector

Click Add and select Custom > Web. Enter the AI Identity Gateway’s MCP endpoint URL:

https://your-gateway.example.com/mcp

Configure OAuth credentials

Click Advanced settings and enter the OAuth Client ID and OAuth Client Secret from the OIDC app you registered on the Auth Provider Orchestrator. The Auth Provider Orchestrator requires pre-registered OAuth clients rather than Dynamic Client Registration (DCR), so Claude needs these credentials to authenticate.

Add the connector

Click Add. The connector now appears in the organization’s connector list, visible to all team members.

Member setup:Each team member authenticates individually to ensure Claude only accesses tools the member is authorized to use:

Go to Settings > Connectors in claude.ai.
Find the AI Identity Gateway connector (labeled Custom) and click Connect.
Complete the OAuth flow — authenticate with your identity provider when prompted.

Once connected, the Gateway’s MCP tools are available in conversations. Members can enable or disable the connector per conversation.For details on plan requirements and connector management, see Get started with custom connectors using remote MCP.

Harden Token Issuance with Token Minting Policies

The Auth Provider Orchestrator supports OPA token minting policies that evaluate every token request before issuance. These policies add a governance layer on top of OAuth client registration — even after a user authenticates successfully, the Orchestrator can deny or constrain the token based on client identity, grant type, requested scopes, or environmental conditions. This is especially valuable when using public clients. Because public clients authenticate with only a client ID and PKCE (no secret), any application that knows the client ID can initiate an authorization flow. Token minting policies let you enforce additional constraints at the point of token issuance to compensate — for example, restricting which networks can mint tokens for a given client.

Public client is an OAuth term describing how the client authenticates (no secret, PKCE only) — it does not mean the Gateway is publicly accessible. A public client can connect to a Gateway on a private network (e.g., Claude Code or Claude Desktop via mcp-remote connecting to an internal Gateway). Similarly, a publicly accessible Gateway can use confidential clients. The client type and deployment model are independent choices.

Example: Restrict a Private Gateway to Corporate Networks

The following policy ensures that the public client claude-public can only mint tokens when the request originates from the corporate network. This is useful when the Gateway is on a private network and you want to ensure tokens are only issued to users connecting from known internal ranges:

maverics.yaml

apps:
  - name: claude-public
    type: oidc
    clientID: claude-public
    public: true
    grantTypes:
      - authorization_code
      - refresh_token
    authorization:
      tokenMinting:
        accessToken:
          policies:
            - name: restrict-public-client-by-network
              rego: |
                package orchestrator

                default result := {"allowed": true}

                # Only allow the public client to mint tokens from the
                # corporate network.
                result := {"allowed": false, "internal_message": "public client not allowed from this network"} {
                  input.request.oauth.client_id == "claude-public"
                  not net.cidr_contains("10.0.0.0/8", input.source.ip)
                }
    redirectURLs:
      # claude.ai and Claude Desktop web connectors (routed through Anthropic)
      - https://claude.ai/api/mcp/auth_callback
      - https://claude.com/api/mcp/auth_callback
      # Claude Code -- fixed port via --callback-port (connects directly from user's machine)
      - http://localhost:29352/callback
      # Claude Desktop via mcp-remote -- note /oauth/callback path differs from Claude Code
      - http://localhost:3334/oauth/callback
    accessToken:
      type: jwt
      lifetimeSeconds: 3600
    refreshToken:
      allowOfflineAccess: true
      lifetimeSeconds: 86400
    authentication:
      idps:
        - upstream-idp
    claimsMapping:
      email: upstream-idp.email
      name: upstream-idp.name
      sub: upstream-idp.sub

This policy denies token issuance for claude-public unless the request originates from the 10.0.0.0/8 CIDR range. Replace the CIDR with your organization’s internal network range. You can combine multiple net.cidr_contains checks to allow several network ranges.

Source IP checks are a useful defense-in-depth measure but should not be your only security control. Client IPs can be obscured by proxies, VPNs, or NAT, and the input.source.ip value reflects the immediate connection to the Orchestrator, which may be a load balancer or reverse proxy rather than the end user’s machine. Use IP restrictions alongside other controls — such as user authentication, PKCE, and scoped token lifetimes — rather than relying on them in isolation.

Example: Restrict a Public Gateway to Anthropic’s IP Ranges

When the Gateway is publicly accessible and Claude connects via claude.ai or Claude Desktop web connectors, traffic arrives from Anthropic’s published outbound IP ranges. The following policy restricts token issuance to requests originating from these ranges:

maverics.yaml

authorization:
  tokenMinting:
    accessToken:
      policies:
        - name: restrict-to-anthropic-ips
          rego: |
            package orchestrator

            default result := {"allowed": true}

            # Only allow token minting from Anthropic's outbound IP ranges.
            # See https://platform.claude.com/docs/en/api/ip-addresses
            # for the current ranges.
            result := {"allowed": false, "internal_message": "request not from Anthropic IP range"} {
              not anthropic_ip
            }

            anthropic_ip {
              # Anthropic outbound IPv4
              net.cidr_contains("160.79.104.0/21", input.source.ip)
            }

            anthropic_ip {
              # Anthropic outbound IPv6
              net.cidr_contains("2607:6bc0::/48", input.source.ip)
            }

If you also support Claude Code or Claude Desktop via mcp-remote (which connect directly from users’ machines), combine the Anthropic ranges with your corporate network ranges:

maverics.yaml

            anthropic_ip {
              # Anthropic outbound IPv4
              net.cidr_contains("160.79.104.0/21", input.source.ip)
            }

            anthropic_ip {
              # Anthropic outbound IPv6
              net.cidr_contains("2607:6bc0::/48", input.source.ip)
            }

            corporate_ip {
              net.cidr_contains("10.0.0.0/8", input.source.ip)
            }

            result := {"allowed": false, "internal_message": "request not from allowed network"} {
              not anthropic_ip
              not corporate_ip
            }

Token minting policies can inspect any field in the token request, including input.request.oauth.client_id, input.request.oauth.scope, input.request.oauth.audience, input.request.oauth.grant_type, and input.source.ip. See the token minting policy reference for the full list of available input fields.

IP Allowlisting for Public Deployments

When the AI Identity Gateway and Auth Provider Orchestrator are publicly accessible, you can restrict inbound traffic to known IP ranges as an additional layer of protection. Understanding the traffic flow is important for applying restrictions at the right layer:

User’s browser → Auth Provider — During the OAuth authorization step, the user’s browser connects directly to the Auth Provider Orchestrator’s authorize endpoint. This traffic comes from the user’s IP, not Anthropic’s.
Anthropic’s backend → Auth Provider — Token exchange and token refresh requests are made server-side by Anthropic’s infrastructure. This traffic comes from Anthropic’s published outbound IP ranges.
Anthropic’s backend → Gateway — MCP tool calls are routed through Anthropic’s infrastructure. This traffic also comes from Anthropic’s outbound IP ranges.

This means IP restrictions apply differently depending on the component:

Gateway infrastructure-level allowlisting — The Gateway can be locked down to Anthropic’s outbound IP ranges (160.79.104.0/21 for IPv4, 2607:6bc0::/48 for IPv6) since only Anthropic’s backend connects to it for web connectors. Use your cloud provider’s firewall, security groups, WAF, or reverse proxy.
Auth Provider infrastructure-level allowlisting — The Auth Provider cannot be restricted to Anthropic’s IPs alone because the user’s browser must reach the authorize endpoint during the OAuth flow. However, it does not need to be open to the entire internet — organizations can restrict access to Anthropic’s outbound IP ranges plus their own users’ networks using VPNs, corporate IP allowlists, device management policies, or conditional access controls. The key requirement is that both Anthropic’s infrastructure and the user’s device can reach the Auth Provider.
Auth Provider token minting policies — OPA token minting policies evaluate at the token endpoint, where requests come from Anthropic’s backend (for web connectors) or the user’s machine (for Claude Code / mcp-remote). Use the examples above to restrict by source IP at this layer.
Gateway inbound authorization policies — Use OPA policies on the AI Identity Gateway to restrict tool invocations by source IP. This controls who can call tools even with a valid token.

Anthropic publishes stable outbound IP addresses for MCP tool calls from claude.ai and Claude Desktop. See Anthropic IP Addresses for the current ranges. These addresses will not change without notice. For Claude Code and Claude Desktop via mcp-remote, traffic originates from the user’s machine rather than Anthropic’s infrastructure. Whether infrastructure-level IP allowlisting is practical for these clients depends on your network topology and trust domains — organizations with well-defined corporate IP ranges can allowlist those ranges alongside token minting and Gateway authorization policies.

Verify the Connection

After connecting, verify that Claude can discover and invoke tools from the AI Identity Gateway.

Check tool discovery — Ask Claude to list available tools. Claude should display the MCP tools exposed by your MCP Bridge and MCP Proxy apps. Tool names include the namespace prefix (e.g., my_api_listUsers).
Invoke a tool — Ask Claude to call one of the discovered tools. For example: “List all users using the my_api_listUsers tool.” The AI Identity Gateway authenticates the request, evaluates authorization policies, performs token exchange, and returns the result.
Check the Orchestrator logs — The AI Identity Gateway Orchestrator logs show the complete request flow: agent authentication, OPA policy evaluation, token exchange, and upstream API call. Verify that all steps completed successfully.

If Claude cannot discover tools or tool invocations fail, see the troubleshooting sections in the Expose APIs to Agents and Protect MCP Servers guides.

Troubleshooting

OAuth redirect URI mismatch

The redirect URI Claude sends does not match what is configured in the OIDC app’s redirectURLs.Resolution:

Check the Auth Provider Orchestrator logs for the exact redirect_uri value Claude is sending.
Add that exact URI (including scheme, host, port, and path) to the OIDC app’s redirectURLs array.
For claude.ai and Claude Desktop, ensure both https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback are in the redirect URLs list.
For Claude Code, ensure you passed --callback-port when adding the MCP server, and that http://localhost:{PORT}/callback with that port is in the redirect URLs list. Without --callback-port, Claude Code picks a random port that will not match any pre-registered URL.
For Claude Desktop via mcp-remote, ensure http://localhost:{PORT}/oauth/callback is in the redirect URLs list. Note the /oauth/callback path — this differs from Claude Code’s /callback path. The default port is 3334.

Claude cannot discover any tools

If Claude connects and authenticates but sees no tools:

Verify that MCP Bridge or MCP Proxy apps are configured and running on the AI Identity Gateway Orchestrator.
Check that the agent’s token has the required scopes for tool discovery.
Review the AI Identity Gateway Orchestrator logs for errors during tool registration or upstream connection failures.
Confirm that inbound OPA policies do not block tool listing.

Authentication popup does not appear

Token refresh fails after session expires

If Claude’s session stops working after the access token expires:

Verify that the OIDC app’s grantTypes includes refresh_token.
Check that refreshToken.allowOfflineAccess is true in the OIDC app configuration.
Confirm the refresh token has not expired (check refreshToken.lifetimeSeconds).
If using a confidential client, ensure the client secret has not been rotated or revoked since the session was established.

Tokens remain valid after disconnecting in claude.ai

When a user disconnects a connector in claude.ai or Claude Desktop, Anthropic removes the tokens from its systems but does not revoke them at the identity provider. Access and refresh tokens on the Auth Provider Orchestrator remain valid until they expire, and session cookies are not cleared.Resolution:

Set short accessToken.lifetimeSeconds values (e.g., 300—900 seconds) to limit the window of validity after disconnection.
Set refreshToken.lifetimeSeconds to bound how long a refresh token can extend a session.
If immediate revocation is required, revoke the user’s session directly on the Auth Provider Orchestrator or upstream identity provider.

TLS certificate verification fails with mcp-remote

If mcp-remote fails with UNABLE_TO_VERIFY_LEAF_CERTIFICATE or similar TLS errors, the Gateway’s certificate is not trusted by Node.js. This is common with self-signed certificates, internal CAs, or VPN-intercepted connections.Resolution (recommended): Point NODE_EXTRA_CA_CERTS to your organization’s CA certificate file so Node.js trusts the Gateway’s certificate chain:

claude_desktop_config.json

{
  "mcpServers": {
    "ai-identity-gateway": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-gateway.example.com/mcp"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/path/to/your-ca-bundle.pem"
      }
    }
  }
}

Resolution (development only): For local development with self-signed certificates, you can disable TLS verification entirely. Do not use this in production.

claude_desktop_config.json

{
  "mcpServers": {
    "ai-identity-gateway": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-gateway.example.com/mcp"],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables all TLS certificate verification, making the connection vulnerable to man-in-the-middle attacks. Use NODE_EXTRA_CA_CERTS with your organization’s CA certificate for non-development environments.

AI Identity Overview

Set up the Auth Provider Orchestrator and understand agent identity concepts

Expose APIs to Agents

Make REST APIs available to Claude as MCP tools via MCP Bridge

Protect MCP Servers

Add identity governance to existing MCP servers via MCP Proxy

OIDC App Reference

Full configuration reference for OAuth client registration

Anthropic Documentation

Connectors Directory FAQ

Critical reference covering connector architecture, traffic routing, OAuth requirements, token limits, timeouts, and privacy details

Claude Code MCP Configuration

Claude Code docs covering MCP transports, OAuth options, and callback port configuration

Remote MCP on claude.ai

How to add remote MCP servers as connectors on claude.ai, including plan requirements

Building Custom MCP Connectors

Developer guide for building OAuth-protected MCP servers that work with Claude

Building Desktop Extensions

How to package local MCP servers as desktop extensions (.mcpb) for enterprise distribution

MCP Quick Start for Claude Desktop

MCP protocol docs for configuring MCP servers in Claude Desktop

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

Connect Claude to the AI Identity Gateway

How Claude’s Token Works

Prerequisites

Choose a Client Type

Register Claude as an OAuth Client

Create a User Flow

Connect Claude to the Gateway

Connect with mcp-remote

Harden Token Issuance with Token Minting Policies

Example: Restrict a Private Gateway to Corporate Networks

Example: Restrict a Public Gateway to Anthropic’s IP Ranges

IP Allowlisting for Public Deployments

Verify the Connection

Troubleshooting

AI Identity Overview

Expose APIs to Agents

Protect MCP Servers

OIDC App Reference

Anthropic Documentation

Connectors Directory FAQ

Claude Code MCP Configuration

Remote MCP on claude.ai

Building Custom MCP Connectors

Building Desktop Extensions

MCP Quick Start for Claude Desktop

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

​How Claude’s Token Works

​Prerequisites

​Choose a Client Type

​Register Claude as an OAuth Client

​Create a User Flow

​Connect Claude to the Gateway

​Connect with mcp-remote

​Harden Token Issuance with Token Minting Policies

​Example: Restrict a Private Gateway to Corporate Networks

​Example: Restrict a Public Gateway to Anthropic’s IP Ranges

​IP Allowlisting for Public Deployments

​Verify the Connection

​Troubleshooting

​Related Pages

AI Identity Overview

Expose APIs to Agents

Protect MCP Servers

OIDC App Reference

​Anthropic Documentation

Connectors Directory FAQ

Claude Code MCP Configuration

Remote MCP on claude.ai

Building Custom MCP Connectors

Building Desktop Extensions

MCP Quick Start for Claude Desktop

How Claude’s Token Works

Prerequisites

Choose a Client Type

Register Claude as an OAuth Client

Create a User Flow

Connect Claude to the Gateway

Connect with mcp-remote

Harden Token Issuance with Token Minting Policies

Example: Restrict a Private Gateway to Corporate Networks

Example: Restrict a Public Gateway to Anthropic’s IP Ranges

IP Allowlisting for Public Deployments

Verify the Connection

Troubleshooting

Related Pages

Anthropic Documentation