# How to Switch Between Different Auth0 Tenants Using the Same MCP Server Installation

> Easily switch between Auth0 tenants using the same MCP server. Learn how to clear credentials and reauthenticate to manage multiple tenants efficiently.

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

---

**To switch between different Auth0 tenants with a single MCP server installation, run `npx @auth0/auth0-mcp-server logout` to clear stored credentials from your system keychain, then execute `npx @auth0/auth0-mcp-server init` to authenticate against the new tenant.**

The Auth0 MCP Server stores tenant-specific authentication data in your system's secure keychain, enabling seamless multi-tenant workflows without reinstalling the package. Whether you are managing development, staging, and production environments or switching between client organizations, understanding how to switch between different Auth0 tenants ensures you can securely transition between authentication contexts.

## Understanding Tenant Storage and Authentication Flow

The MCP server persists your current session using the `KeychainService` class defined in [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts). This service stores your **access token**, **refresh token**, **tenant domain**, and expiration timestamp in the system keychain (lines 24-30). When you authenticate via the device authorization flow implemented in [`src/auth/device-auth-flow.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/auth/device-auth-flow.ts), the server extracts the tenant domain from the token's `iss` claim using the `getTenantFromToken` function and persists it via `keychain.setDomain` (lines 42-47).

On startup, [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) loads this configuration from the keychain (lines 62-63), automatically connecting to the stored tenant domain. To switch tenants, you must purge these stored values and establish a new authentication session.

## Step-by-Step Guide to Switching Tenants

### Step 1: Log Out of the Current Tenant

First, clear the existing credentials to remove the current tenant's access token, refresh token, and domain information. The `logout` command in [`src/commands/logout.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/logout.ts) invokes `keychain.clearAll()` (lines 73-79), ensuring no residual authentication data remains.

```bash
npx @auth0/auth0-mcp-server logout

```

```text
✓ Successfully removed access token, refresh token, domain information from your system keychain.

```

### Step 2: Initialize Authentication with the New Tenant

Run the `init` command to start a fresh authentication flow. According to the documentation in [`README.md`](https://github.com/auth0/auth0-mcp-server/blob/main/README.md) (lines 50-55), this command should be executed when you want to switch tenants. The CLI will prompt you to log in via your browser, where you can select the new tenant.

```bash
npx @auth0/auth0-mcp-server init --client claude

```

```text

# During the flow a browser window opens.

# After you finish, the CLI prints:

Successfully authenticated to <new-tenant>.auth0.com

```

For **private cloud deployments** using client credentials instead of device flow, pass your private-cloud domain and client-secret flags during initialization as implemented in [`src/commands/init.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/init.ts) (lines 144-151). The logout-then-init pattern remains identical.

### Step 3: Start the MCP Server

Launch the server to automatically pick up the newly stored tenant domain from the keychain.

```bash
npx @auth0/auth0-mcp-server run

```

The server reads the updated configuration on startup, establishing all subsequent API connections to the new tenant.

## Why You Must Log Out Before Re-initializing

If you run `init` while a valid token already exists in the keychain, the CLI detects the stored tenant and skips the login prompt. To force authentication against a different tenant, you **must** clear the keychain using `logout` first. Skipping this step will maintain the original tenant session, preventing the switch.

## Summary

- The Auth0 MCP Server stores tenant credentials (domain, tokens) in your system keychain via `KeychainService` in [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts).
- Run `npx @auth0/auth0-mcp-server logout` to execute `clearAll()` and purge all stored authentication data.
- Execute `npx @auth0/auth0-mcp-server init` to trigger a new device authorization flow or client credentials authentication against the desired tenant.
- The server loads the tenant domain from the keychain on startup ([`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts)), automatically connecting to the most recently authenticated tenant.
- For private cloud environments, use the client-credentials flags during `init` while following the same logout-init sequence.

## Frequently Asked Questions

### Does the Auth0 MCP Server support multiple concurrent tenant sessions?

No, the Auth0 MCP Server maintains a single active tenant session per installation. The `KeychainService` stores one set of credentials (access token, refresh token, and domain) at a time. To work with a different tenant, you must switch contexts by running `logout` followed by `init` for the new tenant.

### Where are my Auth0 tenant credentials stored when using the MCP server?

Your credentials are stored in your operating system's native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) via the `KeychainService` class in [`src/utils/keychain.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/keychain.ts). This includes your access token, refresh token, and tenant domain, providing secure storage outside of plaintext configuration files.

### Can I switch tenants without running the logout command?

No, you cannot reliably switch tenants without logging out first. If you attempt to run `init` while valid credentials exist in the keychain, the CLI detects the active session and skips the authentication flow. You must clear the existing credentials using `logout` to force a new authentication prompt for the target tenant.

### Does switching tenants affect my MCP client configuration?

No, switching tenants does not modify your MCP client configuration files (such as Claude Desktop settings). The tenant context is determined solely by the credentials stored in your system keychain. Your client configuration continues to point to the same `npx @auth0/auth0-mcp-server run` command, which dynamically loads the current tenant domain on startup.