Configuration

Overview

MCP Filesystem Ultra is configured entirely through command-line flags. These flags are passed via the args array in your claude_desktop_config.json (for Claude Desktop) or directly when running the binary.

All flags are optional — the server runs with sensible defaults out of the box.

Quick Start Configuration

Minimal (Claude Desktop)

{
  "mcpServers": {
    "filesystem-ultra": {
      "command": "C:\\path\\to\\filesystem-ultra-v4.exe",
      "args": [
        "C:\\Users\\you\\projects"
      ]
    }
  }
}

Recommended (Production)

{
  "mcpServers": {
    "filesystem-ultra": {
      "command": "C:\\path\\to\\filesystem-ultra-v4.exe",
      "args": [
        "--compact-mode",
        "--cache-size", "200MB",
        "--parallel-ops", "8",
        "--max-search-results", "50",
        "--max-list-items", "100",
        "--backup-dir", "C:\\Backups\\MCP",
        "--backup-max-age", "14",
        "--backup-max-count", "200",
        "--log-dir", "C:\\Logs\\MCP",
        "--log-level", "error",
        "C:\\Users\\you\\projects",
        "C:\\Backups\\MCP"
      ]
    }
  }
}

Complete CLI Flags Reference

Access Control

Flag	Type	Default	Description
`--allowed-paths`	string	(none)	Comma-separated list of allowed base paths. Files outside these paths cannot be accessed.

Allowed paths can also be passed as positional arguments after all flags:

# Using --allowed-paths flag
filesystem-ultra-v4.exe --allowed-paths "C:\project,C:\backups"

# Using positional arguments (equivalent)
filesystem-ultra-v4.exe C:\project C:\backups

# Both formats work together
filesystem-ultra-v4.exe --compact-mode C:\project C:\backups

When --allowed-paths is empty (the default), there are no restrictions. When set, all operations verify that the target path is within one of the allowed directories. Symlinks are resolved via filepath.EvalSymlinks() before checking containment.

Important: If you configure --backup-dir, include that directory in your allowed paths so backup operations can access it.

Token Optimization

Flag	Type	Default	Description
`--compact-mode`	boolean	false	Enable compact responses that minimize token usage (65-75% savings). Responses use shorter formats, fewer headers, and abbreviated metadata.
`--max-response-size`	string	`10MB`	Maximum response size. Accepts size suffixes: `KB`, `MB`, `GB`. Responses exceeding this limit are truncated.
`--max-search-results`	integer	1000	Maximum number of search results returned by `search_files`. Lower values reduce token consumption for broad searches.
`--max-list-items`	integer	500	Maximum items returned in directory listings by `list_directory`. Lower values reduce token consumption for large directories.

Compact mode example:

Without compact mode (approximately 50 tokens per directory entry):

Directory listing for: C:\project\src

Type    Name                    Size        Modified
----------------------------------------------------
[DIR]   components              -           2026-03-10
[FILE]  index.ts                2.3 KB      2026-03-10

With compact mode (approximately 3 tokens per entry):

src: components/, index.ts(2KB), app.tsx(5KB)

Performance

Flag	Type	Default	Description
`--cache-size`	string	`100MB`	Memory cache limit for the 3-tier caching system (file content, directory listings, metadata). Accepts size suffixes: `KB`, `MB`, `GB`.
`--parallel-ops`	integer	2x CPU cores (max 16)	Maximum number of concurrent file operations. Higher values improve throughput for batch and pipeline workloads.
`--binary-threshold`	string	`1MB`	File size threshold for binary protocol detection. Files larger than this threshold may use different handling strategies.

Cache sizing guidance:

Cache Size	Recommended For	Typical Memory Usage
`50MB`	Small projects, constrained environments	50-80 MB
`100MB`	Default, most development work	80-120 MB
`200MB`	Large codebases, frequent repeated reads	150-250 MB
`500MB`	Enterprise projects, log analysis	200-400 MB

The cache uses automatic eviction — when the limit is reached, the oldest entries are removed. Cache hit rates typically reach 85-95% during a session and 98%+ after warmup.

Backup System

Flag	Type	Default	Description
`--backup-dir`	string	System temp directory	Directory for backup storage. Default: `%TEMP%\mcp-batch-backups` (Windows) or `/tmp/mcp-batch-backups` (Linux/WSL).
`--backup-max-age`	integer	7	Maximum age of backups in days. Backups older than this are eligible for cleanup.
`--backup-max-count`	integer	100	Maximum number of backups to keep. When exceeded, the oldest backups are deleted automatically.

Example configuration:

{
  "args": [
    "--backup-dir", "C:\\Backups\\MCP",
    "--backup-max-age", "14",
    "--backup-max-count", "200",
    "C:\\project",
    "C:\\Backups\\MCP"
  ]
}

Important: The backup directory must be included in allowed paths (either via --allowed-paths or as a positional argument) for the backup tool to access it.

Backups are created automatically before destructive operations (edit_file, delete_file, multi_edit, and batch/pipeline destructive steps). Each backup is stored in its own directory with a unique ID:

20260313-143022-abc123/
  metadata.json       # Backup information (timestamp, operation, context)
  files/
    your_file.go      # Backed up file contents

Risk Assessment

Flag	Type	Default	Description
`--risk-threshold-medium`	float	20.0	Percentage of file change that triggers MEDIUM risk level.
`--risk-threshold-high`	float	75.0	Percentage of file change that triggers HIGH risk level.
`--risk-occurrences-medium`	integer	50	Number of replacement occurrences that triggers MEDIUM risk.
`--risk-occurrences-high`	integer	100	Number of replacement occurrences that triggers HIGH risk.

Risk level behavior:

Level	Conditions (defaults)	What Happens
LOW	< 20% change, < 50 occurrences	Proceeds silently
MEDIUM	20-74% change, or 50-100 occurrences	Auto-proceeds with backup and risk notice
HIGH	75-89% change, or > 100 occurrences	Auto-proceeds with backup and prominent warning
CRITICAL	>= 90% change	Blocked — requires `force: true`

Adjusting thresholds for stricter or more lenient editing:

{
  "args": [
    "--risk-threshold-medium", "15.0",
    "--risk-threshold-high", "50.0",
    "--risk-occurrences-medium", "30",
    "--risk-occurrences-high", "75"
  ]
}

Only CRITICAL risk (>= 90% of file content changed) blocks the operation. MEDIUM and HIGH risk edits auto-proceed with an automatic backup. This design eliminates wasteful retry round-trips in agentic workflows.

Hooks System

Flag	Type	Default	Description
`--hooks-enabled`	boolean	false	Enable the pre/post operation hook system. Hooks allow custom validation and formatting logic for 12 event types.
`--hooks-config`	string	(none)	Path to a hooks configuration JSON file. Required when `--hooks-enabled` is true.

Hook event types:

The hook system supports 12 event types: pre/post for read, write, edit, delete, search, and list operations. Hooks can validate parameters, transform content, enforce policies, and format output.

Example hooks configuration:

{
  "hooks": [
    {
      "event": "pre_write",
      "type": "validate",
      "config": {
        "max_file_size": 5242880,
        "blocked_extensions": [".exe", ".dll"]
      }
    },
    {
      "event": "post_edit",
      "type": "format",
      "config": {
        "formatter": "gofmt",
        "extensions": [".go"]
      }
    }
  ]
}

See Hooks for detailed documentation.

Logging and Audit

Flag	Type	Default	Description
`--log-level`	string	`info`	Log level for stderr output. Values: `debug`, `info`, `warn`, `error`. Uses `slog` with JSON handler.
`--debug`	boolean	false	Enable debug mode. Equivalent to `--log-level debug` but also enables additional diagnostic output.
`--log-dir`	string	(none)	Directory for audit logs and metrics snapshots. When set, enables operation logging for all 16 tool invocations.

Audit logging (when --log-dir is set):

The server writes two files:

File	Format	Description
`operations.jsonl`	JSON Lines	One entry per tool call with timing, status, path, bytes, file size, args summary, risk level, lines changed, and match count. Auto-rotates at 10 MB, keeps the last 3 files.
`metrics.json`	JSON	Performance metrics snapshot updated every 30 seconds.

When --log-dir is not set, audit logging is disabled with zero overhead — the auditWrap() function returns the handler unchanged.

Example:

{
  "args": [
    "--log-dir", "C:\\Logs\\MCP",
    "--log-level", "warn"
  ]
}

The audit logs can be viewed through the separate Dashboard binary. See below.

Miscellaneous

Flag	Type	Default	Description
`--version`	boolean	false	Print version information and exit.
`--bench`	boolean	false	Run a performance benchmark and exit.
`--vscode-api`	boolean	true	Enable VS Code API integration when available.

Dashboard Configuration

The Dashboard is a separate binary (dashboard.exe) that reads audit logs and serves a web UI for monitoring.

# Build the dashboard
go build -ldflags="-s -w" -trimpath -o dashboard.exe ./cmd/dashboard/

# Run
dashboard.exe --log-dir=C:\Logs\MCP --backup-dir=C:\Backups\MCP --port=9100

Flag	Default	Description
`--log-dir`	(required)	Same directory as the MCP server’s `--log-dir`
`--backup-dir`	(required)	Same directory as the MCP server’s `--backup-dir`
`--port`	9100	HTTP port for the dashboard UI

The dashboard and MCP server communicate only through files — there is no direct coupling. The dashboard reads operations.jsonl and metrics.json, and provides real-time updates via Server-Sent Events (SSE).

Dashboard pages: Dashboard (metrics), Operations (audit log), Backups (enterprise recovery), Statistics, Proxy/Tokens, Edit Analysis.

Configuration Profiles

Minimal Token Usage

For environments where token cost is the primary concern:

{
  "args": [
    "--compact-mode",
    "--max-search-results", "20",
    "--max-list-items", "50",
    "--log-level", "error",
    "C:\\project"
  ]
}

Maximum Performance

For batch workloads and large codebases:

{
  "args": [
    "--cache-size", "500MB",
    "--parallel-ops", "16",
    "--max-search-results", "2000",
    "C:\\project"
  ]
}

Full Observability

For enterprise environments with audit requirements:

{
  "args": [
    "--compact-mode",
    "--cache-size", "200MB",
    "--parallel-ops", "8",
    "--log-dir", "C:\\Logs\\MCP",
    "--log-level", "info",
    "--backup-dir", "C:\\Backups\\MCP",
    "--backup-max-age", "30",
    "--backup-max-count", "500",
    "--hooks-enabled",
    "--hooks-config", "C:\\config\\mcp-hooks.json",
    "C:\\project",
    "C:\\Backups\\MCP",
    "C:\\Logs\\MCP"
  ]
}

Strict Security

For environments with tight access control:

{
  "args": [
    "--allowed-paths", "C:\\project\\src,C:\\project\\tests",
    "--risk-threshold-medium", "10.0",
    "--risk-threshold-high", "40.0",
    "--risk-occurrences-medium", "20",
    "--risk-occurrences-high", "50",
    "--backup-max-count", "500",
    "--log-dir", "C:\\Logs\\MCP",
    "C:\\project\\src",
    "C:\\project\\tests"
  ]
}

Environment Variables

The server does not read environment variables directly. All configuration is through CLI flags. However, the server detects the following environment conditions automatically:

WSL detection: Auto-detects when running inside Windows Subsystem for Linux
CPU count: Used to set default --parallel-ops (2x CPU cores, max 16)
Temp directory: Used as default --backup-dir when not specified

Runtime Configuration

Some settings can be checked or adjusted at runtime:

// View current performance settings and cache stats
server_info({ action: "stats" })

// View tool documentation and available features
server_info({ action: "help", topic: "overview" })

// Configure WSL auto-sync at runtime
wsl({ action: "autosync_config", enabled: true, sync_on_write: true })