> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/ai-identity/mcp-bridge) or [MCP Proxy](/guides/ai-identity/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 -- user identity claims (`sub`, `email`, `groups`, etc.) and the `client_id` identifying the OAuth client. The `client_id` is a required claim in JWT access tokens per [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068#name-data-structure), so admins can write policies that target Claude traffic by matching on it (e.g., `input.token.client_id == "claude"`). The token does not carry delegation semantics -- there is no `act` claim distinguishing "Claude acting on behalf of the user" from "the user directly."
* **Outbound token exchange** is where the Gateway adds delegation semantics. When the Gateway performs [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) 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.

> [!NOTE]
>
> 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)**](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
>   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**](https://datatracker.ietf.org/wg/wimse/about/) (Workload Identity
>   in Multi-System Environments) and [**SPIFFE**](https://spiffe.io/) (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**](https://datatracker.ietf.org/doc/draft-klrc-aiagent-auth/)
>   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 can match on `client_id` and user identity claims but
> cannot distinguish delegation from direct access. Customers can use
> [service extensions](/reference/orchestrator/service-extensions) such as
> `buildAccessTokenClaimsSE` to construct an `act` claim that simulates
> delegation semantics by embedding 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](/guides/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](/reference/modes/ai-identity-gateway) for configuration details.
* **Claude Desktop, Claude Code, or a claude.ai account** -- Any Claude client that supports remote MCP servers works with this guide.

> [!NOTE]
>
> 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](https://support.claude.com/en/articles/11596036-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 |

> [!WARNING]
>
> 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)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
> 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](#harden-token-issuance-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)**

**Console UI**

**1. Navigate to Applications**

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

**2. Set the application name**

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

**3. 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/orchestrator/configuration/secret-providers) reference (e.g., `<vault.claude_secret>`).

> [!WARNING]
>
> Store client secrets in a [secret provider](/reference/orchestrator/configuration/secret-providers) rather than entering them directly. Use secret reference syntax so the Orchestrator resolves the value at runtime.

**4. 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](#connect-claude-to-the-gateway) 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.

**5. 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.

**6. Configure access token settings**

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

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

**8. Save**

Click **Save** to create the OIDC application.

**Configuration**

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.

```yaml maverics.yaml theme={null}
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](/reference/orchestrator/configuration/secret-providers). Never hardcode secrets in configuration files.

**Public Client**

**Console UI**

**1. Navigate to Applications**

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

**2. Set the application name**

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

**3. 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.

**4. 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.

> [!WARNING]
>
> 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.

**5. 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.

**6. 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.

**7. 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)

**8. Configure access token settings**

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

**9. Enable refresh tokens**

Under **Refresh Token Settings**, toggle **Allow Offline Access** on.

**10. Save**

Click **Save** to create the OIDC application.

**Configuration**

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.

```yaml maverics.yaml theme={null}
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
```

> [!WARNING]
>
> 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.

Registration is not complete until the application is bound to an identity connector, which tells the Orchestrator which IdP authenticates users. In the Console UI, you finish this from the application's own settings; in YAML, the `authentication.idps` field you already set on the app handles it directly.

**Console UI**

**1. Add the identity connector**

If you haven't already, add your identity connector to the Auth Provider deployment's **Identity Fabric**. Navigate to **Identity Fabric** in the sidebar, click **Create**, and select your IdP's connector type (e.g., Entra ID, Okta, or Keycloak). The connector must exist before you can select it as an application's authentication source.

**2. Open the application's settings**

Navigate to **Applications** in the sidebar and open your Claude application.

**3. Add the connector to the application's resources**

In the application's **Resources** card, click **Edit**, then click **Add Resource** and select the identity connector you added in the previous step. Click **Save**. A connector must be added as a resource before it can be selected as an authentication source.

**4. Configure the authentication source**

Find the **Access Control** card and click **Edit**. From the **Select an authentication source** dropdown, choose the connector you just added, then click **Save**.

**5. 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](/reference/console/config-publishing) for details on the publishing lifecycle.

**Configuration**

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**

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**

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.

```bash theme={null}
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.

**Confidential Client**

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.

```bash theme={null}
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.

> [!WARNING]
>
> 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:**

```bash theme={null}
# 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](https://docs.anthropic.com/en/docs/claude-code/mcp).

**Claude Desktop**

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`](https://github.com/geelen/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`](https://github.com/geelen/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.

> [!WARNING]
>
> `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](https://www.strata.io/contact).
> See [Building Desktop Extensions with MCPB](https://support.claude.com/en/articles/12922929-building-desktop-extensions-with-mcpb)
> for background on the desktop extension model.

**1. Open MCP server settings**

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

**2. 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**

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.

```json claude_desktop_config.json theme={null}
{
  "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.

> [!TIP]
>
> 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:
>
> ```json oauth_client_info.json theme={null}
> { "client_id": "claude-public" }
> ```
>
> ```json claude_desktop_config.json theme={null}
> "args": [
>   "mcp-remote",
>   "https://your-gateway.example.com/mcp",
>   "--static-oauth-client-info",
>   "@/path/to/oauth_client_info.json"
> ]
> ```

**Confidential Client**

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.

```json claude_desktop_config.json theme={null}
{
  "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.

> [!WARNING]
>
> 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`.

**3. 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](https://modelcontextprotocol.io/quickstart/user).

**Organization (Team / Enterprise)**

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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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:**

**1. Open Organization Connectors**

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

**2. 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
```

**3. 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.

**4. 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:

1. Go to **Settings** > **Connectors** in claude.ai.
2. Find the AI Identity Gateway connector (labeled **Custom**) and click **Connect**.
3. 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Verify the Connection

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

1. **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`).
2. **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.
3. **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.

> [!NOTE]
>
> If Claude cannot discover tools or tool invocations fail, see the troubleshooting
> sections in the [Expose APIs to Agents](/guides/ai-identity/mcp-bridge#troubleshooting)
> and [Protect MCP Servers](/guides/ai-identity/mcp-proxy#troubleshooting) guides.

## Harden Tool Access with Inbound Authorization Policies

The AI Identity Gateway Orchestrator evaluates [OPA inbound authorization policies](/guides/security/policies#ai-identity-gateway-opa-authorization) on every MCP tool call before it reaches the upstream service. While token minting policies (below) govern whether a token is issued at all, inbound authorization policies govern what an agent can do with that token -- controlling which tools are accessible, under what conditions, and for which callers.

This is the primary mechanism for enforcing least-privilege access at the tool level. Policies can inspect the tool name, tool arguments, HTTP headers (including the JWT), source IP, and any other field in the [MCP app input schema](/guides/security/policies#mcp-app-input-schema).

### Example: Separate Read and Write Access to Sensitive Data

The following policy allows agents with `hr:read` scope to query employee data, but requires `hr:admin` scope to create or update records. This prevents AI agents from modifying sensitive HR data unless explicitly authorized with elevated permissions:

```yaml maverics.yaml theme={null}
apps:
  - name: hr-api
    type: mcpBridge
    authorization:
      inbound:
        type: opa
        opa:
          name: hr-read-write-separation
          rego: |
            package orchestrator

            default result["allowed"] := false

            # Decode the bearer token's claims. Undefined when the header is
            # absent or is not a JWT, so the rules below fail and deny.
            jwt_payload := jwt.parse_bearer(input.request.http.headers.Authorization)

            # Read-only tools require hr:read scope.
            result["allowed"] if {
              input.request.mcp.tool.params.name in ["listEmployees", "getEmployee"]
              contains(jwt_payload.scope, "hr:read")
            }

            # Write tools require hr:admin scope.
            result["allowed"] if {
              input.request.mcp.tool.params.name in ["createEmployee", "updateEmployee"]
              contains(jwt_payload.scope, "hr:admin")
            }

            result["internal_message"] := sprintf("denied %s for client %s", [
              input.request.mcp.tool.params.name,
              jwt_payload.client_id,
            ]) if {
              not result.allowed
            }

            result["external_message"] := "insufficient permissions for this operation" if {
              not result.allowed
            }
```

See the [Authorization Policies guide](/guides/security/policies#ai-identity-gateway-opa-authorization) for the full input schema, output schema, and additional examples.

## Harden Token Issuance with Token Minting Policies

The Auth Provider Orchestrator supports [OPA token minting policies](/guides/security/policies#configure-opa-token-minting-policies-oidc-provider-only-optional) 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.

> [!NOTE]
>
> **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:

```yaml maverics.yaml theme={null}
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.

> [!NOTE]
>
> 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](https://platform.claude.com/docs/en/api/ip-addresses). The following policy restricts token issuance to requests originating from these ranges:

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

```
package orchestrator

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](/guides/security/policies#configure-opa-token-minting-policies-oidc-provider-only-optional) for the full input schema.

### 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](https://platform.claude.com/docs/en/api/ip-addresses).
* **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](https://platform.claude.com/docs/en/api/ip-addresses) (`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.

> [!TIP]
>
> Anthropic publishes stable outbound IP addresses for MCP tool calls from
> claude.ai and Claude Desktop. See [Anthropic IP Addresses](https://platform.claude.com/docs/en/api/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.

## Troubleshooting

> **OAuth redirect URI mismatch**
>
> The redirect URI Claude sends does not match what is configured in the OIDC
> app's `redirectURLs`.
>
> **Resolution:**
>
> 1. Check the Auth Provider Orchestrator logs for the exact `redirect_uri`
>    value Claude is sending.
> 2. Add that exact URI (including scheme, host, port, and path) to the OIDC
>    app's `redirectURLs` array.
> 3. 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.
> 4. 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.
> 5. 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**
>
> If Claude does not prompt you to authenticate when connecting to the Gateway:
>
> * Verify that `mcpProvider.authorization.oauth.enabled` is `true` on the AI
>   Identity Gateway Orchestrator.
> * Check that the Gateway's `/.well-known/oauth-protected-resource` endpoint
>   is reachable and returns valid metadata.
> * Ensure the Auth Provider Orchestrator's well-known endpoint is listed in the
>   Gateway's `mcpProvider.authorization.oauth.servers` configuration.
> * For Claude Desktop, confirm you restarted the application after editing the
>   configuration file.

> **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:
>
> ```json claude_desktop_config.json theme={null}
> {
>   "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.
>
> ```json claude_desktop_config.json theme={null}
> {
>   "mcpServers": {
>     "ai-identity-gateway": {
>       "command": "npx",
>       "args": ["mcp-remote", "https://your-gateway.example.com/mcp"],
>       "env": {
>         "NODE_TLS_REJECT_UNAUTHORIZED": "0"
>       }
>     }
>   }
> }
> ```
>
> > [!WARNING]
> >
> > 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.

## Related Pages

> **[AI Identity Overview](/guides/ai-identity/overview)**
>
> Set up the Auth Provider Orchestrator and understand agent identity concepts

> **[Expose APIs to Agents](/guides/ai-identity/mcp-bridge)**
>
> Make REST APIs available to Claude as MCP tools via MCP Bridge

> **[Protect MCP Servers](/guides/ai-identity/mcp-proxy)**
>
> Add identity governance to existing MCP servers via MCP Proxy

> **[OIDC App Reference](/reference/orchestrator/applications/oidc)**
>
> Full configuration reference for OAuth client registration

### Anthropic Documentation

> **[Connectors Directory FAQ](https://support.claude.com/en/articles/11596036-anthropic-connectors-directory-faq)**
>
> Critical reference covering connector architecture, traffic routing, OAuth requirements, token limits, timeouts, and privacy details

> **[Claude Code MCP Configuration](https://docs.anthropic.com/en/docs/claude-code/mcp)**
>
> Claude Code docs covering MCP transports, OAuth options, and callback port configuration

> **[Remote MCP on claude.ai](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)**
>
> How to add remote MCP servers as connectors on claude.ai, including plan requirements

> **[Building Custom MCP Connectors](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers)**
>
> Developer guide for building OAuth-protected MCP servers that work with Claude

> **[Building Desktop Extensions](https://support.claude.com/en/articles/12922929-building-desktop-extensions-with-mcpb)**
>
> How to package local MCP servers as desktop extensions (.mcpb) for enterprise distribution

> **[MCP Quick Start for Claude Desktop](https://modelcontextprotocol.io/quickstart/user)**
>
> MCP protocol docs for configuring MCP servers in Claude Desktop