Virtual Filesystem

What is Virtual Filesystem?

Virtual Filesystem is an MCP server that provides AI agents with a persistent, PostgreSQL-backed virtual filesystem. It supports session-isolated file operations, cross-session shared stores, glob/grep search, and optional Row Level Security, all exposed as standard Model Context Protocol tools. It is designed for use with any MCP client such as Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and others.

How to use Virtual Filesystem?

Set up a PostgreSQL database (version 14 or later) and configure your MCP client to run npx -y mcp-virtual-fs with the DATABASE_URL environment variable and VFS_AUTO_INIT=true for automatic table creation. Then interact with the 11 POSIX-style tools (e.g., write, read, ls, glob, grep) which return structured JSON responses.

Key features of Virtual Filesystem

• Persistent file storage in PostgreSQL, surviving process restarts and container recycling
• Automatic session isolation with per-connection namespaces
• Cross-session named stores for sharing data between agents
• 11 POSIX-style tools: read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores
• Glob and grep search using PostgreSQL trigram indexes
• Optional Row Level Security for multi-tenant database-enforced isolation
• Zero configuration with auto-created tables on first run

Use cases of Virtual Filesystem

• Agent scratchpad: persistent workspace for LLM agents to read/write files across tool calls
• Long-term agent memory: store notes and context across sessions using named stores
• Multi-agent collaboration: multiple agents share files through cross-session stores
• Sandboxed file operations: agents interact with a virtual filesystem instead of the host OS
• CI/CD artifact storage: persist build outputs, logs, and reports in a queryable filesystem

FAQ from Virtual Filesystem

What are the prerequisites to run Virtual Filesystem?

Node.js 20 or later and PostgreSQL 14 or later (with the pg_trgm extension, included in most distributions). Docker is required for integration tests.

How does session management work?

Sessions are handled automatically. For stdio transport each process gets an auto-generated UUID; for HTTP/SSE the transport provides a sessionId. You can also set a deterministic VFS_SESSION_ID environment variable for resumable sessions. Priority is transport sessionId > VFS_SESSION_ID > auto-generated UUID.

How do cross-session stores work?

Named stores persist across sessions. Any session can read/write to a store by passing the store parameter to tools (e.g., write({ path: "/context.md", content: "notes", store: "agent-memory" })). Without store, operations target the session’s own namespace. Stores are auto-created on first use and are never affected by ephemeral session cleanup.

What transports and authentication are supported?

The server supports stdio, HTTP/SSE, and any transport that provides a sessionId. Authentication is handled via the DATABASE_URL connection string (e.g., PostgreSQL user/password). Row Level Security can be enabled for additional database-enforced isolation, requiring the server to connect as the vfs_app role.

How can I clean up old sessions?

Ephemeral sessions can be deleted with SQL: DELETE FROM vfs_sessions WHERE is_persistent = false AND created_at < now() - interval '7 days';. The ON DELETE CASCADE on vfs_nodes automatically handles file cleanup. Persistent stores are never affected.