---
title: "File transfer tools"
description: "MCP tools for transferring files and folders between your machine and servers over secure WebFTP sessions. Covers single and bulk uploads, downloads, transfer history, and status polling."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# File transfer tools

These tools move files and folders between your machine and a server over a secure WebFTP transfer, and let an agent review or check on transfers in progress. They back requests like "upload this config to web-01" or "download `/var/log/app` from db-02 as a zip."

Some tools only work when the MCP server is running locally (stdio mode), because they read from or write to your local filesystem directly: `webftp_upload_file`, `webftp_bulk_upload`, and `webftp_bulk_download`. `webftp_upload_content` and `webftp_download_file` work in both local and remote (streamable-http) mode—`webftp_upload_content` sends file bytes directly instead of a local path, and `webftp_download_file` returns a temporary download link (valid for 24 hours) when running remotely instead of saving to disk.

File transfers are subject to [file ACLs](/reference/mcp/tools/security/), and every transfer is recorded in the [WebFTP audit log](/reference/mcp/tools/audit/). When the caller authenticates through MCP OAuth or a browser session, the server also requires an active [Work Session](/reference/mcp/tools/work-sessions/) that includes the `webftp` scope; static API tokens and service tokens bypass this requirement. Pass `work_session_id` to link a transfer to a specific session, or set the `ALPACON_WORK_SESSION` environment variable to supply a default when the argument is omitted.

  All tools accept `workspace` (required) and `region` (optional, defaults to the configured region). These common parameters are omitted from the tables below.

## Summary

| Tool | Description | Access |
|------|-------------|--------|
| `webftp_session_create` | Session creation is refused through MCP (`403`) | Unavailable |
| `webftp_sessions_list` | List active and past WebFTP sessions | Read-only |
| `webftp_upload_file` | Upload a local file to a server | Additive |
| `webftp_upload_content` | Upload file content (base64) to a server | Additive |
| `webftp_download_file` | Download a file or folder from a server | Additive |
| `webftp_uploads_list` | List upload history | Read-only |
| `webftp_downloads_list` | List download history | Read-only |
| `webftp_bulk_upload` | Upload multiple local files at once | Additive |
| `webftp_bulk_download` | Download multiple files/folders as one zip | Additive |
| `webftp_check_status` | Check the status of an upload or download | Read-only |

## Sessions

### webftp_session_create

This tool remains exposed, but Alpacon refuses WebFTP session creation through MCP with `403`. To transfer files, call an upload or download tool directly. File transfers work without opening a WebFTP session first.

**Access**: Unavailable through MCP

#### Example

> "Upload this script to /opt/scripts/deploy.sh on db-02"

The agent calls `webftp_upload_content` with the script's base64 content, `remote_file_path="/opt/scripts/deploy.sh"`, and `server_id` set to db-02's UUID.

### webftp_sessions_list

Lists active and past WebFTP sessions in a workspace. Filter by `server_id` to see sessions for a single server.

**Access**: Read-only

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | No | Filter results to sessions on this server |

#### Example

> "What WebFTP sessions are currently open on web-01?"

The agent calls `webftp_sessions_list` with `server_id` set to web-01's UUID.

## Uploads

### webftp_upload_file

Uploads a local file to a server. Reads the file from a local absolute path and places it at the given remote absolute path. Both paths must be absolute. Local-mode only—see the note above.

**Access**: Additive

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | Yes | Target server ID |
| `local_file_path` | string | Yes | Absolute path to the local file |
| `remote_file_path` | string | Yes | Absolute destination path on the server |
| `username` | string | No | System user to upload as |
| `allow_overwrite` | boolean | No | Overwrite an existing file at the destination (default: `true`) |
| `work_session_id` | string | No | Work Session to link this upload to, for audit. Falls back to `ALPACON_WORK_SESSION` if omitted |

#### Example

> "Upload /Users/me/nginx.conf to /etc/nginx/nginx.conf on web-01"

The agent calls `webftp_upload_file` with the local and remote paths and `server_id` set to web-01's UUID.

### webftp_upload_content

Uploads file content to a server from base64-encoded bytes instead of a local file path. Use this when you already have the content in hand—for example, a Claude Desktop file attachment, or a file Claude Code read with its Read tool. Works in both local and remote mode.

**Access**: Additive

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | Yes | Target server ID |
| `file_content` | string | Yes | Base64-encoded file content |
| `remote_file_path` | string | Yes | Absolute destination path on the server |
| `file_name` | string | No | File name to record (default: derived from `remote_file_path`) |
| `username` | string | No | System user to upload as |
| `allow_overwrite` | boolean | No | Overwrite an existing file at the destination (default: `true`) |
| `work_session_id` | string | No | Work Session to link this upload to, for audit. Falls back to `ALPACON_WORK_SESSION` if omitted |

#### Example

> "Here's a script I just wrote—put it at /opt/scripts/deploy.sh on api-01"

The agent base64-encodes the script content and calls `webftp_upload_content` with `remote_file_path="/opt/scripts/deploy.sh"`.

### webftp_bulk_upload

Uploads multiple local files to a server in a single operation, all placed in the same remote directory. Local-mode only—see the note above.

**Access**: Additive

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | Yes | Target server ID |
| `local_file_paths` | array | Yes | Absolute paths to the local files |
| `remote_directory` | string | Yes | Absolute destination directory on the server |
| `username` | string | No | System user to upload as |
| `allow_overwrite` | boolean | No | Overwrite existing files at the destination (default: `true`) |
| `work_session_id` | string | No | Work Session to link this upload to, for audit. Falls back to `ALPACON_WORK_SESSION` if omitted |

#### Example

> "Upload these three config files to /etc/app/conf.d on web-01"

The agent calls `webftp_bulk_upload` with `local_file_paths` set to the three local paths and `remote_directory="/etc/app/conf.d"`.

## Downloads

### webftp_download_file

Downloads a file or folder from a server. In local mode, the file is saved to `local_file_path`. In remote mode, the tool waits until the file is ready and returns a temporary download link valid for 24 hours instead of saving to disk. Folders are packaged as a zip archive—set `resource_type="folder"` for directories.

**Access**: Additive

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | Yes | Target server ID |
| `remote_file_path` | string | Yes | Absolute path to the file or folder on the server |
| `local_file_path` | string | Required in local mode | Absolute destination path on your machine. Not used in remote mode |
| `resource_type` | string | No | `file` or `folder` (default: `file`) |
| `username` | string | No | System user to download as |
| `work_session_id` | string | No | Work Session to link this download to, for audit. Falls back to `ALPACON_WORK_SESSION` if omitted |

#### Example

> "Download /var/log/app.log from db-02 to my Downloads folder"

The agent calls `webftp_download_file` with `remote_file_path="/var/log/app.log"` and `local_file_path` set to the destination on your machine.

> "Grab the /var/log/app folder from db-02 as a zip"

The agent sets `resource_type="folder"` so the folder is packaged as a zip before transfer.

### webftp_bulk_download

Downloads multiple files or folders from a server as a single zip archive. All paths in `remote_paths` must share the same parent directory. Local-mode only—see the note above. If the archive isn't ready yet, poll with `webftp_check_status` and retry.

**Access**: Additive

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | Yes | Target server ID |
| `remote_paths` | array | Yes | Absolute paths to the files/folders, all under the same parent directory |
| `local_file_path` | string | Yes | Absolute destination path for the zip archive on your machine |
| `username` | string | No | System user to download as |
| `work_session_id` | string | No | Work Session to link this download to, for audit. Falls back to `ALPACON_WORK_SESSION` if omitted |

#### Example

> "Download /var/log/app/access.log and /var/log/app/error.log from web-01 as one zip"

The agent calls `webftp_bulk_download` with `remote_paths` set to both log file paths and `local_file_path` set to the destination zip on your machine.

## Transfer history

### webftp_uploads_list

Lists upload history—filenames, sizes, timestamps, and transfer status. Filter by `server_id`.

**Access**: Read-only

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | No | Filter results to uploads to this server |

#### Example

> "What have I uploaded to web-01 recently?"

The agent calls `webftp_uploads_list` with `server_id` set to web-01's UUID.

### webftp_downloads_list

Lists download history—filenames, sizes, timestamps, and transfer status. Filter by `server_id`.

**Access**: Read-only

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server_id` | string | No | Filter results to downloads from this server |

#### Example

> "Show me my download history for db-02"

The agent calls `webftp_downloads_list` with `server_id` set to db-02's UUID.

### webftp_check_status

Checks the transfer status of a WebFTP upload or download operation—still in progress, succeeded, or failed. Use this to poll after `webftp_bulk_download` or another async transfer.

**Access**: Read-only

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_id` | string | Yes | ID of the upload or download to check |
| `transfer_type` | string | Yes | `upload` or `download` |

#### Example

> "Is my bulk download for db-02 done yet?"

The agent calls `webftp_check_status` with the `file_id` returned by the earlier `webftp_bulk_download` call and `transfer_type="download"`.

## Related

- [Command execution tools](/reference/mcp/tools/execution/): run commands on the same servers you transfer files to
- [Access control & approvals](/reference/mcp/tools/security/): manage the file ACL rules that gate uploads and downloads
- [Audit logs](/reference/mcp/tools/audit/): review the WebFTP transfer log for every upload and download

Source: https://docs.alpacax.com/reference/mcp/tools/files/
