# How to Configure the Auth0 MCP Server for Private Cloud Tenants Using Client Credentials

> Configure Auth0 MCP Server for Private Cloud tenants using client credentials. Learn how to switch authentication from device flow to OAuth client-credentials grant with simple options.

- Repository: [Auth0/auth0-mcp-server](https://github.com/auth0/auth0-mcp-server)
- Tags: how-to-guide
- Published: 2026-02-25

---

**To configure the Auth0 MCP Server for Private Cloud tenants, pass the `--auth0-domain`, `--auth0-client-id`, and `--auth0-client-secret` options to the `init` command, which automatically switches authentication from the default device flow to the OAuth client-credentials grant.**

The `auth0/auth0-mcp-server` repository enables AI assistants to manage Auth0 tenants through the Model Context Protocol (MCP). While public cloud tenants use an interactive device authorization flow, Private Cloud environments require you to configure the Auth0 MCP Server using client credentials for non-interactive authentication.

## Authentication Flow Overview

The MCP server supports two distinct authentication methods depending on your tenant type:

- **Device Authorization Flow**: The default interactive flow for public cloud tenants where users authenticate via a browser.
- **Client Credentials Flow**: Required for Private Cloud tenants where interactive browser-based authentication is not available or permitted.

When you provide the three credential parameters during initialization, the server detects Private Cloud mode and bypasses the device flow entirely, obtaining an access token directly through the OAuth 2.0 client-credentials grant.

## Prerequisites for Private Cloud Setup

Before initializing the server for a Private Cloud tenant, ensure you have:

1. **Domain**: Your Private Cloud tenant domain (e.g., `my-tenant.private.auth0.com`)
2. **Client ID**: An Auth0 application client ID with the client-credentials grant enabled
3. **Client Secret**: The corresponding client secret for the application
4. **Audience**: Optional. Defaults to `https://<domain>/api/v2/` if not specified

## Step-by-Step Configuration

### Initialize via CLI

Run the `init` command with all three authentication parameters to trigger the client-credentials flow:

```bash
auth0-mcp init \
  --client claude \
  --tools '*' \
  --auth0-domain my-tenant.private.auth0.com \
  --auth0-client-id A1B2C3D4E5F6G7H8I9J0 \
  --auth0-client-secret superSecretValue123

```

This command calls the initialization logic in [`src/commands/init.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/init.ts), detects the presence of the credential triad (lines 43-47), and logs "Using client credentials flow for authentication" before proceeding.

### Initialize Programmatically

You can also configure the server programmatically using TypeScript:

```typescript
import init from './src/commands/init.js';

await init({
  client: 'windsurf',
  tools: ['auth0_list_*', 'auth0_get_*'],
  auth0Domain: 'my-tenant.private.auth0.com',
  auth0ClientId: 'A1B2C3D4E5F6G7H8I9J0',
  auth0ClientSecret: 'superSecretValue123',
});

```

The `init` function checks for `auth0Domain`, `auth0ClientId`, and `auth0ClientSecret` properties and routes to `requestClientCredentialsAuthorization` when all three are present.

## How the Client Credentials Flow Works

Understanding the internal mechanism helps troubleshoot configuration issues. The flow follows these steps according to the source code:

### Detection and Routing

In [`src/commands/init.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/init.ts) (lines 43-47), the CLI inspects the options object. If `auth0Domain`, `auth0ClientId`, and `auth0ClientSecret` are all provided, the server immediately selects the client-credentials path instead of the interactive device flow.

### Token Acquisition

The function `requestClientCredentialsAuthorization` in [`src/auth/client-credentials-flow.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/auth/client-credentials-flow.ts) (lines 30-48) handles the OAuth exchange:

```typescript
// Simplified representation of the flow
const authClient = await getAuthenticationClient(domain, clientId, clientSecret);
const { data } = await authClient.oauth.clientCredentialsGrant({
  audience: `https://${domain}/api/v2/`,  // Defaults to Management API v2
});

```

If the `audience` parameter is omitted, the code automatically constructs the default Auth0 Management API v2 endpoint for your domain.

### Secure Storage

The received tokens are persisted in the system keychain via [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts) (lines 60-78):

- `keychain.setToken(data.access_token)` stores the bearer token
- `keychain.setDomain(domain)` saves the tenant domain
- `keychain.setTokenExpiresAt(Date.now() + data.expires_in * 1000)` records expiration

This ensures credentials survive server restarts without residing in plain text files.

### Configuration Validation

Before each API call, the server uses `loadConfig` and `validateConfig` from [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) to verify that:

- A domain is configured
- The access token exists in the keychain
- The token has not expired

If validation fails, the server prompts you to re-run the initialization command.

## Verifying Your Configuration

After initialization, confirm that credentials are properly stored and valid:

```typescript
import { loadConfig, validateConfig } from './src/utils/config.js';

const cfg = await loadConfig();
if (await validateConfig(cfg)) {
  console.log('MCP is ready – token valid for domain', cfg?.domain);
} else {
  console.error('Configuration invalid – re-run `auth0-mcp init` with correct credentials');
}

```

A successful validation indicates the MCP server can now call the Auth0 Management API on your Private Cloud tenant.

## Summary

- **Private Cloud tenants** must use the client-credentials flow because they cannot execute the interactive device authorization flow.
- **Trigger the flow** by providing `--auth0-domain`, `--auth0-client-id`, and `--auth0-client-secret` to the `init` command or programmatic `init` function.
- **Automatic detection** occurs in [`src/commands/init.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/init.ts) when all three credential parameters are present.
- **Token management** happens automatically through [`src/auth/client-credentials-flow.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/auth/client-credentials-flow.ts) and secure storage in [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts).
- **Validation** ensures the server only starts when valid credentials are available in the system keychain.

## Frequently Asked Questions

### What is the difference between device flow and client credentials in the Auth0 MCP Server?

Device flow requires a user to authenticate through a browser and enter a device code, which is suitable for public cloud tenants. Client credentials use a machine-to-machine OAuth grant where the server authenticates directly using a client ID and secret, which is required for Private Cloud tenants that cannot run interactive browser sessions.

### How do I know if my tenant requires client credentials authentication?

If your tenant uses a Private Cloud deployment (typically domains ending in `.private.auth0.com` or custom private domains) and lacks public internet access for browser-based authentication, you must use client credentials. Public cloud tenants (e.g., `tenant.auth0.com`) can use the default device flow.

### Where are the credentials stored after running the init command?

The access token, domain, and expiration timestamp are stored in your operating system's secure keychain using the functions in [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts) (lines 60-78). The client secret is used only during the initial token exchange and is not persisted to disk.

### Can I switch from device flow to client credentials without reinstalling the server?

Yes. Simply re-run the `auth0-mcp init` command with the `--auth0-domain`, `--auth0-client-id`, and `--auth0-client-secret` parameters. The new credentials will overwrite the existing device-flow tokens in the keychain, and the server will use the client-credentials flow for subsequent API calls.