Virtual Fs

What virtual-fs does

The virtual-fs MCP server presents a file-oriented interface backed by PostgreSQL. Agent operations are stored in the database rather than on the machine running the MCP process, so files remain available after process restarts, container recycling, and redeployments. The server is suitable for agent scratch work, persistent notes, build outputs, logs, reports, and other data that benefits from a filesystem-shaped API.

Each connection gets a session namespace by default. This keeps one agent session's files separate from another session's files without requiring a session argument in every tool call. Named stores provide an alternative namespace for information that should be shared between sessions or kept as longer-term memory.

How it works

The virtual-fs MCP server uses PostgreSQL as its storage backend and requires PostgreSQL 14 or newer with the pg_trgm extension. Node.js 20 or later is also required. The server can initialize its tables on startup when VFS_AUTO_INIT=true; otherwise, the schema can be applied manually with the supplied SQL file.

Session identity depends on the transport and configuration. Stdio connections receive a generated UUID for each process, while HTTP/SSE connections use the transport-provided MCP session ID. Setting VFS_SESSION_ID provides a deterministic or resumable identity, but transport session identity has priority. Passing a store parameter switches an operation from the current session namespace to a named persistent store. Stores are created when first used, and the stores tool lists their names.

Optional PostgreSQL Row Level Security can add database-enforced isolation for multi-tenant deployments. RLS requires applying the provided RLS SQL and configuring the server with an appropriate database role.

Setup and configuration

Provide DATABASE_URL in the MCP client's environment. A typical configuration runs the package with npx, points it at PostgreSQL, and sets VFS_AUTO_INIT=true for first-run table creation. Manual schema management is also supported with psql $DATABASE_URL -f sql/schema.sql.

Available environment variables include:

• DATABASE_URL: PostgreSQL connection string; required.
• VFS_AUTO_INIT: creates tables at startup when enabled; defaults to false.
• VFS_SESSION_ID: optional deterministic session identifier.
• VFS_ENABLE_RLS: enables Row Level Security when set up in the database; defaults to false.
• VFS_STORAGE_BACKEND: selects the storage backend and defaults to postgres.

Tools and capabilities

The virtual-fs MCP server exposes these tools:

• read returns file content and size.
• write creates or replaces a file and creates missing parent directories.
• append adds content to a file or creates it when absent.
• stat reports whether a path exists and returns available metadata.
• ls lists directory entries, placing directories first and sorting alphabetically.
• mkdir creates a directory and any missing parents.
• rm removes a file or recursively removes a directory.
• mv moves or renames a file or directory.
• glob finds paths using patterns such as **/*.ts or brace extensions.
• grep searches file contents with a regular expression and can accept a path filter.
• stores lists persistent store names.

All tools except stores accept the optional store parameter. Responses use structured JSON, which lets an agent inspect results such as file sizes, match counts, directory entries, and deletion status.