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

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. 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, 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 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 invokes keychain.clearAll() (lines 73-79), ensuring no residual authentication data remains.

npx @auth0/auth0-mcp-server logout

✓ 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 (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.

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

# 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 (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.

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.
• 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), 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}