For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Configure Claude Desktop to use agentgateway

Configure Claude Desktop to route requests through your agentgateway proxy.

About third-party inference mode

Claude Desktop sends model traffic to Anthropic by default. Third-party inference mode changes that destination to an endpoint that you operate, such as an agentgateway proxy. Anthropic made this mode generally available on July 9, 2026.

Anthropic designed the mode for organizations whose security, regulatory, or contractual requirements prevent them from sending data to Anthropic’s first-party infrastructure. Prompts, responses, files, and tool outputs go only to the endpoint that you configure, and conversation history stays on the user’s device. You can create an agentgateway proxy at that endpoint, so that every Claude Desktop request passes through your policies for authentication, guardrails, rate limits, and observability before it reaches a model.

Keep the following behavior in mind:

• One setting covers the whole Claude Desktop app. Chat, Cowork, and Code all send inference to the endpoint that you configure.
• Claude Desktop reads its configuration once, at launch. After you change a setting, fully quit the app and reopen it.
• The gateway URL must use HTTPS unless it is a loopback address. A plain HTTP URL on any other host fails validation with the error Invalid custom3p enterprise config: baseUrl: must use https (or http on loopback).
• Managed configuration wins. When an administrator delivers settings through mobile device management (MDM), users cannot override them.

For the full list of settings, see the Claude Desktop configuration reference.

The steps in this guide run agentgateway on the same machine as Claude Desktop and use the loopback address 127.0.0.1, so no certificate is needed. To point Claude Desktop at an agentgateway proxy on another host, serve the proxy over HTTPS. For more information, see HTTPS listeners.

Before you begin

1. Install the agentgateway binary.

2. Install Claude Desktop.

3. Choose how the proxy authenticates callers.

   Method	When to use	Upstream billing
   Gateway API key	Recommended starting point. Agentgateway validates a client key and adds a separately managed Anthropic API key upstream.	Anthropic API account
   Identity provider	Recommended for an enterprise rollout. Agentgateway validates each user’s OIDC token and adds a separately managed Anthropic API key upstream.	Anthropic API account
   Claude subscription passthrough	Advanced option for preserving per-user Claude subscription usage. Agentgateway passes each user’s token upstream and does not independently authenticate the caller.	User’s Claude subscription

   For a gateway API key, configure an LLM model and a virtual API key in agentgateway. For subscription passthrough, you need a Claude Pro, Max, Team, or Enterprise subscription and the Claude Code CLI, which provides the claude setup-token command. For identity-provider authentication, you need an OIDC provider and an Anthropic API key for the proxy to send upstream.

Use Client Setup with a gateway API key

For Claude Desktop, Client Setup outputs the gateway URL and API key; it does not configure a model name in Claude Desktop. The gateway route must already accept the key and support the Anthropic Messages API at /v1/messages, and agentgateway must hold the upstream provider credential. An endpoint that exposes only the OpenAI-compatible /v1/chat/completions API is not sufficient. For more information about the UI, see UI.

For a managed rollout, see Manage gateway API keys with Microsoft Intune.

To preserve per-user subscription billing instead of using a gateway API key, continue with the following advanced configuration.

Optional: Use Claude subscription passthrough

Start agentgateway with the Teams configuration. Agentgateway listens on port 4001 and exposes Claude at the /claude path.

1. Create a configuration file.

   cat > config.yaml << 'EOF'
   gateways:
     default:
       port: 4001
       protocol: HTTP
   routes:
   - name: claude-agent
     matches:
     - path:
         pathPrefix: /claude
     policies:
       urlRewrite:
         path:
           prefix: /
     backends:
     - ai:
         name: claude-agent
         provider:
           anthropic: {}
         policies:
           ai:
             routes:
               /v1/messages: messages
               /v1/messages/count_tokens: anthropicTokenCount
               '*': passthrough
   EOF

2. Start agentgateway.

   agentgateway -f config.yaml

The backend deliberately has no backendAuth policy. In subscription mode, the bearer token that each user creates with claude setup-token must pass through agentgateway to Anthropic. Do not add a provider API key or apply a virtual API key policy to this route.

policies:
  requestHeaderModifier:
    add:
      anthropic-beta: oauth-2025-04-20

Configure Claude Desktop with a Claude subscription

1. Get a bearer token for your Claude account.

   claude setup-token

   Copy the token printed to the terminal.

2. Open Claude Desktop and enable developer mode: Help → Troubleshooting → Enable Developer Mode. Then fully quit and relaunch Claude Desktop. A new Developer menu appears in the menu bar.

3. In the menu bar, go to Developer → Configure Third Party Inference → Gateway.

4. Enter the gateway URL. Use 127.0.0.1 rather than localhost.

   http://127.0.0.1:4001/claude

5. For Credential kind, select Static API key. For Gateway auth scheme, select Bearer, and enter the token from step 1 in Gateway API key. Each user must use their own subscription token. To authenticate users with your identity provider and use a centrally managed provider credential instead, see Authenticate users with your identity provider.

6. Open Models and add at least one full model ID that the subscription can use, such as claude-opus-5. Do not use an alias such as opus. The first entry is the default. Turn off Model discovery, or leave it unset; an explicit model list makes discovery unnecessary.

7. Click Test connection. Claude Desktop tests inference with the first configured model. If no explicit model is configured, the test first calls <base-url>/v1/models and fails when the gateway or provider does not make that endpoint available to the subscription token.

   Note

   With subscription passthrough, the connection test might return HTTP 429 with rate_limit_error even when normal Cowork inference works. Apply the configuration, send a harmless prompt, and check the agentgateway request log. If the actual /v1/messages request returns HTTP 200, treat the connection-test result as a false negative.

8. Click Apply Changes, then fully quit Claude Desktop and reopen it. Claude Desktop reads its configuration only at launch.

   Note

   On macOS, Claude Desktop might not enter third-party inference mode from the settings panel alone. If the app still signs in to Anthropic after you reopen it, set deploymentMode to 3p in the third-party configuration file, then quit and reopen the app again.

   python3 - <<'EOF'
   import json, os
   p = os.path.expanduser('~/Library/Application Support/Claude-3p/claude_desktop_config.json')
   d = json.load(open(p))
   d['deploymentMode'] = '3p'
   open(p, 'w').write(json.dumps(d, indent=2))
   EOF

For a managed rollout of this subscription configuration, see Manage Claude subscriptions with Microsoft Intune.

Authenticate users with your identity provider

If you distribute one static API key to every user, you cannot attribute requests to a person or revoke access for only one user. Instead, select the Interactive sign-in credential kind. Claude Desktop then runs an OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE) against your identity provider and sends the resulting token on every inference request. Agentgateway validates the token and adds the LLM provider credential itself, so the user’s device never holds a provider API key.

The interactive sign-in flow is the same for standalone and Kubernetes deployments. Only the agentgateway configuration differs: standalone configures JWT validation directly on the route, whereas Kubernetes uses an AgentgatewayPolicy and an AgentgatewayBackend for the JWKS endpoint.

    sequenceDiagram
    participant C as Claude Desktop
    participant B as Browser or OS broker
    participant E as Microsoft Entra ID
    participant G as agentgateway
    participant A as Anthropic

    alt Browser flow for initial testing
        C->>B: Open the system browser
        B->>E: Authorization request with PKCE challenge
        E-->>C: Authorization code through loopback callback
        C->>E: Exchange code and PKCE verifier
        E-->>C: ID token
    else Broker flow for managed production devices
        C->>B: Request an identity token
        B->>E: Authenticate the user and device
        E-->>B: ID token
        B-->>C: ID token
    end

    C->>G: Inference request with bearer ID token
    G->>E: Fetch and cache signing keys
    G->>G: Validate signature, issuer, and audience
    G->>A: Inference request with provider credential
    A-->>G: Model response
    G-->>C: Model response
  

The OAuth callback returns to Claude Desktop, not to agentgateway. The gateway hostname is the inference endpoint and must not be registered as the OAuth redirect URI.

After you disable or offboard a user, the identity provider prevents new sign-ins and token refreshes. An ID token that was already issued can remain valid until it expires, depending on the identity provider’s revocation and session policies.

The following steps use Microsoft Entra ID as the example identity provider. Any OpenID Connect (OIDC) provider works the same way. Substitute your own issuer URL, client ID, and JWKS URL.

1. Register a public-client application with your identity provider, and record the client ID and issuer URL. Do not create a client secret. The following values configure Claude Desktop’s browser flow.

   Setting	Value
   Client type	Public client. Claude Desktop holds no client secret.
   Redirect URI	http://127.0.0.1/callback
   Scopes	openid profile email offline_access

   Important

   Two details about the redirect URI cause most failures:

   • Include the /callback path. Claude Desktop redirects to http://127.0.0.1:<port>/callback, and a registration of http://127.0.0.1 alone does not match. On Entra ID, the mismatch returns AADSTS50011.
   • Register the URI as a native or desktop client, not a web client. Claude Desktop picks an ephemeral port for each sign-in. A native client registration accepts any loopback port, as described in RFC 8252, and a web client registration requires an exact port match. On Entra ID, select the Mobile and desktop applications platform. The browser and broker authorization-code flows do not require the legacy Allow public client flows toggle; leave it disabled.
   • Do not register the agentgateway hostname as the redirect URI. Claude Desktop receives the authorization response, then sends the resulting token to the gateway URL on inference requests.

2. Save the identifiers from your registration and your Anthropic API key, so that agentgateway can resolve them. Agentgateway reads variable references in the configuration file from the environment at startup.

   export TENANT_ID=<your-tenant-id>
   export CLIENT_ID=<your-client-id>
   export ANTHROPIC_API_KEY=<your-anthropic-api-key>

3. Update your configuration file to validate the token on the route and to send an Anthropic API key upstream. Interactive sign-in puts the identity provider token in the Authorization header, so the proxy must supply the provider credential itself rather than pass a user token upstream. Replace any client API key authentication on this route instead of requiring both authentication methods.

   cat > config.yaml << 'EOF'
   # yaml-language-server: $schema=https://agentgateway.dev/schema/config
   gateways:
     default:
       port: 4001
       protocol: HTTP
   routes:
   - name: claude-agent
     matches:
     - path:
         pathPrefix: /claude
     policies:
       urlRewrite:
         path:
           prefix: /
       jwtAuth:
         mode: strict
         issuer: https://login.microsoftonline.com/$TENANT_ID/v2.0
         audiences:
         - $CLIENT_ID
         jwks:
           url: https://login.microsoftonline.com/$TENANT_ID/discovery/v2.0/keys
     backends:
     - ai:
         name: claude-agent
         provider:
           anthropic: {}
         policies:
           backendAuth:
             key: "$ANTHROPIC_API_KEY"
           ai:
             routes:
               /v1/messages: messages
               /v1/messages/count_tokens: anthropicTokenCount
               '*': passthrough
   EOF

   Review the following table to understand this configuration.

   Setting	Description
   jwtAuth.mode	Set to strict so that agentgateway rejects any request that has no valid token. The default value, optional, admits requests that carry no token at all.
   jwtAuth.issuer	The expected iss claim. Validating the issuer alongside the signature is what ties a token to your tenant.
   jwtAuth.audiences	The expected aud claim. For an ID token, the audience is the client ID of the application that you registered.
   jwtAuth.jwks.url	The JWKS endpoint that agentgateway fetches signing keys from.
   backendAuth.key	The Anthropic API key that agentgateway sends upstream. Because the user token authenticates the caller, this credential no longer comes from the client.

   Use the issuer base URL shown in the example. Do not use the OpenID discovery-document URL, which ends in /.well-known/openid-configuration, as the issuer.

   For more detail on JWT validation, see JWT authentication.

4. Restart agentgateway to load the new configuration.

   agentgateway -f config.yaml

5. In Claude Desktop, go to Developer → Configure Third Party Inference → Gateway and set the following fields.

   Field	Value
   Credential kind	Interactive sign-in
   Gateway base URL	http://127.0.0.1:4001/claude
   Client ID	The client ID of the application that you registered
   Issuer URL	https://login.microsoftonline.com/$TENANT_ID/v2.0
   Bearer token	ID token
   Scopes	openid profile email offline_access
   Sign-in flow	Browser for this initial test; use the Intune guide to move managed devices to Broker
   Model discovery	Off when you use a fixed model list
   Models	One or more full model IDs that the backend exposes

   Warning

   Set the bearer token type to ID token. With the access token setting, Entra ID returns a Microsoft Graph token that validation against your tenant JWKS rejects with InvalidSignature. The ID token carries the client ID as its audience, which matches the configured audience.

6. From Claude Desktop, click Test connection. Then click Apply Changes, fully quit Claude Desktop, and reopen it. A browser window opens to your identity provider. After you sign in, send a real prompt and confirm a successful POST /v1/messages request in the agentgateway logs. The request must return HTTP 200 and include jwt.sub for the signed-in user. This confirms that Claude Desktop sent the Entra ID token and that agentgateway validated it before forwarding the request.

Send custom headers

Use the Custom inference headers field to add a header to every inference request, such as a tenant identifier that a route or a policy matches on. Claude Desktop sends these headers on requests from Chat, Cowork, and Code alike.

To supply a header value that changes over time, set a credential helper instead. A credential helper is an executable that Claude Desktop runs with no arguments and that prints either a bare token or a JSON object in the form {"token": "...", "headers": {"Name": "Value"}}. Claude Desktop caches the result and re-runs the helper when the cache expires, with no prompt and no relaunch. Helper headers override custom inference headers of the same name, and a configured helper replaces any static API key. Use a helper to read a short-lived credential from a secret store.

Roll out to your organization

Configure and test one machine in developer mode first. When the connection works, click Export in the Configure Third Party Inference panel to produce a profile for your device management system, and distribute it with the tool that you already use, such as Jamf, Intune, Workspace ONE, or Group Policy. Users then receive the configuration on first launch and do not configure anything by hand.

For an end-to-end Microsoft Intune rollout with Entra ID and managed-device enforcement, see Manage Claude Desktop with Microsoft Intune.

Managed configuration takes precedence over local settings, so a user cannot point the app at a different endpoint. The delivery mechanism differs per operating system.

The following example shows the Linux form. On macOS and Windows, write every value as a string, including numbers, booleans, and nested JSON.

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://agentgateway.example.com/claude",
  "inferenceCredentialKind": "interactive",
  "inferenceGatewayOidcAuthFlow": "browser",
  "inferenceGatewayOidc": {
    "issuer": "https://login.microsoftonline.com/$TENANT_ID/v2.0",
    "clientId": "$CLIENT_ID",
    "scopes": "openid profile email offline_access",
    "bearerTokenType": "id_token"
  },
  "modelDiscoveryEnabled": false,
  "inferenceModels": ["claude-opus-5"],
  "inferenceCustomHeaders": {
    "X-Tenant-Id": "acme"
  }
}

For every available key and for the per-region profiles that a multi-region deployment needs, see the Claude Desktop configuration reference.

Verify the connection

Send a message in Claude Desktop. If the connection is successful, responses flow through your agentgateway proxy and appear in the terminal where agentgateway is already running.

Look for log entries like the following in your running agentgateway output:

info  request gateway=default/default listener=http route=claude-agent endpoint=api.anthropic.com:443 http.method=POST http.path=/v1/messages http.status=200 protocol=llm

If you configured gateway API key or OIDC authentication in strict mode, send a request without the Authorization header and confirm that agentgateway rejects it. This negative check verifies that the route does not admit unauthenticated requests.

Troubleshoot the connection

Next steps