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, and every transfer is recorded in the WebFTP audit log. When the caller authenticates through MCP OAuth or a browser session, the server also requires an active Work Session 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 | Create a WebFTP session on a server | Additive |
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
Creates a new WebFTP session on a server and returns its session ID and connection details. This is for advanced session management—for a simple file transfer, call webftp_upload_file or webftp_download_file directly, which handle sessions for you.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Target server ID |
username | string | No | System user for the session |
work_session_id | string | No | Work Session to link this session to, for audit. Falls back to ALPACON_WORK_SESSION if omitted |
Example
“Open a WebFTP session on db-02 as the deploy user”
The agent calls webftp_session_create with server_id set to db-02’s UUID and username="deploy", returning the new session’s ID.
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: run commands on the same servers you transfer files to
- Access control & approvals: manage the file ACL rules that gate uploads and downloads
- Audit logs: review the WebFTP transfer log for every upload and download