auth0-mcp-server

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #golang #machine-learning #deep-learning #nodejs #windows #awesome #vue #awesome-list #mcp #openai

auth0-mcp-server

(★ 113)

Connect LLMs and AI agents to Auth0 Management APIs via an MCP server. Use natural-language commands to create apps, deploy Actions, and query logs—runs locally and supports interactive tenant authentication for secure Auth0 administration from AI tools/CLIs.

File Explorer

Download Latest Version (.zip)

- - Bug Report.yml
  - config.yml
  - Feature Request.yml
- - npm-release.yml
  - release.yml
  - rl-secure.yml
  - test.yml
- CODEOWNERS
- dependabot.yml
- PULL_REQUEST_TEMPLATE.md
- stale.yml
- auth0-mcp-example-demo.gif
- auth0-mcp-server-hld.png
- help-image-01.png
- help-image-02.png
- help-image-03.png
- mcp-banner-light.png
- mcp-server-auth.png
- - init.toml
  - logout.toml
  - session.toml
- - client-credentials-flow.ts
  - device-auth-flow.ts
- - base.ts
  - claude-code.ts
  - claude.ts
  - cursor.ts
  - gemini.ts
  - index.ts
  - types.ts
  - utils.ts
  - vscode.ts
  - windsurf.ts
- - init.ts
  - logout.ts
  - run.ts
  - session.ts
- - actions.ts
  - application-grants.ts
  - applications.ts
  - forms.ts
  - index.ts
  - logs.ts
  - onboarding.ts
  - quickstarts.ts
  - resource-servers.ts
- - analytics.ts
  - auth0-client.ts
  - config.ts
  - constants.ts
  - credentials-writer.ts
  - env-credentials.ts
  - fetch.ts
  - glob.ts
  - http-utility.ts
  - keychain.ts
  - logger.ts
  - onboarding.ts
  - package.ts
  - quickstart-guide.ts
  - quickstart-placeholders.ts
  - quickstarts.ts
  - rate-limiter.ts
  - response-masker.ts
  - scopes.ts
  - terminal.ts
  - tools.ts
  - types.ts
- exports.ts
- index.ts
- server.ts
- - client-credentials-flow.test.ts
  - device-auth-flow.test.ts
  - request-authorization.test.ts
- - logs.benchmark.test.ts
  - README.md
- - base.test.ts
  - claude-code.test.ts
  - clients.test.ts
  - index.test.ts
  - utils.test.ts
  - vscode.test.ts
- - init-client-credentials.test.ts
  - init.test.ts
  - logout.test.ts
  - run.test.ts
  - session.test.ts
- - mcp-test.ts
- - mcp-server.test.ts
- - config.ts
  - handlers.ts
  - terminal.ts
- - actions.test.ts
  - application-grants.test.ts
  - applications.test.ts
  - forms.test.ts
  - index.test.ts
  - logs.test.ts
  - onboarding.test.ts
  - quickstarts.test.ts
  - resource-servers.test.ts
  - tool-parameter-schema.test.ts
- - analytics.test.ts
  - auth0-client.test.ts
  - config.test.ts
  - credentials-writer.test.ts
  - env-credentials.test.ts
  - fetch.test.ts
  - glob.test.ts
  - keychain.test.ts
  - onboarding.test.ts
  - quickstart-guide.test.ts
  - quickstart-placeholders.test.ts
  - quickstarts.test.ts
  - rate-limiter.test.ts
  - response-masker.test.ts
  - scopes.test.ts
  - tools.test.ts
- exports.test.ts
- index.test.ts
- README.md
- server.test.ts
- setup.ts
- generate-notice.js
- local-setup.js
- publish-smithery.js
.gitignore
.mcpbignore
.prettierignore
.prettierrc
.shiprc
.version
AGENTS.md
CHANGELOG.md
eslint.config.js
gemini-extension.json
GEMINI.md
glama.json
icon.png
LICENSE
manifest.json
NOTICE
package.json
README.md
server.json
tsconfig.json
tsconfig.test.json
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![MCP server for Auth0](https://cdn.auth0.com/website/mcp/assets/mcp-banner-light.png)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![NPM Downloads](https://img.shields.io/npm/dw/%40auth0%2Fauth0-mcp-server)](https://www.npmjs.com/package/@auth0/auth0-mcp-server)
[![NPM Version](https://img.shields.io/npm/v/@auth0/auth0-mcp-server)](https://www.npmjs.com/package/@auth0/auth0-mcp-server)
[<img src="https://devin.ai/assets/deepwiki-badge.png" alt="Ask questions about auth0-mcp-server on DeepWiki" height="20"/>](https://deepwiki.com/auth0/auth0-mcp-server)

</div>

📚 [Documentation](https://auth0.com/docs/get-started/mcp) • 🚀 [Getting Started](#-getting-started) • 💻 [Supported Tools](#%EF%B8%8F-supported-tools) • 💬 [Feedback](#-feedback-and-contributing)

</div>

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) is an open protocol introduced by Anthropic that standardizes how large language models communicate with external tools, resources or remote services.

Connect Claude, Cursor, or Windsurf to your Auth0 tenant to create apps, deploy Actions, debug logs, and manage users — all without touching the dashboard.

> [!CAUTION]
> **Beta Software Notice: This software is currently in beta and is provided AS IS without any warranties.**
>
> - Features, APIs, and functionality may change at any time without notice
> - Not recommended for production use or critical workloads
> - Support during the beta period is limited
> - Issues and feedback can be reported through the [GitHub issue tracker](https://github.com/auth0/auth0-mcp-server/issues)
>
> By using this beta software, you acknowledge and accept these conditions.

The Auth0 MCP Server integrates with LLMs and AI agents, allowing you to perform various Auth0 management operations using natural language. For instance, you could simply ask Claude Desktop to perform Auth0 management operations:

- > Create a new Auth0 app and get the domain and client ID
- > Create and deploy a new Auth0 action to generate a JWT token
- > Could you check Auth0 logs for logins from 192.108.92.3 IP address?

<br/>

## 🚀 Getting Started

**Prerequisites:**

- [Node.js v18 or higher](https://nodejs.org/en/download)
- [Claude Desktop](https://claude.ai/download) or any other [MCP Client](https://modelcontextprotocol.io/clients)
- [Auth0](https://auth0.com/) account with appropriate permissions

<br/>

### Install the Auth0 MCP Server

Install Auth0 MCP Server and configure it to work with your preferred MCP Client. The `--tools` parameter specifies which tools should be available (defaults to `*` if not provided).

**Claude Desktop with all tools**

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

**Claude Desktop with read-only tools**

```bash
npx @auth0/auth0-mcp-server init --read-only
```

You can also explicitly select read-only tools:

```bash
npx @auth0/auth0-mcp-server init --tools 'auth0_list_*,auth0_get_*'
```

**Claude Code**

Initialize the Auth0 MCP server for Claude Code

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

You will be prompted to choose a configuration scope:

- **User** — written to `~/.claude.json` and available across all your projects.
- **Project** — written to `.mcp.json` at a project folder you specify, intended to be checked into version control and shared with your team.

**Windsurf**

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

**Cursor**

Step 1:

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install)

Step 2:

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

**Cursor with limited tools access**

```bash
npx @auth0/auth0-mcp-server init --client cursor --tools 'auth0_list_applications,auth0_get_application'
```

**VS Code**

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

You can configure VS Code for either global or workspace scope:

- **Global**: Available in all VS Code instances
- **Workspace**: Available only in a specific project/repository

The command will prompt you to choose your preferred scope and automatically configure the appropriate `mcp.json` file.

**VS Code with limited tools access**

```bash
npx @auth0/auth0-mcp-server init --client vscode --tools 'auth0_list_*,auth0_get_*' --read-only
```

**Gemini CLI**

Initialize the gemini MCP server for the Gemini CLI

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

Install the Gemini Extension

```
gemini extensions install https://github.com/auth0/auth0-mcp-server

```

**Codex CLI**

Authenticate once with Auth0:

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

Then add the Auth0 MCP server to Codex:

```bash
codex mcp add auth0 --env DEBUG=auth0-mcp --env DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus -- npx -y @auth0/auth0-mcp-server run
```

You can also add it directly to `~/.codex/config.toml`:

```toml
[mcp_servers.auth0]
command = "npx"
args = ["-y", "@auth0/auth0-mcp-server", "run"]

[mcp_servers.auth0.env]
DEBUG = "auth0-mcp"
DBUS_SESSION_BUS_ADDRESS = "unix:path=/run/user/1000/bus"
```

Restart Codex after updating the configuration.

**Other MCP Clients**

To use Auth0 MCP Server with any other MCP Client, you can manually add this configuration to the client and restart for changes to take effect:

```json
{
  "mcpServers": {
    "auth0": {
      "command": "npx",
      "args": ["-y", "@auth0/auth0-mcp-server", "run"],
      "capabilities": ["tools"],
      "env": {
        "DEBUG": "auth0-mcp"
      }
    }
  }
}
```

You can add `--tools '<pattern>'` to the args array to control which tools are available. See [Security Best Practices](#-security-best-practices-for-tool-access) for recommended patterns.

### Authorize with Auth0

Your browser will automatically open to initiate the OAuth 2.0 device authorization flow. Log into your Auth0 account and grant the requested permissions.

> [!NOTE]
> Credentials are securely stored in your system's keychain. You can optionally verify storage through your keychain management tool. Check out [Authentication](#-authentication) for more info.

### Verify your integration

Restart your MCP Client (Claude Desktop, Windsurf, Cursor, etc.) and ask it to help you manage your Auth0 tenant

### Onboard your project

To get a project running with Auth0 from scratch, ask your MCP Client to onboard it (e.g. `Onboard my Next.js project with Auth0`). This invokes the `auth0_onboarding` tool, which creates an Auth0 application configured for your framework and writes the credentials to a `.env` file in your project. Under the hood it composes the `auth0_create_application` and `auth0_save_credentials_to_file` tools to do this. It then hands off to `auth0_get_quickstart_guide`, which resolves your callback URLs, updates the application, and returns the framework-specific code to integrate the Auth0 SDK — taking you from no Auth0 setup to a working integration in a single guided flow.

## 🛠️ Supported Tools

The Auth0 MCP Server provides the following tools for Claude to interact with your Auth0 tenant:

### Applications

| Tool                       | Description                                                 | Usage Examples                                                                                                                                                                                                                           |
| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_list_applications`  | List all applications in the Auth0 tenant or search by name | - `Show me all my Auth0 applications` <br> - `Find applications with 'api' in their name` <br> - `What applications do I have in my Auth0 tenant?`                                                                                       |
| `auth0_get_application`    | Get details about a specific Auth0 application              | - `Show me details for the application called 'Customer Portal'` <br> - `Get information about my application with client ID abc123` <br> - `What are the callback URLs for my 'Mobile App'?`                                            |
| `auth0_create_application` | Create a new Auth0 application                              | - `Create a new single-page application called 'Analytics Dashboard'` <br> - `Set up a new native mobile app called 'iOS Client'` <br> - `Create a machine-to-machine application for our background service`                            |
| `auth0_update_application` | Update an existing Auth0 application                        | - `Update the callback URLs for my 'Web App' to include https://staging.example.com/callback` <br> - `Change the logout URL for the 'Customer Portal'` <br> - `Add development environment metadata to my 'Admin Dashboard' application` |
| `auth0_save_credentials_to_file` | Save an application's credentials as environment variables to a project's `.env` file (and add it to `.gitignore`) | - `Save my app's Auth0 credentials to a .env file in this project` <br> - `Write the client ID and secret for 'Web App' to .env.local` <br> - `Store these Auth0 credentials in my project's environment file` |

### Onboarding

| Tool                          | Description                                                                                                                     | Usage Examples                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_onboarding`            | Onboard a project with Auth0: creates an application configured for the given framework and saves credentials to a `.env` file | - `Onboard my Next.js project with Auth0` <br> - `Set up Auth0 for my React app in this directory` <br> - `Get my Express app started with Auth0`                                        |
| `auth0_get_quickstart_guide`  | Fetch the framework quickstart prompt, resolve and update callback URLs, and return code to integrate the Auth0 SDK            | - `Show me how to add the Auth0 SDK to my Next.js app` <br> - `Complete the Auth0 integration for my project` <br> - `Give me the quickstart code for my React application`              |

### Resource Servers

| Tool                           | Description                                          | Usage Examples                                                                                                                                                                                            |
| ------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_list_resource_servers`  | List all resource servers (APIs) in the Auth0 tenant | - `Show me all the APIs in my Auth0 tenant` <br> - `List my resource servers` <br> - `What APIs have I configured in Auth0?`                                                                              |
| `auth0_get_resource_server`    | Get details about a specific Auth0 resource server   | - `Show me details for the 'User API'` <br> - `What scopes are defined for my 'Payment API'?` <br> - `Get information about the resource server with identifier https://api.example.com"`                 |
| `auth0_create_resource_server` | Create a new Auth0 resource server (API)             | - `Create a new API called 'Inventory API' with read and write scopes` <br> - `Set up a resource server for our customer data API` <br> - `Create an API with the identifier https://orders.example.com"` |
| `auth0_update_resource_server` | Update an existing Auth0 resource server             | - `Add an 'admin' scope to the 'User API'` <br> - `Update the token lifetime for my 'Payment API' to 1 hour` <br> - `Change the signing algorithm for my API to RS256`                                    |

### Application Grants

| Tool                             | Description                                                                                             | Usage Examples                                                                                                                                                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_create_application_grant` | Create a client grant that authorizes an Auth0 application to access a specific API with defined scopes | - `Grant my 'Backend Service' application access to the 'User API'` <br> - `Create a client grant for my M2M app to call the payments API` <br> - `Authorize my application to access the inventory API with read and write scopes` |

### Actions

| Tool                  | Description                               | Usage Examples                                                                                                                                                                            |
| --------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_list_actions`  | List all actions in the Auth0 tenant      | - `Show me all my Auth0 actions` <br> - `What actions do I have configured?` <br> - `List the actions in my tenant`                                                                       |
| `auth0_get_action`    | Get details about a specific Auth0 action | - `Show me the code for my 'Enrich User Profile' action` <br> - `Get details about my login flow action` <br> - `What does my 'Add Custom Claims' action do?`                             |
| `auth0_create_action` | Create a new Auth0 action                 | - `Create an action that adds user roles to tokens` <br> - `Set up an action to log failed login attempts` <br> - `Create a post-login action that checks user location`                  |
| `auth0_update_action` | Update an existing Auth0 action           | - `Update my 'Add Custom Claims' action to include department information` <br> - `Modify the IP filtering logic in my security action` <br> - `Fix the bug in my user enrichment action` |
| `auth0_deploy_action` | Deploy an Auth0 action                    | - `Deploy my 'Add Custom Claims' action to production` <br> - `Make my new security action live` <br> - `Deploy the updated user enrichment action`                                       |

### Logs

| Tool              | Description                     | Usage Examples                                                                                                                                                                                    |
| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_list_logs` | List logs from the Auth0 tenant | - `Show me recent login attempts` <br> - `Find failed logins from the past 24 hours` <br> - `Get authentication logs from yesterday` <br> - `Show me successful logins for user john@example.com` |
| `auth0_get_log`   | Get a specific log entry by ID  | - `Show me details for log entry abc123` <br> - `Get more information about this failed login attempt` <br> - `What caused this authentication error?`                                            |

### Forms

| Tool                 | Description                             | Usage Examples                                                                                                                                                                      |
| -------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth0_list_forms`   | List all forms in the Auth0 tenant      | - `Show me all my Auth0 forms` <br> - `What login forms do I have configured?` <br> - `List the custom forms in my tenant`                                                          |
| `auth0_get_form`     | Get details about a specific Auth0 form | - `Show me the details of my 'Corporate Login' form` <br> - `What does my password reset form look like?` <br> - `Get the configuration for my signup form`                         |
| `auth0_create_form`  | Create a new Auth0 form                 | - `Create a new login form with our company branding` <br> - `Set up a custom signup form that collects department information` <br> - `Create a password reset form with our logo` |
| `auth0_update_form`  | Update an existing Auth0 form           | - `Update the colors on our login form to match our new brand guidelines` <br> - `Add a privacy policy link to our signup form` <br> - `Change the logo on our password reset form` |
| `auth0_publish_form` | Publish an Auth0 form                   | - `Publish my updated login form` <br> - `Make the new signup form live` <br> - `Deploy the password reset form to production`                                                      |

### 🔒 Security Best Practices for Tool Access

When configuring the Auth0 MCP Server, it's important to follow security best practices by limiting tool access based on your specific needs. The server provides flexible configuration options that let you control which tools AI assistants can access.

You can easily restrict tool access using the `--tools` and `--read-only` flags when starting the server:

```bash
# Enable only read-only operations
npx @auth0/auth0-mcp-server run --read-only

# Alternative way to enable only read-only operations
npx @auth0/auth0-mcp-server run --tools 'auth0_list_*,auth0_get_*'

# Limit to just application-related tools
npx @auth0/auth0-mcp-server run --tools 'auth0_*_application*'

# Limit to read-only application-related tools
# Note: --read-only takes priority when used with --tools
npx @auth0/auth0-mcp-server run --tools 'auth0_*_application*' --read-only

# Restrict to only log viewing capabilities
npx @auth0/auth0-mcp-server run --tools 'auth0_list_logs,auth0_get_log'

# Run the server with all tools enabled
npx @auth0/auth0-mcp-server run --tools '*'
```

> [!IMPORTANT]
> When both `--read-only` and `--tools` flags are used together, the `--read-only` flag takes priority for security. This means even if your `--tools` pattern matches non-read-only tools, only read-only operations will be available. This ensures you can rely on the `--read-only` flag as a security guardrail.

For environments where CLI flags cannot be passed through (for example, MCP bundle installs), the same controls are available as environment variables:

| Variable              | Equivalent flag | Example                                    |
| --------------------- | --------------- | ------------------------------------------ |
| `AUTH0_MCP_READ_ONLY` | `--read-only`   | `AUTH0_MCP_READ_ONLY=true`                 |
| `AUTH0_MCP_TOOLS`     | `--tools`       | `AUTH0_MCP_TOOLS=auth0_list_*,auth0_get_*` |

CLI flags take precedence when both are provided.

This approach offers several important benefits:

1. **Enhanced Security**: By limiting available tools to only what's needed, you reduce the potential attack surface and prevent unintended modifications to your Auth0 tenant.

2. **Better Performance**: Providing fewer tools to AI assistants actually improves performance. When models have access to many tools, they use more of their context window to reason about which tools to use. With a focused set of tools, you'll get faster and more relevant responses.

3. **Resource-Based Access Control**: You can configure different instances of the MCP server with different tool sets based on specific needs - development environments might need full access, while production environments could be limited to read operations only.

4. **Simplified Auditing**: With limited tools, it's easier to track which operations were performed through the AI assistant.

For most use cases, start with the minimum set of tools needed and add more only when required. This follows the principle of least privilege - a fundamental security best practice.

#### 🛡️ Credential Protection

The server automatically **redacts sensitive fields** (e.g., `client_secret`, `token` etc.) in relevant MCP tool responses, replacing them with `[REDACTED]`. This prevents secrets from leaking into AI assistant logs or conversation history.

To securely store credentials locally, the `auth0_save_credentials_to_file` tool writes Auth0 credentials as environment variables to a user-specified file (e.g., `.env.local`), and automatically adds it to `.gitignore`. If the file already exists, credentials are appended (preserving existing content); otherwise, a new file is created. This tool can be invoked manually or the AI assistant will automatically prompt you to save credentials after creating an application.

### 🧪 Security Scanning

We recommend regularly scanning this server, and any other MCP-compatible servers you deploy, with community tools built to surface protocol-level risks and misconfigurations.

These scanners help identify issues across key vulnerability classes including: server implementation bugs, tool definition and lifecycle risks, interaction and data flow weaknesses, and configuration or environment gaps.

Useful tools include:

- **[mcpscan.ai](https://mcpscan.ai)**  
  Web-based scanner that inspects live MCP endpoints for exposed tools, schema enforcement gaps, and other issues.

- **[mcp-scan](https://github.com/invariantlabs-ai/mcp-scan)**  
  CLI tool that simulates attack paths and evaluates server behavior from a client perspective.

These tools are not a substitute for a full audit, but they offer meaningful guardrails and early warnings. We suggest including them in your regular security review process.

If you discover a vulnerability, please follow our [responsible disclosure process](https://auth0.com/whitehat).

## 🕸️ Architecture

The Auth0 MCP Server implements the Model Context Protocol, allowing Claude to:

1. Request a list of available Auth0 tools
2. Call specific tools with parameters
3. Receive structured responses from the Auth0 Management API

The server handles authentication, request validation, and secure communication with the Auth0 Management API.

> [!NOTE]
> The server operates as a local process that connects to Claude Desktop, enabling secure communication without exposing your Auth0 credentials.

## 🔐 Authentication

The Auth0 MCP Server uses the Auth0 Management API and requires authentication to access your Auth0 tenant.

### Initial Setup

To authenticate the MCP Server:

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

This will start the device authorization flow, allowing you to log in to your Auth0 account and select the tenant you want to use.

> [!NOTE]
> Authenticating using device authorization flow is not supported for **private cloud** tenants.
> Private Cloud users should authenticate with [client credentials](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).Keep the token lifetime as minimal as possible to reduce security risks. [See more](https://auth0.com/docs/secure/tokens/access-tokens/update-access-token-lifetime)
>
> ```bash
> npx @auth0/auth0-mcp-server init --auth0-domain <auth0-domain> --auth0-client-id <auth0-client-id> --auth0-client-secret <auth0-client-secret>
> ```

> [!IMPORTANT]
>
> <details>
> <summary>Keep limited scope for client credentials M2M application:</summary>
>
> Supported scopes:
>
> - `read:clients`
> - `create:clients`
> - `update:clients`
> - `read:resource_servers`
> - `create:resource_servers`
> - `update:resource_servers`
> - `read:actions`
> - `create:actions`
> - `update:actions`
> - `read:logs`
> - `read:forms`
> - `create:forms`
> - `update:forms`
>
> </details>
> The `init` command needs to be run whenever:
>
> - You're setting up the MCP Server for the first time
> - You've logged out from a previous session
> - You want to switch to a different tenant
> - Your token has expired
>
> The `run` command will automatically check for token validity before starting the server and will provide helpful error messages if authentication is needed.

> [!NOTE]
> Using the MCP Server will consume Management API rate limits according to the subscription plan. Refer to the [Rate Limit Policy](https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) for more information.

> [!TIP]
> Using the `--no-interaction` flag skips the user interaction (press return) to open the browser during setup. This can be useful if the MCP server is initiated in certain environments like an AI Agent.

### Session Management

To see information about your current authentication session:

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

### Logging Out

For security best practices, always use the logout command when you're done with a session:

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

This ensures your authentication tokens are properly removed from the system keychain.

### Authentication Flow

The server uses OAuth 2.0 device authorization flow for secure authentication with Auth0. Your credentials are stored securely in your system's keychain and are never exposed in plain text.

## 🩺 Troubleshooting

When encountering issues with the Auth0 MCP Server, several troubleshooting options are available to help diagnose and resolve problems.

Start troubleshooting by exploring all available commands and options:

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

### 🚥 Operation Modes

#### 🐞 Debug Mode

- More detailed logging
- Enable by setting environment variable: `export DEBUG=auth0-mcp`

> [!TIP]
> Debug mode is particularly useful when troubleshooting connection or authentication issues.

#### 🔑 Scope Selection

The server provides an interactive scope selection interface during initialization:

- **Interactive Selection**: Navigate with arrow keys and toggle selections with spacebar
- **No Default Scopes**: By default, no scopes are selected for maximum security
- **Glob Pattern Support**: Quickly select multiple related scopes with patterns:

```bash
  # Select all read scopes
  npx @auth0/auth0-mcp-server init --scopes 'read:*'

# Select multiple scope patterns (comma-separated)
  npx @auth0/auth0-mcp-server init --scopes 'read:*,create:clients,update:actions'
  ```

> [!NOTE]
> Selected scopes determine what operations the MCP server can perform on your Auth0 tenant.

### ⚙️ Configuration

#### Other MCP Clients:

To use Auth0 MCP Server with any other MCP Client, you can add this configuration to the client and restart for changes to take effect:

> [!NOTE]  
> You can manually update if needed or if any unexpected errors occur during the npx init command.

### 🚨 Common Issues

1. **Authentication Failures**
   - Ensure you have the correct permissions in your Auth0 tenant
   - Try re-initializing with `npx @auth0/auth0-mcp-server init`

2. **Claude Desktop Can't Connect to the Server**
   - Restart Claude Desktop after installation
   - Check that the server is running with `ps aux | grep auth0-mcp`

3. **API Errors or Permission Issues**
   - Enable debug mode with `export DEBUG=auth0-mcp`
   - Check your Auth0 token status: `npx @auth0/auth0-mcp-server session`
   - Reinitialize with specific scopes: `npx @auth0/auth0-mcp-server init --scopes 'read:*,update:*,create:*'`
   - If a specific operation fails, you may be missing the required scope

4. **Invalid Auth0 Configuration Error**
   - This typically happens when your authorization token is missing or expired
   - Run `npx @auth0/auth0-mcp-server session` to check your token status
   - If expired or missing, run `npx @auth0/auth0-mcp-server init` to authenticate

> [!TIP]
> Most connection issues can be resolved by restarting both the server and Claude Desktop.

## 📋 Debug logs

Enable debug mode to view detailed logs:

```sh
export DEBUG=auth0-mcp
```

Get detailed MCP Client logs from Claude Desktop:

```sh
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```

For advanced troubleshooting, use the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector -e DEBUG='auth0-mcp' @auth0/auth0-mcp-server run
```

For detailed MCP Server logs, run the server in debug mode:

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

## 👨‍💻 Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/auth0/auth0-mcp-server.git
cd auth0-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Initiate device auth flow
npx . init

# Configure your MCP Client (e.g. Claude Desktop) with MCP server path
npm run setup
```

### Development Scripts

```bash
# Run directly with TypeScript (no build needed)
npm run dev

# Run with debug logs enabled
npm run dev:debug

# Run with MCP inspector for debugging
npm run dev:inspect

# Run the compiled JavaScript version
npm run start
```

> [!NOTE]
> This server requires [Node.js v18 or higher](https://nodejs.org/en/download).

## 🔒 Security

The Auth0 MCP Server prioritizes security:

- Credentials are stored in the system's secure keychain
- No sensitive information is stored in plain text
- Authentication uses OAuth 2.0 device authorization flow
- No permissions (scopes) are requested by default
- Interactive scope selection allows you to choose exactly which permissions to grant
- Support for glob patterns to quickly select related scopes (e.g., `read:*`)
- Easy token removal via `logout` command when no longer needed

> [!IMPORTANT]
> For security best practices, always use `npx @auth0/auth0-mcp-server logout` when you're done with a session or switching between tenants. This ensures your authentication tokens are properly removed from the system keychain.

> [!CAUTION]
> Always review the permissions requested during the authentication process to ensure they align with your security requirements.

## Anonymized Analytics Disclosure

Anonymized data points are collected during the use of this MCP server. This data includes the MCP version, operating system, timestamp, and other technical details that do not personally identify you.

Auth0 uses this data to better understand the usage of this tool to prioritize the features, enhancements and fixes that matter most to our users.

To **opt-out** of this collection, set the `AUTH0_MCP_ANALYTICS` environment variable to `false`.

## 💬 Feedback and Contributing

We appreciate feedback and contributions to this project! Before you get started, please see:

- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)

### Reporting Issues

To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-mcp-server/issues).

### Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.

## 📄 License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

## What is Auth0?

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/auth0-logos/2023-branding/favicon/auth0-icon-ondark.svg" width="150" height="75">
    <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/auth0-logos/2023-branding/favicon/auth0-icon-onlight.svg" width="150" height="75">
    <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
  </picture>
</p>
<p align="center">
  Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
</p>

auth0-mcp-server

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

auth0-mcp-server

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README