# How to Configure Different MCP Clients (VS Code, Cursor, Windsurf, Gemini CLI) with Specific Tool Restrictions

> Easily configure Auth0 MCP clients like VS Code, Cursor, and Gemini CLI. Learn to use the --tools flag for specific tool restrictions on each client.

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

---

**To configure different MCP clients with specific tool restrictions, use the `--tools` flag with the Auth0 MCP CLI to limit available capabilities on a per-client basis.**

The `auth0/auth0-mcp-server` repository provides a **client-manager abstraction** that writes editor-specific MCP server configurations, allowing you to restrict which Auth0 management tools are exposed in each integrated development environment. By leveraging the `BaseClientManager` class and its concrete implementations, you can deploy tailored tool sets for VS Code, Cursor, Windsurf, and Gemini CLI from a single CLI interface.

## Understanding the Client Manager Architecture

The Auth0 MCP server uses an inheritance model where all client managers extend `BaseClientManager` located in [[`src/clients/base.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/base.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/base.ts). This base class handles the core logic for converting user options into executable server configurations.

### BaseClientManager and ServerConfig

The `BaseClientManager.createServerConfig()` method transforms `ClientOptions` into a `ServerConfig` object that specifies how the MCP server launches:

```typescript
// src/clients/base.ts
protected createServerConfig(options: ClientOptions): ServerConfig {
  const args = ['-y', packageName, 'run', '--tools', `${options.tools.join(',')}`];
  if (options.readOnly) {
    args.push('--read-only');
  }
  return {
    command: 'npx',
    args,
    env: { DEBUG: 'auth0-mcp' },
    ...(this.capabilities?.length && { capabilities: this.capabilities })
  };
}

```

Each concrete manager (VSCodeClientManager, CursorClientManager, etc.) inherits this method and only overrides the configuration file path resolution.

### Tool Restriction Mechanism

Tool restrictions flow through the system in three stages:

1. **CLI Parsing**: The `run` command in [[`src/commands/run.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/run.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/run.ts) accepts a `--tools` flag with comma-separated values (e.g., `actions,applications`)
2. **Config Generation**: The `tools` array joins into a comma-separated string injected into the server arguments array
3. **Server Enforcement**: When the editor launches the MCP server, it passes these arguments, causing the server to register only the specified tools

## Configuring Individual MCP Clients

Each client manager writes to a platform-specific configuration file location. All support the same `--tools` and `--read-only` options, but VS Code offers additional scope controls.

### VS Code Configuration

The `VSCodeClientManager` in [[`src/clients/vscode.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/vscode.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/vscode.ts) supports both global and workspace-scoped configurations.

**Configuration file locations:**

- **Global**: `~/Library/Application Support/Code/User/mcp.json` (macOS), `%APPDATA%/Code/User/mcp.json` (Windows), or `~/.config/Code/User/mcp.json` (Linux)
- **Workspace**: `<workspace>/.vscode/mcp.json`

**Configuration example:**

```bash
npx @auth0/auth0-mcp-server configure vscode --tools actions,applications --scope global

```

The manager handles scope selection through `promptForScope()` and `promptForWorkspaceFolder()` when interactive options are omitted:

```typescript
// src/clients/vscode.ts
async configure(options: VSCodeClientOptions): Promise<void> {
  if (options.scope) {
    this.selectedScope = options.scope;
    this.selectedWorkspaceFolder = options.workspaceFolder;
  } else {
    this.selectedScope = await this.promptForScope();
  }
  if (this.selectedScope === 'workspace' && !this.selectedWorkspaceFolder) {
    this.selectedWorkspaceFolder = await this.promptForWorkspaceFolder();
  }
  const configPath = this.getConfigPath();
  const config = this.readVSCodeConfig(configPath);
  config.servers = config.servers ?? {};
  config.servers.auth0 = this.createServerConfig(options);
  this.writeVSCodeConfig(configPath, config);
}

```

### Cursor Configuration

The `CursorClientManager` in [[`src/clients/cursor.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/cursor.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/cursor.ts) uses a simplified path resolution strategy without scope options.

**Configuration file location:**

- `~/.cursor/mcp.json` (macOS/Linux)
- `%APPDATA%\.cursor\mcp.json` (Windows)

**Path resolution implementation:**

```typescript
// src/clients/cursor.ts
getConfigPath(): string {
  const configDir = getPlatformPath({
    darwin: path.join(os.homedir(), '.cursor'),
    win32: path.join('{APPDATA}', '.cursor'),
    linux: path.join(os.homedir(), '.cursor')
  });
  ensureDir(configDir);
  return path.join(configDir, 'mcp.json');
}

```

**Configuration command:**

```bash
npx @auth0/auth0-mcp-server configure cursor --tools resource-servers --read-only

```

### Windsurf Configuration

The `WindsurfClientManager` in [[`src/clients/windsurf.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/windsurf.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/windsurf.ts) targets the Codeium Windsurf editor with a distinct configuration path.

**Configuration file location:**

- `~/.codeium/windsurf/mcp_config.json` (macOS/Linux)
- `%APPDATA%\.codeium\windsurf\mcp_config.json` (Windows)

**Configuration command:**

```bash
npx @auth0/auth0-mcp-server configure windsurf --tools logs,users

```

### Gemini CLI Configuration

The `GeminiClientManager` in [[`src/clients/gemini.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/gemini.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/gemini.ts) operates as a thin wrapper around the base class, utilizing standard path resolution logic while maintaining the same `ClientOptions` interface.

**Configuration command:**

```bash
npx @auth0/auth0-mcp-server configure gemini --tools applications,connections

```

## Practical Configuration Examples

### Restricting VS Code to Specific Tools

To limit VS Code to only "actions" and "applications" tools while allowing read-write access:

```bash
npx @auth0/auth0-mcp-server configure vscode --tools actions,applications

```

This writes the following structure to the VS Code MCP configuration:

```json
{
  "servers": {
    "auth0": {
      "command": "npx",
      "args": ["-y", "auth0-mcp-server", "run", "--tools", "actions,applications"],
      "env": { "DEBUG": "auth0-mcp" }
    }
  }
}

```

### Different Tool Sets Per Client

Deploy divergent security policies across editors by running separate configuration commands:

```bash

# VS Code: Full access, read-only mode

npx @auth0/auth0-mcp-server configure vscode --read-only

# Cursor: Only resource server management

npx @auth0/auth0-mcp-server configure cursor --tools resource-servers

# Windsurf: Logging and user management only

npx @auth0/auth0-mcp-server configure windsurf --tools logs,users

```

### Dynamic Tool Selection at Runtime

For temporary tool restrictions without persisting to client configuration files, use the `run` command directly:

```bash
npx @auth0/auth0-mcp-server run --tools actions,applications

```

The `RunOptions` interface in [[`src/commands/run.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/run.ts)](https://github.com/auth0/auth0-mcp-server/blob/main/src/commands/run.ts) accepts the tools array and passes it to `startServer()`:

```typescript
export interface RunOptions {
  tools: string[];
  readOnly?: boolean;
}

```

## Summary

- **Client managers** inherit from `BaseClientManager` and handle editor-specific configuration paths while sharing tool restriction logic
- **Tool restrictions** use the `--tools` flag with comma-separated values, processed by `createServerConfig()` in [`src/clients/base.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/base.ts)
- **VS Code** supports both global and workspace scopes via `VSCodeClientManager`, storing configs in [`mcp.json`](https://github.com/auth0/auth0-mcp-server/blob/main/mcp.json) files
- **Cursor, Windsurf, and Gemini** use simplified managers that write to editor-specific directories (`.cursor/`, `.codeium/windsurf/`)
- **Read-only mode** applies globally via the `--read-only` flag, appended to server arguments when `options.readOnly` is true

## Frequently Asked Questions

### How do I restrict specific tools for only one editor while keeping full access in another?

Run the `configure` command for each client with different `--tools` arguments. The Auth0 MCP server stores separate configurations for each editor, allowing VS Code to run with all tools while restricting Cursor to only `resource-servers`, for example.

### Where does the Auth0 MCP server store VS Code configuration files?

According to the source code in [`src/clients/vscode.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/vscode.ts), global configurations reside at `~/Library/Application Support/Code/User/mcp.json` on macOS, while workspace configurations write to [`.vscode/mcp.json`](https://github.com/auth0/auth0-mcp-server/blob/main/.vscode/mcp.json) in your project root. The `VSCodeClientManager` determines the path based on the `scope` option passed to `configure()`.

### What is the difference between the `--tools` flag and the `--read-only` flag?

The `--tools` flag accepts a comma-separated list of tool identifiers (e.g., `actions,applications`) that determines which Auth0 management capabilities the MCP server registers. The `--read-only` flag is a boolean modifier that, when present, restricts all available tools to non-destructive operations. Both are processed in `BaseClientManager.createServerConfig()` and appended to the `args` array passed to `npx`.

### Can I use wildcard patterns or regular expressions in the `--tools` flag?

No, the `--tools` flag requires explicit comma-separated tool identifiers. The `createServerConfig()` method in [`src/clients/base.ts`](https://github.com/auth0/auth0-mcp-server/blob/main/src/clients/base.ts) joins the `options.tools` array directly without pattern matching. To enable all tools, pass the specific identifiers your Auth0 MCP server version supports, or omit the flag entirely to use server defaults.