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

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). 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:

// 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) 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) 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:

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:

// 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) 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:

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

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

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) operates as a thin wrapper around the base class, utilizing standard path resolution logic while maintaining the same ClientOptions interface.

Configuration command:

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:

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

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

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

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

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) accepts the tools array and passes it to startServer():

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
• VS Code supports both global and workspace scopes via VSCodeClientManager, storing configs in 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, global configurations reside at ~/Library/Application Support/Code/User/mcp.json on macOS, while workspace configurations write to .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 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.

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