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

> Build run the Auth0 MCP Server from source locally for development. Clone the repo, install dependencies, authenticate, and start using npm commands.

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

---

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

```bash
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`](https://github.com/auth0/auth0-mcp-server/blob/main/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:

```bash
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:

```bash
npx . init

```

According to the source code in [`src/commands/init.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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:

```bash

# 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`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts), registering handlers for `ListTools` and `CallTool` requests over `StdioServerTransport`.

## Understanding the Server Architecture

### Configuration Management

The [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/init.ts)**: Handles device authorization and credential storage
- **[`run.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/mcp.json) or settings UI:

```json
{
  "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:

```json
{
  "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`](https://github.com/auth0/auth0-mcp-server/blob/main/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:

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

```

**Filter specific tool categories** using glob patterns:

```bash

# 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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) and tools filtered via [`src/utils/tools.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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`](https://github.com/auth0/auth0-mcp-server/blob/main/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.