How to Build and Run the Auth0 MCP Server from Source for Local Development

Clone the repository, install dependencies with npm install, authenticate via npx . init, and start the server using npm run dev or npm run start to run the Auth0 MCP Server locally for development.

The Auth0 MCP Server acts as a secure bridge between AI assistants and the Auth0 Management API, implementing the Model Context Protocol (MCP) to enable AI-driven tenant management. This guide walks you through building and running the auth0/auth0-mcp-server repository from source for local development and testing.

Step-by-Step Build and Run Instructions

1. Clone the Repository and Install Dependencies

Start by cloning the official repository and installing Node.js dependencies:

git clone https://github.com/auth0/auth0-mcp-server.git
cd auth0-mcp-server
npm install

The project uses standard npm workflows defined in package.json, which includes build scripts for TypeScript compilation and development watching.

2. Compile the TypeScript Source

Build the project to generate compiled JavaScript in the dist/ directory:

npm run build

This step is required before running the production version, though you can skip it when using the development server that runs TypeScript directly.

3. Authenticate Using the Device Flow

Initialize authentication to store your Auth0 credentials securely in the system keychain:

npx . init

According to the source code in src/commands/init.ts, this command launches the OAuth 2.0 device-authorization flow in your browser. The loadConfig function in src/utils/config.ts then reads and stores your Auth0 tenant, domain, and token locally, while validateConfig verifies token validity before each server start.

4. Start the Local Development Server

Run the server using either the compiled version or the development watcher:

# Hot-reloading development mode (TypeScript on-the-fly)

npm run dev

# Or run the compiled version

npm run start

The server initializes an MCP instance using @modelcontextprotocol/sdk/server as implemented in src/server.ts, registering handlers for ListTools and CallTool requests over StdioServerTransport.

Understanding the Server Architecture

Configuration Management

The src/utils/config.ts file contains the core credential logic. The loadConfig function retrieves stored tokens from the system keychain, while validateConfig ensures the Auth0 token remains valid before executing management API calls. This validation runs during server startup and again within the CallTool handler before forwarding requests.

Tool Discovery and Filtering

Tool definitions reside in src/tools/**/*.ts. The getAvailableTools function in src/utils/tools.ts dynamically filters available tools based on CLI arguments:

• --read-only: Restricts operations to read-only tools (GET requests)
• --tools: Accepts a glob pattern to limit exposure (e.g., auth0_*_application*)

MCP Protocol Implementation

In src/server.ts, the server registers two primary request handlers:

• ListTools: Returns sanitized tool definitions based on filtering flags
• CallTool: Validates configuration, injects the Auth0 token via formatDomain, and dispatches to the appropriate handler in the HANDLERS registry

The transport layer uses StdioServerTransport from the MCP SDK, reading JSON-RPC messages from stdin and writing responses to stdout, enabling any MCP-compatible client to launch the server via npx.

CLI Command Structure

The src/commands/ directory implements the command-line interface:

• init.ts: Handles device authorization and credential storage
• run.ts: Parses --tools and --read-only flags before starting the server
• session: Displays current token information via npx @auth0/auth0-mcp-server session
• logout: Removes credentials from the keychain

Configuring MCP Clients for Local Development

To test your local build with AI clients like Claude Desktop or Gemini, add the following configuration to your client's mcp.json or settings UI:

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

For development builds, replace the npx command with a direct path to your local repository:

{
  "mcpServers": {
    "auth0-local": {
      "command": "node",
      "args": ["/path/to/auth0-mcp-server/dist/index.js", "run"],
      "capabilities": ["tools"]
    }
  }
}

Verify the connection by asking your AI assistant to list Auth0 applications. The client will request the tool list from src/server.ts, then invoke the appropriate handler from src/tools/, which formats the domain and forwards the call to the Auth0 Management API.

Advanced Local Development Options

Run with read-only restrictions to prevent accidental modifications during testing:

npx @auth0/auth0-mcp-server run --read-only

Filter specific tool categories using glob patterns:

# Only application management tools

npx @auth0/auth0-mcp-server run --tools 'auth0_*_application*'

# List and get operations only

npx @auth0/auth0-mcp-server run --read-only --tools 'auth0_list_*,auth0_get_*'

Debug mode enables verbose logging via the DEBUG=auth0-mcp environment variable, useful when troubleshooting tool handlers in src/tools/**/*.ts.

Summary

• Clone and install: Use git clone and npm install to prepare the development environment
• Build process: Run npm run build to compile TypeScript to dist/, or use npm run dev for hot-reloading
• Authentication: Execute npx . init to store credentials via the device flow implemented in src/commands/init.ts
• Server startup: Launch with npm run start (compiled) or npm run dev (TypeScript direct)
• Architecture: The server uses StdioServerTransport for MCP communication, with configuration managed in src/utils/config.ts and tools filtered via src/utils/tools.ts
• Client integration: Configure MCP clients to launch the local server binary for testing AI-assisted Auth0 management

Frequently Asked Questions

How do I reset my Auth0 credentials when testing locally?

Run npx @auth0/auth0-mcp-server logout to remove the stored token from your system keychain. According to the source implementation, this clears the credentials used by loadConfig in src/utils/config.ts, allowing you to re-authenticate with npx . init using a different tenant or token.

Can I run the server without compiling the TypeScript first?

Yes. Use npm run dev to run the server directly from TypeScript source using ts-node or similar development dependencies defined in package.json. This mode provides hot-reloading for rapid iteration on handlers in src/tools/**/*.ts without waiting for npm run build to complete.

Which environment variables control debug output?

Set DEBUG=auth0-mcp in your environment or MCP client configuration to enable verbose logging. The server implementation checks this variable during initialization to log request handling, token validation, and tool execution details from src/server.ts and related handler files.

How do I limit tool exposure for security testing?

Use the --read-only flag to restrict operations to GET requests only, or specify a --tools glob pattern to whitelist specific functionality. The getAvailableTools function in src/utils/tools.ts filters the full registry from src/tools/**/*.ts based on these CLI arguments before registering handlers with the MCP server instance.

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