Files

Session-scoped storage with intelligent lifecycle management across three scopes: working, input, and output - each optimized for different stages of your agent's workflow.

Overview

Files is a built-in capability that provides AI agents with unified storage across multiple scopes, each designed for specific use cases. When enabled on your MCP Gateway, agents can manage code and temporary files in working, read user data from input, and write results to output. Files automatically mounts into VMs, enabling your agent's Python or JavaScript code to use standard filesystem paths.

Key Features

• Three Storage Scopes: working (agent workspace), input (user data), output (results)
• Intelligent Permissions: Read-only input, read/write output, full access working
• VM Integration: Direct mounting for code execution with familiar filesystem paths
• Automatic Cleanup: working files deleted after 48 hours of inactivity
• Persistent Storage: input and output files retained until manually deleted

How to Enable

1. Navigate to your MCP Gateway settings
2. Locate Files in the Built-in Capabilities section
3. Toggle the capability ON
4. Save your configuration

Once enabled, any AI agent connected to your gateway can use file storage through the MCP protocol with automatic scope-based permissions.

Storage Scopes

working

• Purpose: Agent's workspace for code, cache, and temporary files
• Permissions: Full read/write access
• Lifetime: 48 hours of inactivity
• VM Mount: /working (read/write)
• Best for: Python/JavaScript code, dependencies, build artifacts, caching, debug logs, intermediate calculations

input

• Purpose: User-provided data for agent to process
• Permissions: Read-only (agent), Write (user via web UI)
• Lifetime: Persistent (until manually deleted)
• VM Mount: /input (read-only)
• Best for: CSV files, JSON data, images, datasets to analyze

output

• Purpose: Agent-generated results for user to download
• Permissions: Read/Write (agent), Read (user via web UI)
• Lifetime: Persistent (until manually deleted)
• VM Mount: /output (read/write)
• Best for: Reports, processed data, visualizations, analysis results

What AI Agents Can Do

Data Processing Workflows

• Read CSV/JSON data from input scope
• Process data using code in working directory
• Write processed results to output scope
• Use working for intermediate transformations
• Organize outputs in directories for user download

Code Execution in VMs

• Write Python scripts to working directory for execution
• Install dependencies in working directory
• Read user data from mounted /input directory inside VM
• Write results to mounted /output directory inside VM
• Let VM mount scopes automatically as filesystem paths

Multi-Step Analysis

• Store parsing results in working between steps
• Cache expensive computations in working directory
• Read multiple input files sequentially
• Generate multiple output files organized by type
• Maintain working state across agent turns (up to 48 hours)

Report Generation

• Read input data and templates
• Build reports piece by piece in working directory
• Write final PDFs/images to output
• Organize outputs in dated directories
• Let users download via web UI

Iterative Development

• Write code to working directory and test in VM
• Read test data from input
• Write test results to output
• Iterate without losing state (48-hour window)

Capability Behavior

Resource Limits

Limit	Value	Applies To
Per-File Size	10 MB	All scopes
Files per Scope	1,000 files	Each scope independently
working Lifetime	48 hours inactive	Automatic cleanup
input Lifetime	Persistent	Until manually deleted
output Lifetime	Persistent	Until manually deleted

Permission Matrix

	working	input	output
Agent/MCP	Read & Write	Read	Read & Write
User	No access	Read & Write	Read

Automatic Features

• Session-based file isolation per scope
• Automatic cleanup of working scope (48 hours)
• Direct VM mounting for code execution
• Scope-based permission enforcement

Performance Characteristics

• Fast read/write operations
• Instant availability after write
• Optimized for small-to-medium files (<10MB)
• VM mounts provide native filesystem performance

Limitations

Not for Large Files

• Individual files limited to 10 MB
• Not suitable for video processing or large datasets
• Consider chunking large files into smaller pieces

Scope-Specific Constraints

• Cannot write to input scope (read-only for agents)
• Cannot delete from input or output (persistent scopes)
• working scope is temporary (48-hour auto-cleanup)
• Agents can read output to verify their writes succeeded

VM Mounting Specifics

• All three scopes are mounted in VMs
• working mounted at /working (read/write)
• input mounted at /input (read-only)
• output mounted at /output (read/write)
• VM sees standard Linux filesystem paths
• No special storage APIs needed in VM code

No Version History

• No automatic versioning of files
• Last write wins for concurrent modifications
• No rollback or recovery features
• Consider manual versioning in filenames if needed

Pricing

Files uses a tiered pricing model based on scope:

Free Scopes

• working: Included, auto-deleted after 48 hours inactive

Paid Scopes

• input: $0.005/GB/day for persistent storage
• output: $0.005/GB/day for persistent storage

Notes

• Only persistent scopes (input/output) incur storage charges
• Temporary scopes (working) are free with automatic cleanup
• Per-operation costs count as single gateway request
• Storage metered daily based on actual usage

Typical Applications

CSV Data Analysis

Agent reads CSV from input, writes Python analysis code to working, executes in VM which reads mounted /input/data.csv and writes /output/summary.json, user downloads results via web UI.

Report Generation Pipeline

User uploads dataset to input, agent processes data using code in working directory, generates PDF report in output/reports/ directory, organizes outputs by date for easy user access.

Multi-Step ETL Workflow

Agent reads JSON from input, stores intermediate transformations in working during processing, writes cleaned data to output, uses working for reusable transformation scripts (48-hour window).

Interactive Code Development

Agent writes Python code to working directory, tests it across multiple turns (working persists 48 hours), reads test data from input, writes test results to output for user review.

Batch Processing with Organization

Agent processes multiple input files sequentially, writes results organized in output directories by type (output/csv/, output/json/, output/reports/), uses working for temporary calculations between files.

Next Steps

Related Capabilities

• Virtual Machine - For code execution with mounted filesystem access
• Code Runner - For simple stateless script execution

Platform Features

• All Capabilities - Explore other built-in tools
• MCP Gateway - Configure your gateway
• Usage & Limits - Understand platform constraints