# How to Debug Connection Issues Between Claude Desktop and the Auth0 MCP Server Using Debug Mode

> Debug connection issues between Claude Desktop and Auth0 MCP Server. Enable debug mode for verbose logs showing timeouts, credential errors, and config path problems.

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

---

**Enable debug mode by setting `AUTH0_MCP_DEBUG=true` or `DEBUG=auth0-mcp` to expose verbose logs that reveal transport timeouts, missing Auth0 credentials, and configuration path errors in stderr.**

Debugging connection failures between Claude Desktop and the Auth0 MCP server requires visibility into the stdio transport layer and authentication flow. By activating debug mode in the `auth0/auth0-mcp-server` repository, you can inspect the exact failure point—whether it’s a missing token, configuration path error, or transport timeout—through detailed logs written to stderr.

## What Debug Mode Does in the Auth0 MCP Server

The MCP server uses the **`debug`** library to emit verbose logs that are suppressed by default. Debug mode activates when you export either `AUTH0_MCP_DEBUG=true` or include `auth0-mcp` in the standard `DEBUG` environment variable.

In [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) (lines 16-19), the server checks these variables to determine logging verbosity. When enabled, the **`log`** function exported from [`src/utils/logger.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/logger.ts) (lines 1-10) writes lines prefixed with `[DEBUG:auth0-mcp]` to **stderr**. This captures internal events including configuration loading, token validation, request handling, and transport connection attempts.

## Where Claude Desktop Interacts With the Server

Three components govern the connection handshake:

- **Configuration discovery** – The `ClaudeClientManager` class in [`src/clients/claude.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/claude.ts) (lines 24-42) locates the Claude Desktop configuration file on the host machine.
- **Transport initialization** – The `startServer` function in [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 44-46) creates a `StdioServerTransport` that communicates via standard input/output.
- **Connection timeout** – The server attempts to connect to the transport with a strict 5-second timeout. If the transport fails to become readable/writable, [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 48-54) logs a *Connection timeout* error and re-throws the exception.

## Identifying Common Failure Points

Use the debug logs to map symptoms to root causes:

- **No logs appear at all** – Debug mode is not enabled or environment variables are not exported. Look for the startup line `Debug mode: false` in [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) output.
- **`[ERROR:auth0-mcp]` about missing credentials** – The stored Auth0 token or domain is missing or expired. The server validates configuration immediately after loading ([`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts), lines 54-60) and again before each tool call (lines 94-101), logging specific messages like `Auth0 token is missing` or `Auth0 token is expired`.
- **`Connection timeout`** – The stdio transport never initialized, indicating Claude Desktop is not running, the wrong executable was launched, or the pipe is broken. The server logs this in [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 66-73) with a hint about stdio transport issues.
- **Logs stop after "Initializing Auth0 MCP server…"** – The process crashed early, often due to a missing `HOME` environment variable. The config loader in [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) (lines 10-14) ensures `HOME` is set and logs adjustments.
- **Tool-specific errors** – After connection succeeds, each tool handler logs `Received tool call:` and `Executing handler for tool:`. If a handler throws, [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 84-90) emits `Error handling tool call:` with the underlying stack trace.

## Step-by-Step Debugging Workflow

### 1. Start the Server in Debug Mode

Export the environment variable before launching the process.

On macOS or Linux:

```bash
export AUTH0_MCP_DEBUG=true

# Alternative: export DEBUG=auth0-mcp

npx auth0-mcp-server start

```

On Windows PowerShell:

```powershell
$env:AUTH0_MCP_DEBUG = "true"
npx auth0-mcp-server start

```

You should see the first line:

```

[DEBUG:auth0-mcp] Debug mode: true

```

### 2. Confirm Claude Desktop Configuration Path

Verify that the server can locate the Claude Desktop configuration file. The `ClaudeClientManager` in [`src/clients/claude.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/claude.ts) (lines 32-42) resolves paths differently per OS:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

To programmatically inspect the resolved path:

```typescript
import { ClaudeClientManager } from './src/clients/claude.js';

const claudeMgr = new ClaudeClientManager();
console.log('Claude config path ->', claudeMgr.getConfigPath());

```

### 3. Watch the Connection Phase

After the server prints `Creating stdio transport…` and `Connecting server to transport…`, a successful connection yields:

```

[INFO:auth0-mcp] Auth0 MCP Server version X.Y.Z running on stdio with 12/15 tools available

```

If you see `Connection timeout` followed by *“This might indicate an issue with the stdio transport”* (from [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts), lines 66-73), verify that:

- Claude Desktop is running and waiting for the server process.
- No other process is bound to the same stdio pipe.

### 4. Inspect Tool Calls

When Claude issues a request, the logs show:

```

[DEBUG:auth0-mcp] Received tool call: listApplications
[DEBUG:auth0-mcp] Executing handler for tool: listApplications

```

If the handler throws, the next line contains `Error handling tool call:` with the specific error message, allowing you to identify which tool implementation in `src/tools/*` requires attention.

### 5. Validate Token and Domain

The server logs credential validation results immediately after loading configuration. If you see `Auth0 token is expired`, refresh the token by re-authenticating with the Auth0 CLI (`auth0 login`) or triggering the device-flow refresh logic.

### 6. Iterate and Re-test

Adjust environment variables, restart Claude Desktop, or correct the underlying configuration file. Re-run the server with debug mode active and repeat the steps until the connection handshake succeeds.

## Summary

- **Activate debug mode** by setting `AUTH0_MCP_DEBUG=true` or `DEBUG=auth0-mcp` to enable verbose `[DEBUG:auth0-mcp]` logs written to stderr.
- **Monitor [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts)** for transport initialization and the 5-second connection timeout that indicates stdio pipe issues.
- **Check [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts)** for credential validation errors and `HOME` environment variable requirements.
- **Use [`src/clients/claude.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/claude.ts)** logic to verify the configuration file path matches your operating system.
- **Trace tool execution** through handler logs in [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 84-90) to isolate post-connection failures.

## Frequently Asked Questions

### How do I enable debug mode for the Auth0 MCP server?

Set the environment variable `AUTH0_MCP_DEBUG=true` or include `auth0-mcp` in the `DEBUG` variable before starting the process. This activates the logger in [`src/utils/logger.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/logger.ts), causing the server to emit detailed diagnostic lines prefixed with `[DEBUG:auth0-mcp]` to stderr.

### What does the "Connection timeout" error mean in Claude Desktop?

This error, thrown in [`src/server.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/server.ts) (lines 48-54) after a 5-second wait, indicates the `StdioServerTransport` failed to establish a readable/writable connection. It typically means Claude Desktop is not running, the server was launched independently instead of by Claude, or the stdio pipe is blocked by another process.

### Why don't I see any debug logs when starting the server?

If no logs appear, debug mode is likely disabled. Verify that `AUTH0_MCP_DEBUG` is exported in the same shell session launching the server, or that your `DEBUG` variable includes the `auth0-mcp` namespace. The server logs `Debug mode: false` on startup when the check in [`src/utils/config.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/utils/config.ts) (lines 16-19) fails.

### How do I verify Claude Desktop is using the correct configuration file?

The `ClaudeClientManager` class in [`src/clients/claude.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/claude.ts) (lines 32-42) resolves the config path based on the OS. You can run a short TypeScript snippet to print `claudeMgr.getConfigPath()` and confirm it matches the expected location (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). If the path is wrong, Claude Desktop may not recognize the MCP server registration.