MCP Server

Name: AeroFTP
Author: axpdev-lab

The AeroFTP MCP (Model Context Protocol) server exposes 39 curated file management tools to AI assistants via JSON-RPC over stdio. It connects Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client to AeroFTP's full integration surface - 7 transport protocols + 20+ native provider integrations + 40+ pre-configured presets - without custom integration code.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants call external tools through a structured JSON-RPC interface. Instead of generating shell commands, the AI calls typed tools with validated parameters and receives structured responses.

AeroFTP implements an MCP server that wraps its CLI into 39 curated tools with connection pooling (auto-reset on stale handles), per-profile request serialization, schema validation, request cancellation, rate limiting, and audit logging.

The official VS Code extension axpdev-lab.aeroftp-mcp configures this server in one click for Claude Code, Claude Desktop, Cursor, and Windsurf simultaneously.

Quick Start

1. Install AeroFTP

The MCP server is included with every AeroFTP installation. See CLI Installation for platform-specific instructions.

bash

# Verify the CLI is available
aeroftp-cli --version

2. Configure Your AI Tool

VS Code Extension (Recommended)

Install the AeroFTP MCP Server extension from the VS Code Marketplace. It auto-detects installed AI tools and configures the MCP server with one click.

Ctrl+Shift+P → AeroFTP: Install MCP Server

The extension supports Claude Code, Claude Desktop, Cursor, and Windsurf simultaneously.

Manual Configuration

Add the following entry to your AI tool's MCP configuration file:

json

{
  "mcpServers": {
    "aeroftp": {
      "command": "aeroftp-cli",
      "args": ["mcp"]
    }
  }
}

Configuration file locations:

Tool	Config Path
Claude Code	`~/.claude/.mcp.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`

3. Connect to a Server

Once configured, your AI assistant can use list_profiles to see your saved servers and connect to start a session.

Available Tools

The MCP server exposes the following curated tools (names use the aeroftp_ prefix in the wire protocol; the table omits the prefix for brevity).

Safe Tools (Read-Only)

Tool	Description
`list_servers`	List saved server profiles from the encrypted vault (names + protocol + tags + per-profile `auth_state` - never credentials). Supports a `filter` arg
`mcp_info`	Diagnostics about the running MCP process: version, supported protocols, capabilities
`agent_connect`	Single-shot connect surface (added v3.6.6): one JSON envelope with `connect` + `capabilities` + `quota` + `path` blocks, replacing the boilerplate sequence `connect → about → df → ls /`
`list_files`	List files and directories at a given path. Pagination, sort, files-only / dirs-only filters
`read_file`	Read text file content. `preview_kb` argument for soft-truncation (added v3.5.9)
`file_info`	File or directory metadata (size, mtime, permissions, hash)
`search_files`	Search files by name pattern (glob), with pagination and sort
`storage_quota`	Storage quota (used/free/total)
`hashsum`	Streamed SHA-256 / SHA-1 / MD5 / BLAKE3 of a remote file (alias: `checksum`, added v3.5.9)
`head` / `tail`	First or last N lines of a remote UTF-8 text file, default 50, cap 10000 (added v3.5.9)
`tree`	Recursive directory tree, depth-capped (added v3.5.9)
`check_tree`	Categorized local-vs-remote diff. `compare_method` argument supports `size` / `mtime` / `checksum` (added v3.6.0). Per-group caps `max_match` / `max_differ` / `max_missing_local` / `max_missing_remote` and `omit_match` switch (added v3.7.0)
`sync_doctor`	Preflight risk summary with `suggested_next_command`. Lighter than `sync_tree dry_run=true` (added v3.7.0)
`reconcile`	Categorized size-only diff variant of `check_tree` with `elapsed_secs` and `suggested_next_command` (added v3.7.0)
`dedupe`	SHA-256 duplicate detection grouped per size, modes `newest` / `oldest` / `largest` / `smallest` / `list`, dry-run by default (added v3.7.0)
`debug_snapshot`	Static diagnostic snapshot: host / runtime info plus the last N redacted `aeroftp.log` lines
`debug_run_test`	Run one self-contained diagnostic probe (e.g. `known_hosts`) and return its result

Medium Tools (Write Operations)

Tool	Description
`download_file`	Download a remote file to a local path
`upload_file`	Upload a local file. Supports `create_parents` for missing-directory auto-creation, `no_clobber` for skip-if-exists (added v3.5.9)
`upload_many`	Batch upload from a `files: []` array (mirrors CLI `--files-from`). Returns per-file `status` (uploaded / skipped / error). Added v3.5.10
`create_directory`	Create a remote directory
`rename`	Rename or move a file or directory
`edit`	Find and replace in a remote text file without downloading it locally (added v3.5.10)
`sync_tree`	Plan and execute a directory sync. Returns `plan[]` (per-file decision) and `plan_by_op` with caps; supports `dry_run` and pool-invalidate fix on apply
`transfer` / `transfer_tree`	Cross-profile copy: single file or recursive directory between two saved profiles. Source and destination provider opened once and reused for the whole batch (added v3.7.0)
`touch`	Create an empty file at a remote path, or report `action: "exists"` (added v3.7.0)
`speed`	Throughput probe: random payload upload + download + SHA-256 integrity + cleanup. Caps 4 MiB default / 64 MiB max, iterations 1..3 (added v3.7.0)
`benchmark`	Run the AeroFTP community benchmark suite against a saved profile and return the schema-v1 JSON report
`close_connection`	Close the current pooled connection (forces reconnect on next call)

High Tools (Destructive)

Tool	Description
`delete`	Permanently delete one or more remote entries (supports `recursive`)
`delete_many`	Batch delete from an explicit list. Per-item `status` reporting
`cleanup`	BFS scan for orphan `.aerotmp` partial-transfer files. Dry-run by default; deletes only when explicitly asked. Caps 100 k entries / depth 100 (added v3.7.0)
`server_exec`	Execute a vault-backed server operation without exposing credentials to the model

Rate Limits

The MCP server enforces per-category rate limits to prevent runaway operations:

Category	Limit	Tools
Read	60/min	list_servers, list_files, read_file, file_info, search_files, storage_quota, hashsum, head, tail, tree, check_tree, reconcile, sync_doctor, dedupe, mcp_info, agent_connect
Write	30/min	upload_file, upload_many, download_file, create_directory, rename, edit, sync_tree, transfer, transfer_tree, touch, speed, benchmark
Delete	10/min	delete, delete_many

When a rate limit is exceeded, the server returns an error with a retry_after hint.

Supported Integrations

The MCP server inherits AeroFTP's full integration surface from the CLI. See Protocol Overview for the complete matrix.

Tier	Coverage
7 transport protocols	FTP, FTPS, SFTP, WebDAV, S3, Azure Blob, OpenStack Swift
20+ native provider integrations	Google Drive, Dropbox, OneDrive, MEGA, Box, pCloud, Filen, Zoho WorkDrive, Internxt, kDrive, Koofr, Jottacloud, FileLu, Yandex Disk, OpenDrive, 4shared, Drime Cloud, GitHub, GitLab, Immich
40+ pre-configured presets	AWS S3, Backblaze B2, Cloudflare R2, Wasabi, DigitalOcean Spaces, MinIO, Storj, IDrive e2, Hetzner Storage Box, Yandex Object Storage, Tencent COS, Alibaba OSS, Oracle Cloud, Nextcloud, Seafile, InfiniCLOUD, Jianguoyun, CloudMe, SourceForge, etc.

Saved profiles for OAuth providers (Google Drive, Dropbox, OneDrive, Box, pCloud, Zoho WorkDrive, Yandex Disk, 4shared, Drime) are loaded from the encrypted vault automatically once authorized in the AeroFTP GUI - the MCP server never sees the underlying tokens.

Security Model

Credential Isolation

The MCP server never exposes credentials to the AI model. Server profiles are stored in AeroFTP's encrypted vault (AES-256-GCM + Argon2id) and resolved by name at connection time.

Audit Logging

Every tool call is logged with timestamp, tool name, parameters, and result status. Logs are stored locally and never transmitted.

Input Validation

All path parameters are validated against traversal attacks (.., absolute paths, null bytes). File sizes are capped to prevent memory exhaustion.

Agent Discovery

Use agent-info to query the MCP server's capabilities programmatically:

bash

aeroftp-cli agent-info --json 2>/dev/null

Returns a JSON object with:

Available tools with parameter schemas
Supported protocols
Exit code definitions
Safety rules and rate limits
Saved server profiles (names only)

Troubleshooting

MCP server not responding

Verify the CLI is accessible:

bash

aeroftp-cli --version

If using Snap, ensure the alias is active:

bash

snap alias aeroftp aeroftp-cli

Connection refused

The MCP server requires a saved server profile. Create one in the AeroFTP desktop app or via the CLI:

bash

aeroftp-cli connect sftp://user@host --save "My Server"

Rate limit errors

Reduce the frequency of tool calls or wait for the retry_after period. Rate limits reset every 60 seconds.

Recent Hardening (v3.5.4)

Three independent audits surfaced 9 issues across pool, vault, serialization, and shutdown semantics. All resolved:

S3 bucket fix from vault profiles: create_provider_from_vault now reads bucket/region/endpoint/path_style from the saved profile options. Previously surfaced as "bucket required" on 10+ S3-backed profiles.
Vault auto-init: McpServer::run() initializes the Universal Vault automatically; falls back to AEROFTP_MASTER_PASSWORD when set. Subprocess MCP now sees credentials without manual unlock.
Per-profile serialization: Arc<Mutex<HashMap<String, Arc<Mutex<()>>>>> linearizes tool calls on the same profile while keeping cross-server calls parallel. Prevents wire interleaving on flaky servers.
Shutdown drain: JoinSet tracks spawned tasks; on EOF stdin, drain_pending(10s) lets in-flight responses complete before exit.
Schema validation: inputSchema.required checked before dispatch. Missing fields return MCP-standard -32602 Invalid params instead of generic errors.
Top-level mcp subcommand: aeroftp-cli mcp argv now matches what the VS Code extension registers, removing the need for nested subcommand routing.

MCP Server ​

What is MCP? ​

Quick Start ​

1. Install AeroFTP ​

2. Configure Your AI Tool ​

VS Code Extension (Recommended) ​

Manual Configuration ​

3. Connect to a Server ​

Available Tools ​

Safe Tools (Read-Only) ​

Medium Tools (Write Operations) ​

High Tools (Destructive) ​

Rate Limits ​

Supported Integrations ​

Security Model ​

Credential Isolation ​

Audit Logging ​

Input Validation ​

Agent Discovery ​

Troubleshooting ​

MCP server not responding ​

Connection refused ​

Rate limit errors ​

Recent Hardening (v3.5.4) ​

Further Reading ​

MCP Server

What is MCP?

Quick Start

1. Install AeroFTP

2. Configure Your AI Tool

VS Code Extension (Recommended)

Manual Configuration

3. Connect to a Server

Available Tools

Safe Tools (Read-Only)

Medium Tools (Write Operations)

High Tools (Destructive)

Rate Limits

Supported Integrations

Security Model

Credential Isolation

Audit Logging

Input Validation

Agent Discovery

Troubleshooting

MCP server not responding

Connection refused

Rate limit errors

Recent Hardening (v3.5.4)

Further Reading