파일 공유(NAS) 연동 가이드

사내 파일 서버를 커넥터에 붙이고 AI 가 파일을 찾게 합니다 — 마운트 · 확인 · 상한.

대상: 사내 파일 서버 / NAS 담당자 · 툴킷 운영자 선행 조건: 커넥터 설치 완료 (Connector 설치 가이드) + 툴킷 사용 가이드 숙지 (Toolkit 사용 가이드) 본 문서는 파일 서버 측 작업 + 커넥터 마운트 중심입니다

이 기능이 하는 일 · 하지 않는 일

AI 가 사내 파일 서버에서 필요한 파일을 찾아내는 것까지가 이 기능입니다.

하는 일	하지 않는 일
폴더 안에 무엇이 있는지 목록으로 보여주기	파일 내용을 도구 결과로 돌려주기
이름 · 확장자 · 수정일로 파일 찾기	파일을 만들거나 고치거나 지우기
찾은 파일마다 참조(ref) 하나씩 만들어 주기	참조 없이 아무 경로나 열기

파일 내용은 도구 결과에 실리지 않습니다. 도구는 목록과 참조만 돌려주고, 실제 파일은 WRKS AI 가 그 참조로 따로 내려받아 답변에 씁니다. 그래서 파일 100개를 찾아도 AI 대화에 들어가는 것은 목록뿐이고, 내용이 필요한 파일만 실제로 읽힙니다.

읽기 전용입니다. 파일을 바꾸거나 지우는 동작은 제품에 없습니다.

공통 보안 원칙

읽기 전용으로 마운트 — 도커 -v 줄 끝에 :ro. 이 기능은 쓰기를 하지 않지만, 읽기 전용으로 붙여 두시면 설령 무슨 일이 생겨도 원본이 안전합니다
마운트 계정의 OS 권한을 좁히세요 — 이것이 실제 경계입니다. 커넥터가 볼 수 있는 범위가 곧 문제가 생겼을 때의 영향 범위입니다
AI 에게 열 폴더를 따로 만드세요 — 부서 공유 전체를 통째로 붙이지 마시고, 전사에 공개해도 되는 자료만 모은 폴더를 만들어 그것만 마운트하시길 권합니다
만드신 뒤 한 번 확인하셔야 열립니다 — 마운트에 실제로 무엇이 있는지 화면에서 보여 드리고, 확인하셔야 엔드포인트를 만들 수 있습니다 (아래 §3)

마운트 봉쇄를 어떻게 봐야 하나 — 솔직한 설명

AI 가 만든 경로는 파일 시스템에 그대로 전달되지 않습니다. 커넥터가 경로를 실제 위치로 굳힌 뒤 마운트 폴더 안인지 검사하고, 벗어나면 거절합니다. 절대 경로 · .. · 심볼릭 링크로 밖을 가리키는 경우가 모두 여기서 막힙니다.

⚠️ 이걸로 다 막히지는 않습니다. SMB 공유가 wide links = yes 로 열려 있으면 서버가 심볼릭 링크를 미리 풀어서 주기 때문에, 커넥터에는 평범한 파일로 보이고 위 검사가 통과합니다. Samba 기본값은 no 라 대개는 막히지만, 켜 두신 공유에서는 서버 설정이 유일한 방어선입니다.

공유 설정에서 wide links 를 끄시고(기본값), 그래도 켜 두셔야 한다면 위 2번 — 마운트 계정의 OS 권한을 좁히는 것으로 피해 범위를 줄여 주세요.

지금은 "전사 공용" 만 쓰실 수 있습니다

툴킷을 만드실 때 이 공유를 누구에게 열지 고르시는데, 지금 고르실 수 있는 것은 전사 공용 하나입니다.

전사 공용 — 이 공유의 모든 파일을 이 툴킷을 쓰는 누구나 봅니다. 사규 · 양식 · 제품 카탈로그처럼 전사에 공개해도 되는 자료에 쓰십니다
부서별 — 부서에 따라 볼 수 있는 폴더가 갈립니다. 아직 준비 중이라 고르실 수 없습니다. 준비되면 안내드리겠습니다

부서별로 갈라야 하는 자료는 지금 붙이지 마시고, 전사에 공개해도 되는 폴더부터 시작하시길 권합니다.

1. 파일 서버를 커넥터 호스트에 마운트

1-1. 마운트하기

커넥터는 호스트에 이미 마운트된 폴더를 봅니다. NAS 를 직접 연결하지 않습니다.

# NFS 예시
sudo mkdir -p /mnt/nas/공유자료
sudo mount -t nfs 10.0.0.50:/volume1/공유자료 /mnt/nas/공유자료 -o ro

# SMB/CIFS 예시 — 자격 증명은 파일로 분리
sudo mount -t cifs //10.0.0.50/공유자료 /mnt/nas/공유자료 \
  -o ro,credentials=/etc/nas-credentials,uid=1000,iocharset=utf8

재부팅 후에도 유지되도록 /etc/fstab 에 넣어 두시길 권합니다.

10.0.0.50:/volume1/공유자료  /mnt/nas/공유자료  nfs  ro,_netdev  0  0

1-2. 마운트가 제대로 붙었는지 확인

# 마운트가 살아 있고 읽히는지
ls -la /mnt/nas/공유자료 | head

# 읽기 전용인지 — "read-only file system" 이 나와야 정상
touch /mnt/nas/공유자료/_test 2>&1

여기까지가 파일 서버 쪽 작업입니다. 커넥터에 이 폴더를 붙이는 명령은 다음 단계에서 화면이 만들어 드립니다.

2. Studio 에서 툴킷 만들고 커넥터에 붙이기

툴킷 → 새 툴킷 만들기
유형에서 파일 공유 (NAS) 선택
이름 과 Connector 선택 — 공유 폴더를 붙이실 그 커넥터입니다
이 공유를 누구에게 열까요? 에서 전사 공용 선택
공유 폴더 경로에 §1-1 에서 마운트하신 경로를 넣습니다 (예: /mnt/nas/공유자료)
화면이 커넥터 실행 명령을 통째로 만들어 드립니다. [복사] 해서 커넥터가 돌아가는 서버에서 실행해 주세요
확인란 체크 후 Toolkit 생성

화면이 만들어 주는 명령은 이렇게 생겼습니다

docker rm -f mcp-connector-<커넥터이름>
docker run -d \
  --name mcp-connector-<커넥터이름> \
  ...
  -v /mnt/nas/공유자료:/var/nas:ro \
  -e MCP_NAS_MOUNT_DIR=/var/nas \
  ...

더해지는 줄	하는 일
`-v <호스트경로>:/var/nas:ro`	호스트에 마운트해 두신 폴더를 컨테이너 안으로. `:ro` 를 빼지 마세요
`MCP_NAS_MOUNT_DIR`	컨테이너 안쪽 경로. 위 `-v` 의 오른쪽과 같습니다

커넥터는 같은 이름·같은 저장소로 다시 뜹니다 — 인증서가 그대로 살아 있어 같은 커넥터로 다시 붙고, 그 커넥터에 걸린 다른 툴킷도 그대로 동작합니다.

⚠️ 커넥터 실행 명령을 직접 손보셨다면 위 명령을 그대로 쓰지 마세요. 직접 더하신 -v·-e 줄이 빠집니다. 그 경우 쓰시던 명령에 위 두 줄만 더해 주세요 — 화면에도 [커넥터 실행 명령을 직접 손보셨다면] 을 펼치면 두 줄만 따로 있습니다.

두 줄을 더하실 때는 이미지 이름(ghcr.io/...)보다 앞에 넣어 주세요. 이미지 이름은 docker run 의 마지막 인자라, 그 뒤에 온 것은 옵션이 아니라 컨테이너에서 실행할 명령으로 읽힙니다.

실행 뒤 확인

# 컨테이너 안에서도 공유 폴더가 보이는지 (컨테이너 이름은 위 명령의 --name 값)
docker exec mcp-connector-<커넥터이름> ls -la /var/nas | head

공유 폴더 경로는 Studio 에 저장되지 않습니다. 어느 폴더를 보여줄지는 전적으로 이 마운트가 정합니다 — 그래서 툴킷 설정 화면에는 폴더를 바꾸는 칸이 없습니다. 바꾸시려면 경로를 고쳐 커넥터를 다시 띄우시면 됩니다.

3. 만드신 뒤 — 공유 폴더 확인 (필수)

툴킷을 만드셨다고 바로 AI 에게 보이지는 않습니다. 도구 탭에 "아직 AI 에게는 이 도구가 보이지 않습니다" 안내와 함께 [공유 폴더 확인하기] 버튼이 나옵니다.

누르시면 마운트에 실제로 있는 것 전부를 보여 드립니다 — 최상위 폴더 목록, 파일 개수, 최근 수정된 파일 몇 건. 이걸 보시고 "우리가 열려던 그 공유가 맞다" 를 확인해 주시면 엔드포인트를 만드실 수 있고, 그때부터 AI 에게 도구가 보입니다.

왜 확인을 받나: 전사 공용은 이 공유의 모든 파일을 누구나 보게 됩니다. 마운트를 한 칸 위로 잡으셨거나 예상 못 한 폴더가 섞여 있으면 그때 발견하시는 편이 낫습니다.

확인의 한계: 확인하신 그 시점의 내용을 보신 것입니다. 확인 뒤에 기밀 파일이 그 폴더로 들어오면 그건 막지 못합니다. 공유 폴더에 무엇을 두실지는 계속 관리해 주셔야 합니다.

엔드포인트 발급은 툴킷 가이드와 동일합니다 (Toolkit 사용 가이드).

4. AI 가 쓰는 도구 3개

파일 공유 툴킷은 도구가 자동으로 만들어집니다. 문서를 올리실 필요가 없고, 켜고 끄거나 이름을 바꾸실 수도 없습니다.

도구	하는 일
`list_files`	폴더 하나의 바로 아래 내용을 봅니다 (하위 폴더까지 뒤지지 않음)
`search_files`	공유 전체에서 이름 · 확장자 · 수정일로 찾습니다 (하위 폴더까지)
`fetch_file`	찾은 파일의 내용을 WRKS AI 가 내려받습니다

fetch_file 은 WRKS AI 에서만 동작합니다. 다른 MCP 클라이언트에 연결하시면 파일을 찾고 목록을 보는 것까지는 그대로 되지만, 파일 내용은 열리지 않습니다.

상한 — 결과가 잘릴 수 있습니다

상한	값
목록 한 번에 돌려주는 개수	기본 200개 · 최대 500개
검색 한 번에 찾는 개수	기본 100개
검색이 들어가는 폴더 깊이	8단계
검색에 쓰는 시간	3초

결과가 잘리면 무엇에 걸려 잘렸는지(개수 · 깊이 · 시간) 함께 알려 드립니다. 파일이 아주 많은 공유라면 폴더를 나눠 여러 툴킷으로 붙이시는 편이 찾기가 잘 됩니다.

5. 트러블슈팅

증상 / 표시	원인 · 해결
`mount_not_configured`	커넥터에 `MCP_NAS_MOUNT_DIR` 이 없습니다 — §2 에서 화면이 만들어 준 명령으로 커넥터를 다시 띄워 주세요
`mount_missing`	지정하신 경로가 컨테이너 안에 없습니다 — `-v` 의 오른쪽과 `MCP_NAS_MOUNT_DIR` 이 같은지 확인
`mount_not_directory`	폴더가 아니라 파일을 가리키고 있습니다
`mount_unavailable`	마운트가 끊겼습니다 — 호스트에서 `ls` 로 확인, NFS/SMB 재마운트
`path_escape` · `path_absolute`	마운트 밖을 가리키는 요청이 거절됐습니다 — 정상 동작입니다
`path_not_found`	그 경로에 파일·폴더가 없습니다. 한글 이름이면 아래 항목도 확인해 주세요
`path_ambiguous`	이름이 눈으로는 같은데 저장된 바이트가 다른 파일이 한 폴더에 둘 이상 있습니다 (아래 참고)
도구 탭에 "AI 에게 보이지 않습니다"	§3 의 공유 폴더 확인을 아직 안 하셨거나, 엔드포인트가 없습니다 — 화면 안내가 어느 쪽인지 알려 줍니다
목록이 비어 있음	마운트 계정에 그 폴더 읽기 권한이 없을 수 있습니다 — 호스트에서 커넥터 계정으로 `ls` 확인

macOS 에서 만든 파일과 Windows 에서 만든 파일은 같은 한글이라도 저장된 바이트가 다를 수 있습니다 (완성형 · 자모 분리). 커넥터는 양쪽을 같은 것으로 보고 찾아 주지만, 한 폴더 안에 두 방식이 섞여 같은 이름이 둘 있으면 어느 쪽인지 정할 수 없어 거절합니다(path_ambiguous). 그 경우 파일 이름을 하나로 정리해 주세요.