파일 전송 도구
이 도구들은 안전한 WebFTP 전송을 통해 내 컴퓨터와 서버 간에 파일·폴더를 옮기고, 진행 중인 전송을 에이전트가 조회하거나 확인할 수 있게 합니다. “이 설정 파일을 web-01에 업로드해줘”나 “db-02의 /var/log/app을 zip으로 다운로드해줘” 같은 요청을 처리합니다.
일부 도구는 MCP 서버가 로컬(stdio 모드)로 실행 중일 때만 동작합니다. 로컬 파일 시스템을 직접 읽거나 쓰기 때문입니다: webftp_upload_file, webftp_bulk_upload, webftp_bulk_download가 여기에 해당합니다. webftp_upload_content와 webftp_download_file은 로컬 모드와 원격(streamable-http) 모드 모두에서 동작합니다. webftp_upload_content는 로컬 경로 대신 파일 바이트를 직접 전송하고, webftp_download_file은 원격 모드에서 실행 중이면 디스크에 저장하는 대신 임시 다운로드 링크(24시간 유효)를 반환합니다.
파일 전송은 파일 ACL의 적용을 받으며, 모든 전송은 WebFTP 감사 로그에 기록됩니다. 호출자가 MCP OAuth나 브라우저 세션으로 인증하는 경우, 서버는 webftp 범위를 포함한 활성 작업 세션도 요구합니다. 정적 API 토큰과 서비스 토큰은 이 요구 사항을 우회합니다. 전송을 특정 세션에 연결하려면 work_session_id를 전달하거나, 인자를 생략했을 때 사용할 기본값으로 ALPACON_WORK_SESSION 환경 변수를 설정하세요.
모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 이 공통 파라미터는 아래 표에서 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
webftp_session_create | 서버에 WebFTP 세션 생성 | 추가적 |
webftp_sessions_list | 활성·과거 WebFTP 세션 조회 | 읽기 전용 |
webftp_upload_file | 로컬 파일을 서버에 업로드 | 추가적 |
webftp_upload_content | 파일 콘텐츠(base64)를 서버에 업로드 | 추가적 |
webftp_download_file | 서버에서 파일 또는 폴더 다운로드 | 추가적 |
webftp_uploads_list | 업로드 이력 조회 | 읽기 전용 |
webftp_downloads_list | 다운로드 이력 조회 | 읽기 전용 |
webftp_bulk_upload | 여러 로컬 파일을 한 번에 업로드 | 추가적 |
webftp_bulk_download | 여러 파일·폴더를 하나의 zip으로 다운로드 | 추가적 |
webftp_check_status | 업로드 또는 다운로드 상태 확인 | 읽기 전용 |
세션
webftp_session_create
서버에 새 WebFTP 세션을 생성하고 세션 ID와 연결 정보를 반환합니다. 고급 세션 관리를 위한 도구이며, 단순한 파일 전송이라면 세션 관리를 알아서 처리하는 webftp_upload_file이나 webftp_download_file을 직접 호출하세요.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
username | string | 아니오 | 세션에 사용할 시스템 사용자 |
work_session_id | string | 아니오 | 감사를 위해 이 세션을 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“deploy 사용자로 db-02에 WebFTP 세션을 열어줘”
에이전트는 server_id를 db-02의 UUID로, username="deploy"로 설정해 webftp_session_create를 호출하고 새 세션의 ID를 반환합니다.
webftp_sessions_list
워크스페이스의 활성·과거 WebFTP 세션을 조회합니다. server_id로 필터링하면 특정 서버의 세션만 볼 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 이 서버의 세션으로 결과를 필터링 |
예시
“지금 web-01에 열려 있는 WebFTP 세션이 뭐가 있어?”
에이전트는 server_id를 web-01의 UUID로 설정해 webftp_sessions_list를 호출합니다.
업로드
webftp_upload_file
로컬 파일을 서버에 업로드합니다. 로컬 절대 경로에서 파일을 읽어 지정한 원격 절대 경로에 배치합니다. 두 경로 모두 절대 경로여야 합니다. 로컬 모드에서만 동작합니다(위 안내 참고).
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
local_file_path | string | 예 | 로컬 파일의 절대 경로 |
remote_file_path | string | 예 | 서버의 목적지 절대 경로 |
username | string | 아니오 | 업로드를 실행할 시스템 사용자 |
allow_overwrite | boolean | 아니오 | 목적지에 파일이 이미 있으면 덮어쓰기 (기본값: true) |
work_session_id | string | 아니오 | 감사를 위해 이 업로드를 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“/Users/me/nginx.conf를 web-01의 /etc/nginx/nginx.conf로 업로드해줘”
에이전트는 로컬·원격 경로와 web-01의 UUID를 server_id로 설정해 webftp_upload_file을 호출합니다.
webftp_upload_content
로컬 파일 경로 대신 base64로 인코딩한 바이트로 서버에 파일 콘텐츠를 업로드합니다. 이미 콘텐츠를 확보한 경우, 예를 들어 Claude Desktop 첨부 파일이나 Claude Code가 Read 도구로 읽은 파일에 사용합니다. 로컬 모드와 원격 모드 모두에서 동작합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
file_content | string | 예 | base64로 인코딩된 파일 콘텐츠 |
remote_file_path | string | 예 | 서버의 목적지 절대 경로 |
file_name | string | 아니오 | 기록할 파일 이름 (기본값: remote_file_path에서 유추) |
username | string | 아니오 | 업로드를 실행할 시스템 사용자 |
allow_overwrite | boolean | 아니오 | 목적지에 파일이 이미 있으면 덮어쓰기 (기본값: true) |
work_session_id | string | 아니오 | 감사를 위해 이 업로드를 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“방금 작성한 이 스크립트를 api-01의 /opt/scripts/deploy.sh에 넣어줘”
에이전트는 스크립트 내용을 base64로 인코딩해 remote_file_path="/opt/scripts/deploy.sh"로 webftp_upload_content를 호출합니다.
webftp_bulk_upload
여러 로컬 파일을 한 번의 작업으로 서버에 업로드하며, 모두 동일한 원격 디렉터리에 배치됩니다. 로컬 모드에서만 동작합니다(위 안내 참고).
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
local_file_paths | array | 예 | 로컬 파일들의 절대 경로 |
remote_directory | string | 예 | 서버의 목적지 디렉터리 절대 경로 |
username | string | 아니오 | 업로드를 실행할 시스템 사용자 |
allow_overwrite | boolean | 아니오 | 목적지에 파일이 이미 있으면 덮어쓰기 (기본값: true) |
work_session_id | string | 아니오 | 감사를 위해 이 업로드를 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“이 설정 파일 3개를 web-01의 /etc/app/conf.d에 업로드해줘”
에이전트는 local_file_paths를 세 로컬 경로로, remote_directory="/etc/app/conf.d"로 설정해 webftp_bulk_upload를 호출합니다.
다운로드
webftp_download_file
서버에서 파일 또는 폴더를 다운로드합니다. 로컬 모드에서는 local_file_path에 파일을 저장합니다. 원격 모드에서는 파일이 준비될 때까지 기다린 뒤 디스크에 저장하는 대신 24시간 동안 유효한 임시 다운로드 링크를 반환합니다. 폴더는 zip 압축 파일로 묶이며, 디렉터리를 다운로드하려면 resource_type="folder"로 설정하세요.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
remote_file_path | string | 예 | 서버의 파일 또는 폴더 절대 경로 |
local_file_path | string | 로컬 모드에서 필수 | 내 컴퓨터의 목적지 절대 경로. 원격 모드에서는 사용하지 않음 |
resource_type | string | 아니오 | file 또는 folder (기본값: file) |
username | string | 아니오 | 다운로드를 실행할 시스템 사용자 |
work_session_id | string | 아니오 | 감사를 위해 이 다운로드를 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“db-02의 /var/log/app.log를 내 Downloads 폴더로 다운로드해줘”
에이전트는 remote_file_path="/var/log/app.log"와 내 컴퓨터의 목적지로 설정한 local_file_path로 webftp_download_file을 호출합니다.
“db-02의 /var/log/app 폴더를 zip으로 가져와줘”
에이전트는 resource_type="folder"로 설정해 폴더를 zip으로 묶은 뒤 전송하도록 합니다.
webftp_bulk_download
여러 파일 또는 폴더를 서버에서 하나의 zip 압축 파일로 다운로드합니다. remote_paths의 모든 경로는 동일한 상위 디렉터리에 있어야 합니다. 로컬 모드에서만 동작합니다(위 안내 참고). 압축 파일이 아직 준비되지 않았다면 webftp_check_status로 상태를 확인한 뒤 다시 시도하세요.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
remote_paths | array | 예 | 파일·폴더들의 절대 경로, 모두 동일한 상위 디렉터리 아래에 있어야 함 |
local_file_path | string | 예 | 내 컴퓨터에서 zip 압축 파일을 저장할 목적지 절대 경로 |
username | string | 아니오 | 다운로드를 실행할 시스템 사용자 |
work_session_id | string | 아니오 | 감사를 위해 이 다운로드를 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“web-01의 /var/log/app/access.log와 /var/log/app/error.log를 zip 하나로 다운로드해줘”
에이전트는 remote_paths를 두 로그 파일 경로로, local_file_path를 내 컴퓨터의 목적지로 설정해 webftp_bulk_download를 호출합니다.
전송 이력
webftp_uploads_list
업로드 이력을 파일 이름, 크기, 타임스탬프, 전송 상태와 함께 조회합니다. server_id로 필터링할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 이 서버로의 업로드로 결과를 필터링 |
예시
“최근에 web-01에 업로드한 게 뭐가 있어?”
에이전트는 server_id를 web-01의 UUID로 설정해 webftp_uploads_list를 호출합니다.
webftp_downloads_list
다운로드 이력을 파일 이름, 크기, 타임스탬프, 전송 상태와 함께 조회합니다. server_id로 필터링할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 이 서버로부터의 다운로드로 결과를 필터링 |
예시
“db-02에 대한 내 다운로드 이력을 보여줘”
에이전트는 server_id를 db-02의 UUID로 설정해 webftp_downloads_list를 호출합니다.
webftp_check_status
WebFTP 업로드 또는 다운로드 작업의 전송 상태(진행 중, 성공, 실패)를 확인합니다. webftp_bulk_download나 다른 비동기 전송 이후 상태를 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
file_id | string | 예 | 확인할 업로드 또는 다운로드의 ID |
transfer_type | string | 예 | upload 또는 download |
예시
“db-02에 대한 내 대량 다운로드가 끝났어?”
에이전트는 이전 webftp_bulk_download 호출이 반환한 file_id와 transfer_type="download"로 webftp_check_status를 호출합니다.