MCP Server

Give every AI agent instant access to your filesystem.

The UFFS MCP server bridges AI agents to the UFFS daemon using the Model Context Protocol. Any MCP-compatible host — Claude Desktop, Cursor, Windsurf, Augment, Codeium, or your own tooling — can search, aggregate, and inspect files through UFFS with zero setup beyond a single config line.

Claude querying real NTFS data through the UFFS MCP server — deterministic search underneath, MCP on top. Recorded against the real endpoint with unedited timings (see the demo kit).

How It Works

┌──────────────┐                    ┌──────────────┐              ┌─────────────┐
│ AI Agent     │   MCP (stdio or    │ UFFS MCP     │  IPC socket  │ uffs-daemon  │
│ (Claude,     ├───HTTP)───────────▶│ Server       ├─────────────▶│ (in-memory   │
│  Cursor, …)  │   JSON-RPC 2.0    │ (bridge)     │              │  MFT index)  │
└──────────────┘                    └──────────────┘              └─────────────┘

The MCP server is a thin bridge — it translates MCP tool calls into daemon queries and returns results. It does not hold index data itself. The daemon must be running (it auto-starts when needed).

1 Two transports

	HTTP (recommended)	stdio
Sessions	Multi-session — many agents share one server	Single-session per AI host
Lifecycle	You manage: `uffs --mcp start` / `stop`	AI host manages: spawns and kills
Persistence	Stays running between agent restarts	Dies when agent disconnects
Setup	One `start`, then point hosts at URL	Config per host with `command` + `args`
Auth	Optional bearer token	No auth (pipe is private)
Best for	Production, shared environments, many hosts	Quick setup, single-agent use

2 Quick start

HTTP mode

# Start the MCP HTTP server (auto-starts daemon too)
# Windows — auto-discovers NTFS drives:
uffs --mcp start

# macOS / Linux — provide MFT data:
uffs --mcp start --data-dir ~/uffs_data

# Custom port:
uffs --mcp start --port 9090

# With authentication:
uffs --mcp start --auth-token MY_SECRET_TOKEN

# Check status:
uffs --mcp status

# Performance stats:
uffs --mcp stats

# Stop:
uffs --mcp stop

stdio mode

# Typically not run manually — configured in the AI host's MCP settings.
# The host spawns this process and communicates via stdin/stdout.
uffs --mcp run --data-dir ~/uffs_data

3 Host configuration

Claude Desktop / Claude Code

Add to settings.json or claude_desktop_config.json:

HTTP mode:

{
  "mcpServers": {
    "uffs": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

stdio mode:

{
  "mcpServers": {
    "uffs": {
      "command": "uffs",
      "args": ["mcp", "run", "--data-dir", "/path/to/uffs_data"]
    }
  }
}

Windows (no --data-dir needed):

{
  "mcpServers": {
    "uffs": {
      "command": "uffs",
      "args": ["mcp", "run"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "uffs": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Windsurf

Add to mcp_config.json:

{
  "mcpServers": {
    "uffs": {
      "serverUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

Augment Code

HTTP mode is auto-detected when the server is running. Stdio mode:

{
  "mcpServers": {
    "uffs": {
      "command": "uffs",
      "args": ["mcp", "run", "--data-dir", "/path/to/uffs_data"]
    }
  }
}

Standalone binary (alternative)

The uffs-mcp binary can be used instead of uffs --mcp run:

{
  "mcpServers": {
    "uffs": {
      "command": "uffs-mcp"
    }
  }
}

4 Tools

The MCP server exposes six read-only tools. All are annotated as readOnlyHint: true — they never modify the filesystem.

Tool	Required params	Description
`uffs_search`	`pattern`	Search files and directories with 40+ filter parameters
`uffs_aggregate`	—	Server-side analytics with 12 built-in presets
`uffs_facet_values`	`field`	Discover distinct values (extension, type, drive) with counts
`uffs_info`	`path`	Full metadata for a single file or directory
`uffs_drives`	—	List all indexed drives with record counts
`uffs_status`	—	Daemon health, uptime, memory, loading progress

`uffs_search`

The primary query tool. Accepts a pattern and any combination of filters (all ANDed). See Search Modes for pattern syntax and Filters for the full parameter list.

Key parameters:

Parameter	Example	Purpose
`pattern`	`"*.pdf"`, `"invoice"`, `">report_[0-9]+"`	Glob, substring, or regex (prefix `>`)
`filter`	`"files"`, `"dirs"`, `"all"`	File/directory filter
`ext`	`"pdf"`, `"pictures"`, `"archives"`	Extension or collection alias
`type_filter`	`"code"`, `"document"`, `"picture"`	Semantic type category
`min_size` / `max_size`	`1073741824`	Size in bytes (1 073 741 824 = 1 GB)
`newer` / `older`	`"7d"`, `"today"`, `"2026-01-01"`	Modification time filter
`path_contains`	`"Users\\rnio"`	Scope to a subtree
`drives`	`["C", "D"]`	Scope to specific drives
`sort`	`"-size"`, `"modified"`, `"-treesize"`	Sort field (prefix `-` for descending)
`limit`	`50`	Max results (default 50, cap 500)
`projection`	`["name", "size", "path"]`	Columns to return
`whole_word`	`true`	Word-boundary matching
`attr`	`"hidden"`, `"compressed"`	NTFS attribute filter

`uffs_aggregate`

Server-side analytics. Use preset for one-call answers or aggregations for custom specs. See Aggregation for full documentation.

{ "preset": "overview" }
{ "preset": "by_type", "drives": ["C"] }
{ "aggregations": ["terms:extension,top=30", "stats:size"] }

Available presets: overview, by_type, by_extension, by_drive, by_size, by_age, storage, activity, top_folders, duplicates, media, cleanup.

`uffs_facet_values`

Discover what exists before searching. Returns top-N values with counts and byte totals.

{ "field": "extension", "top": 20 }
{ "field": "type", "pattern": "*.log" }
{ "field": "drive" }

`uffs_info`

Full metadata for a single path:

{ "path": "C:\\Windows\\System32\\ntoskrnl.exe" }

Returns: size, allocated size, created/modified/accessed timestamps, NTFS flags, MFT record number, parent directory path.

5 Resources

Resources are read-only data that agents can access even when tool invocation is unavailable. This is critical — some MCP clients expose resources/read but not tools/call.

URI	Content	Agent use
`uffs://cookbook`	Curated example queries with ready-to-use arguments	Start here — learn query patterns fast
`uffs://schema/search`	JSON Schema for `uffs_search` parameters	Validate/construct search calls
`uffs://schema/aggregate`	JSON Schema for `uffs_aggregate` parameters	Validate/construct aggregate calls
`uffs://schema/fields`	Complete field catalog (types, capabilities)	Discover filterable/sortable fields
`uffs://presets/aggregate`	Aggregate preset names with descriptions	Choose the right preset
`uffs://drives`	Live drive listing with record counts	Check what's indexed
`uffs://status`	Daemon health, loading progress	Check readiness

Resource templates

URI template	Example	Content
`uffs://info/{path}`	`uffs://info/C%3A%5CWindows`	File/directory metadata

The {path} segment is percent-encoded (: → %3A, \ → %5C).

6 Prompts

Prompts are guided multi-step workflows that an agent can request and then execute step-by-step.

Prompt	Parameters	Workflow
`find_large_files`	`limit` (default 50)	Search for largest files
`find_by_extension`	`extension`, `limit`	Find all files with a given extension
`recent_changes`	`days` (default 1)	Files modified in the last N days
`find_duplicates_by_name`	`filename`	Find files with the same name across drives
`disk_usage_report`	`drive` (optional)	Multi-step: overview → type → extension → largest files
`cleanup_report`	`min_size_mb` (default 100)	Temp files, zero-byte, cleanup preset
`duplicate_investigation`	`extension` (optional)	Aggregate duplicates → search candidates

Agents request a prompt via prompts/get, receive structured instructions, then execute the steps using the tools above.

7 Server management

Commands

Command	Description
`uffs --mcp start`	Start the HTTP gateway as a background process
`uffs --mcp status`	Show PID, uptime, HTTP health, and load stats
`uffs --mcp stats`	Show performance metrics (queries, timing, sessions)
`uffs --mcp stop`	Graceful shutdown via HTTP `/shutdown`
`uffs --mcp kill`	Hard kill (SIGKILL / taskkill) + PID file cleanup
`uffs --mcp restart`	Stop → start with the same configuration
`uffs --mcp reload`	SIGHUP all stdio sessions + restart HTTP gateway

Status

$ uffs --mcp status
MCP HTTP Server
  PID:         89234
  Transport:   http:127.0.0.1:8080
  Uptime:      4h 23m
  Health:      200 OK
  Sessions:    3 active

Stats

$ uffs --mcp stats
═══ MCP Server Stats ═══
Uptime:            15732s
Tool calls:        847
  uffs_search:     612
  uffs_aggregate:  145
  uffs_facet:      52
  uffs_info:       28
  uffs_drives:     6
  uffs_status:     4
Resource reads:    23
Prompt gets:       8
Sessions:          12 total, 3 active
Avg tool latency:  2.4ms

8 HTTP endpoints

Method	Path	Auth	Description
`POST`	`/mcp`	Bearer (if configured)	MCP Streamable HTTP (JSON-RPC 2.0)
`GET`	`/mcp`	Bearer (if configured)	SSE event stream for server notifications
`DELETE`	`/mcp`	Bearer (if configured)	Close session
`GET`	`/health`	None	Liveness probe — always `200 OK`
`GET`	`/status`	None	Server status + uptime JSON

Authentication

When started with --auth-token, the HTTP gateway requires a bearer token on all /mcp requests:

uffs --mcp start --auth-token MY_SECRET

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer MY_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

The /health and /status endpoints are always unauthenticated.

Health check

$ curl http://127.0.0.1:8080/health
OK

$ curl http://127.0.0.1:8080/status
{
  "status": "ok",
  "uptime_secs": 3421,
  "sessions_active": 2,
  "tool_calls_total": 847
}

9 Agent instructions

When an agent connects, the MCP server sends agent instructions as part of the initialize response. These instructions teach the agent:

All 6 tools with one-line descriptions
A query strategy (aggregate → facet → search) that minimizes round-trips
Key parameters cheat sheet for uffs_search
Resource listing (including the cookbook)
Prompt listing

This means an agent can start using UFFS effectively without reading any external documentation — the instructions are embedded in the protocol.

10 Cookbook

The uffs://cookbook resource is the single most useful resource for agents learning to use UFFS. It contains ~30 ready-to-use examples organized into 10 categories:

Category	Examples
Quick Find	Glob, substring, whole-word, regex, drive-scoped
Size Triage	Top-N largest, >1 GB, large archives
Time Filters	Last 7d, >2yr old, created today
Type & Extension	Pictures, code, executables
Path Scoping	User home dir, project dirs, config files
Subtree Analysis	Largest dirs, empty dirs, crowded dirs
Cleanup	Temp files, zero-byte, bulkiness, long paths
Aggregation	All presets, scoped, custom specs
Facets	Extensions, drives, scoped facets
Advanced	Hidden files, NTFS compression, multi-step workflows

Each example includes:

tool — which tool to call
arguments — a complete JSON object, copy-pasteable into tools/call
explanation — why each parameter was chosen

Plus 12 power-user tips for combining parameters effectively.

11 Idle timeout and auto-exit

stdio mode

The stdio server has an idle timeout (default: 2 hours). If no MCP messages are received within the window, the server exits cleanly.

{
  "command": "uffs",
  "args": ["mcp", "run", "--idle-timeout", "3600"]
}

Set --idle-timeout 0 to disable.

The timeout uses a sliding window — every MCP request resets the deadline. A busy agent will never trigger it.

HTTP mode

The HTTP gateway runs indefinitely. Use uffs --mcp stop to shut it down.

12 Logging and diagnostics

stdout is the protocol channel — all diagnostic output goes to stderr or a log file.

# Default: INFO to stderr
uffs --mcp run

# Verbose: auto-creates log file
UFFS_LOG=debug uffs --mcp run

# Explicit log file
UFFS_LOG_FILE=/tmp/mcp.log uffs --mcp run

# Both
UFFS_LOG=trace UFFS_LOG_FILE=/tmp/mcp-diag.log uffs --mcp run

Default log file location:

macOS: ~/Library/Application Support/uffs/uffs_mcp.log
Linux: ~/.local/share/uffs/uffs_mcp.log
Windows: %LOCALAPPDATA%\uffs\uffs_mcp.log

13 Relationship to the daemon

The MCP server is not the daemon. They are separate processes:

	Daemon (`uffs-daemon`)	MCP Server (`uffs --mcp`)
Role	Holds MFT index in memory, executes queries	Bridges MCP protocol to daemon
Data	Yes — full file index	No — stateless bridge
Started by	Auto-started by first client	`uffs --mcp start` or AI host
Stopped by	`uffs --daemon stop` or idle timeout	`uffs --mcp stop` or AI host disconnect
Multiple?	One daemon per machine	Many MCP servers (one per AI host session)

When the MCP server connects, it auto-starts the daemon if needed. Stopping the MCP server does not stop the daemon — other clients (CLI, TUI, other MCP sessions) may still be using it.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

MCP Server

How It Works

1 Two transports

2 Quick start

HTTP mode

stdio mode

3 Host configuration

Claude Desktop / Claude Code

Cursor

Windsurf

Augment Code

Standalone binary (alternative)

4 Tools

`uffs_search`

`uffs_aggregate`

`uffs_facet_values`

`uffs_info`

5 Resources

Resource templates

6 Prompts

7 Server management

Commands

Status

Stats

8 HTTP endpoints

Authentication

Health check

9 Agent instructions

10 Cookbook

11 Idle timeout and auto-exit

stdio mode

HTTP mode

12 Logging and diagnostics

13 Relationship to the daemon

Uh oh!

Uh oh!

FilesExpand file tree

mcp.md

Latest commit

History

mcp.md

File metadata and controls

MCP Server

How It Works

1 Two transports

2 Quick start

HTTP mode

stdio mode

3 Host configuration

Claude Desktop / Claude Code

Cursor

Windsurf

Augment Code

Standalone binary (alternative)

4 Tools

uffs_search

uffs_aggregate

uffs_facet_values

uffs_info

5 Resources

Resource templates

6 Prompts

7 Server management

Commands

Status

Stats

8 HTTP endpoints

Authentication

Health check

9 Agent instructions

10 Cookbook

11 Idle timeout and auto-exit

stdio mode

HTTP mode

12 Logging and diagnostics

13 Relationship to the daemon

`uffs_search`

`uffs_aggregate`

`uffs_facet_values`

`uffs_info`