auth0-mcp-server

MCP (Model Context Protocol) is an open protocol introduced by Anthropic that standardizes how large language models communicate with external tools, resources or remote services.

⚠ Beta Feature Notice:This feature is currently in Beta. Please use with caution when calling tools, as functionality may be unstable or subject to change.

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 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?

🚀 Getting Started

Prerequisites:

• Node.js v18 or higher
• Claude Desktop or any other MCP Client
• Auth0 account with appropriate permissions

Install the Auth0 MCP Server

Install Auth0 MCP Server and configure it to work with your preferred MCP client.

Claude Desktop

npx @auth0/auth0-mcp-server init

Windsurf

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

Cursor

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

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:

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

Authenticate 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. Checkout Authentication for more info.

Verify your integration

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

🛠️ Supported Tools

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

Applications

Resource Servers

Actions

Logs

Forms

🕸️ 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:

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.

[!IMPORTANT]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

Session Management

To see information about your current authentication session:

npx @auth0/auth0-mcp-server session

Logging Out

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

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

Get command line help: View a list of supported commands and usage examples

# Command help
npx @auth0/auth0-mcp-server help

# Initialize the server (authenticate and configure)
npx @auth0/auth0-mcp-server init

# Initialize with specific scopes (supports glob patterns)
npx @auth0/auth0-mcp-server init --scopes 'read:*,create:clients'

# Run the server
npx @auth0/auth0-mcp-server run

# Display current session information
npx @auth0/auth0-mcp-server session

# Remove Auth0 tokens from keychain
npx @auth0/auth0-mcp-server logout

🚥 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:

  # 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:

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

[!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 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 permissions and expiration
   • 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

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

📋 Debug logs

Enable debug mode to view detailed logs:

export DEBUG=auth0-mcp

Get detailed MCP Client logs from Claude Desktop:

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

For advanced troubleshooting, use the MCP Inspector:

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

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

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

👨‍💻 Development

Building from Source

# 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(Claude Desktop) with MCP server path
npm run local-setup

# Restart MCP client, in this case claude desktop app

[!NOTE]This server requires Node.js v18 or higher.

🔒 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.

💬 Feedback and Contributing

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

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

Reporting Issues

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

📄 License

This project is licensed under the MIT license. See the LICENSE file for more info.

What is Auth0?

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?