File Gateway

A file management system providing S3 file operations through a REST API and MCP server for AI agents.

Overview

File Gateway provides:

• File API - FastAPI REST service for S3 file operations (list, upload, download, delete)
• MCP Server - Model Context Protocol server for agent file access; it follows the VersityGW backend — the local PVC in posix mode and the remote bucket in s3 mode — so agents’ MCP writes and the file-api always share one store
• VersityGW - S3-compatible gateway; stores objects on a local PVC (default) or proxies an existing remote S3 bucket
• Persistent Storage - Kubernetes PVC-backed storage (posix backend only)

File Size Limitations

The Filesystem MCP Server is designed for small files that can be directly loaded into agent context. For this reason it enforces a 1MB file size limit for uploads.

For larger files or datasets, consider using RAG (Retrieval-Augmented Generation) or vectorization patterns.

Install

ark install marketplace/services/file-gateway

Or with DevSpace:

cd services/file-gateway
devspace deploy

Or with Helm:

helm install file-gateway services/file-gateway/chart -n default

Access via:

• Port forward: kubectl port-forward svc/file-gateway-file-api 8080:8080
• Ark Dashboard → Files page 

Services

File API

FastAPI REST service for S3 file operations via VersityGW. Provides endpoints for listing, uploading, downloading, and deleting files from S3-compatible storage.

Port: 8080

Filesystem MCP Server

Model Context Protocol server that provides file system access tools for AI agents. Agents can interact with the file storage through MCP tools.

For detailed documentation on available tools and usage, see the Filesystem MCP Server documentation.

Port: 8000

VersityGW

S3-compatible gateway for object storage, providing the underlying storage backend.

Port: 7070

Configuration

Remote S3 backend

By default VersityGW stores objects on a local PVC (backend: posix). To back the gateway with an existing S3 bucket (e.g. real AWS S3), set versitygw.backend=s3. VersityGW then proxies that bucket and no PVC is provisioned. In this mode the filesystem MCP also switches to an S3 storage adapter (STORAGE_BACKEND=s3) pointed at the same VersityGW endpoint, so files an agent writes through the MCP and files served by the file-api share one bucket. The MCP exposes the same tool set (write_file, read_text_file, list_directory, …) in both modes, so agents need no changes.

Create the credentials secret:

kubectl create secret generic my-s3-creds \
  --from-literal=AWS_ACCESS_KEY_ID=... \
  --from-literal=AWS_SECRET_ACCESS_KEY=...
  # optional, for temporary / STS credentials:
  # --from-literal=AWS_SESSION_TOKEN=...

The secret’s keys are injected as AWS_* environment variables and consumed via the AWS default credential chain — include AWS_SESSION_TOKEN when using temporary STS credentials. (VersityGW’s explicit VGW_S3_ACCESS_KEY/VGW_S3_SECRET_KEY flags can’t carry a session token, so the chain is used instead.) Alternatively omit the secret entirely and use IRSA / pod identity (see below).

Install:

Released chart (OCI):

helm install file-gateway oci://ghcr.io/mckinsey/agents-at-scale-marketplace/charts/file-gateway \
  -n default --create-namespace \
  --set versitygw.backend=s3 \
  --set versitygw.s3Backend.region=us-east-1 \
  --set versitygw.s3Backend.credentialsSecret=my-s3-creds \
  --set fileApi.config.bucketName=my-existing-bucket

(From a checkout, replace the chart reference with services/file-gateway/chart.)

The PVC is skipped automatically in s3 mode, so storage.enabled does not need to be set. The filesystem MCP stays enabled and writes to the same bucket; by default it writes at the bucket root (shared with the file-api). Set filesystemMcp.config.keyPrefix=agents/ to scope MCP writes under a prefix.

Constraints (enforced at install time):

• The bucket must already exist. The chart does not create it; the default aas-files will not exist in a real account, so set fileApi.config.bucketName to a bucket you own.
• Credentials are required. Set credentialsSecret, or set versitygw.s3Backend.allowDefaultCredentialChain=true to use IRSA / pod identity. For IRSA you must also annotate the gateway service account via versitygw.serviceAccount.annotations (e.g. eks.amazonaws.com/role-arn), otherwise the pod has no role to assume.
• Leave versitygw.s3Backend.endpoint empty for AWS. For S3-compatible providers (MinIO, Ceph RGW, etc.) set the endpoint and usually versitygw.s3Backend.usePathStyle=true, since VersityGW defaults to virtual-host addressing which those services don’t support.

Usage with Agents

Agents can access files through the Filesystem MCP Server. The MCP server is automatically registered with Ark and provides file operation tools to connected agents.

See the Filesystem MCP Server documentation for details on:

• Available filesystem tools
• Creating agents with filesystem access
• Configuring workspaces
• Example queries and operations

Use the ark-dashboard to browse and manage files.

Uninstall

Using Ark CLI:

ark uninstall marketplace/services/file-gateway

Using Helm:

helm uninstall file-gateway -n default

Using DevSpace:

cd services/file-gateway
devspace purge