Filesystem MCP Server

⚠️ Deprecated. This standalone MCP server is deprecated and will be combined into the File Gateway service. File Gateway bundles this MCP alongside the REST file-api and VersityGW and supports both the filesystem (PVC) and s3 storage backends. Use File Gateway for new deployments; this standalone chart will be removed in a future release.

The Filesystem MCP Server is an MCP-compliant server that provides secure filesystem operations. It enables agents to read, write, edit, search, and manage files within controlled workspaces.

Available Tools

The MCP server exposes the following tools (prefixed with mcp-filesystem-):

• mcp-filesystem-read-file - Read file contents
• mcp-filesystem-write-file - Write or overwrite files
• mcp-filesystem-edit-file - Edit existing files
• mcp-filesystem-create-directory - Create directories
• mcp-filesystem-list-directory - List directory contents
• mcp-filesystem-move - Move or rename files/directories
• mcp-filesystem-search - Search for files and content
• mcp-filesystem-get-file-info - Get file metadata
• mcp-filesystem-list-allowed-directories - List accessible directories
• mcp-filesystem-directory-tree - Get directory tree structure
• mcp-filesystem-set-base-directory - Configure workspace directory

Quick Start

Installation

Using Ark CLI (Recommended):

ark install marketplace/mcps/filesystem-mcp-server

Using DevSpace (for Development):

cd mcps/filesystem-mcp-server
devspace deploy

Using Helm:

cd mcps/filesystem-mcp-server
helm install mcp-filesystem ./chart -n default

Creating an Agent with Filesystem Access

Create an agent that uses the filesystem MCP server:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: filesystem-agent
  namespace: default
spec:
  tools:
    - name: mcp-filesystem-read-file
      type: custom
    - name: mcp-filesystem-write-file
      type: custom
    - name: mcp-filesystem-edit-file
      type: custom
    - name: mcp-filesystem-create-directory
      type: custom
    - name: mcp-filesystem-list-directory
      type: custom

Configuring Workspaces

Workspaces are configured via Ark query annotations using the set_base_directory tool:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: my-query
  annotations:
    "ark.mckinsey.com/mcp-server-settings": |
      {"default/mcp-filesystem": {
        "toolCalls": [{
          "name": "set_base_directory",
          "arguments": {"path": "my-workspace"}
        }]
      }}
spec:
  input: "List all files in the current directory"
  targets:
    - name: filesystem-agent

This creates and configures /data/my-workspace/ as the working directory for all filesystem operations in that query.

Examples

Basic File Operations

# Create and write to a file
ark query agent/filesystem-agent "Create a file hello.txt with content 'Hello World'"
 
# Read a file
ark query agent/filesystem-agent "Read the contents of hello.txt"
 
# List files
ark query agent/filesystem-agent "List all files in the current directory"

Directory Operations

# Create a directory structure
ark query agent/filesystem-agent "Create a directory structure: project/src and project/tests"
 
# Get directory tree
ark query agent/filesystem-agent "Show me the directory tree of the project folder"

Search Operations

# Search for files
ark query agent/filesystem-agent "Find all .txt files"
 
# Search file contents
ark query agent/filesystem-agent "Search for files containing 'TODO'"

Configuration

Environment Variables

Configured in chart/values.yaml:

Storage backends

The server picks a storage adapter at startup via STORAGE_BACKEND. Both adapters expose the identical tool set, so agents work unchanged regardless of backend.

• filesystem (default) — reads/writes the local filesystem under BASE_DATA_DIR, backed by the PVC.
• s3 — reads/writes an S3 bucket via the AWS SDK, addressing objects by key (“directories” are key prefixes). This is what File Gateway uses when VersityGW runs its s3 backend, so the MCP and the file-api share one bucket. Extra variables in this mode:

Helm Chart Options

# Storage configuration
persistence:
  size: 10Gi
  storageClass: standard
 
# Resource limits
resources:
  limits:
    cpu: 1000m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

Architecture

The server has a clean separation of concerns:

Session Wrapper (src/index.ts)

• MCP protocol session lifecycle (ID generation, tracking)
• Session metadata persistence (sessions.json)
• LRU eviction and cleanup
• Transport management
• Generic and reusable across MCP servers

Filesystem Adapter (src/adapters/filesystem/)

• File operations (read, write, edit, search, list, tree) against the local PVC
• Path validation and security
• Workspace management via set_base_directory

S3 Adapter (src/adapters/s3/)

• The same MCP tools backed by an S3 bucket via @aws-sdk/client-s3 (objects addressed by key; “directories” are key prefixes)
• Selected when STORAGE_BACKEND=s3; talks to any S3-compatible endpoint (AWS_ENDPOINT_URL), including the in-cluster VersityGW

Shared Tool Schemas (src/adapters/shared/)

• Both adapters import their tool names and input schemas from one module, guaranteeing the two backends expose an identical tool surface (so Ark generates the same tool names either way)

Key Design Principles

• MCP sessions ≠ application state: Sessions track connections, not configuration
• Annotations as source of truth: Workspace configuration comes from Ark annotations
• Single base directory: All sessions share /data/ with user-specified subdirectories
• No per-session directories: Workspaces are explicitly named and persistent

Security Considerations

• All filesystem operations are restricted to the configured base directory (/data/)
• Path traversal attacks are prevented through path validation
• Each workspace is isolated within its subdirectory
• Session limits prevent resource exhaustion
• Persistent storage should be properly secured with appropriate access controls

Uninstallation

Using Ark CLI:

ark uninstall marketplace/mcps/filesystem-mcp-server

Using DevSpace:

cd mcps/filesystem-mcp-server
devspace purge

Using Helm:

helm uninstall mcp-filesystem -n default