NiChart DLMUSE MCP server

GPU EC2 인스턴스의 MCP 서버 뒤에서 cbica/nichart_dlmuse (T1 MRI skull-strip + MUSE ROI segmentation)를 호스팅하므로, 모든 사용자가 로컬 GPU를 요구하지 않아도 Claude Code가 원격으로 분할 작업을 실행할 수 있습니다.

이렇게 구성된 이유

MCP 도구 인자는 JSON입니다. .nii.gz는 수십 MB의 바이너리이며, 분할은 GPU에서 ~1-2분이 걸립니다 — 단일 블로킹 도구 호출에는 너무 느리고 큽니다. 그래서:

• 파일 전송은 MCP 프로토콜 외부에서 이루어집니다: 인증된 일반 POST /upload 엔드포인트를 통해. 오직 작은 upload_id만 MCP 도구 인자로 전달됩니다.

• 작업은 비동기입니다: run_dlmuse_segmentation은 작업을 큐에 넣고 즉시 반환합니다. get_job_status는 폴링하고, get_job_result는 CSV를 인라인으로 가져오며 마스크 파일 다운로드 링크를 제공합니다.

• 단일 워커, 직렬화: 하나의 공유 GPU이므로 한 번에 하나의 docker run만 실행되며, asyncio.Queue 뒤에서 대기열을 이룹니다.

• Bearer 토큰 인증: /healthz를 제외한 모든 엔드포인트에서 팀원별로 인증합니다.

• 프라이빗 인스턴스, 공용 웹 계층 없음: 앱은 127.0.0.1에만 바인딩되고, 보안 그룹은 SSH(22)만 엽니다. 사용자는 SSH 포트 포워딩으로 노트북을 해당 루프백 포트에 연결하고 개인 키로 접속합니다 — 도메인도 없고 인터넷에 노출된 공격 대상도 없습니다.

• TLS는 자체 서명 인증서입니다. 인스턴스에서 한 번 생성됩니다. 공개적으로 발급된 인증서(Let's Encrypt 등)는 도메인 검증을 위해 인스턴스가 인터넷에서 접근 가능해야 하는데, 이 인스턴스는 그렇지 않기 때문입니다. 각 사용자는 노트북에서 해당 인증서 하나를 신뢰합니다(아래 참조).

• 스캔 데이터는 영원히 보관되지 않습니다: 업로드와 작업 출력은 RETENTION_HOURS(기본 24시간) 후 삭제됩니다.

아키텍처

Claude Code (laptop)                    SSH tunnel                  EC2 (private, SG: 22 only)
  │  ssh -i key.pem -L 8420:127.0.0.1:8420 user@instance ─────────────────►  │
  │                                                                          │
  │  1. curl https://127.0.0.1:8420/upload ─────(via tunnel)──────────►  MCP server :8420 (127.0.0.1, self-signed TLS)
  │  2. run_dlmuse_segmentation ────────────────(via tunnel)──────────►         │
  │  3. get_job_status (poll) ──────────────────(via tunnel)──────────►  asyncio job queue (1 worker)
  │  4. get_job_result ─────────────────────────(via tunnel)──────────►         │
                                                                   docker run --gpus all cbica/nichart_dlmuse

저장소 구조

server/app.py     MCP tools (run_dlmuse_segmentation, get_job_status, get_job_result)
                  + HTTP routes (/upload, /download/{job_id}/{filename}, /healthz)
server/jobs.py    job queue/worker, docker invocation, root-owned-output cleanup
server/auth.py    bearer-token ASGI middleware
server/config.py  env-driven settings
deploy/           EC2 provisioning script (installs Docker, GPU toolkit, self-signed cert, systemd unit)

일회성 EC2 설정

기존 GPU EC2 인스턴스가 필요합니다 (AWS Deep Learning AMI 권장 — NVIDIA 드라이버와 Docker가 보통 이미 설치되어 있습니다).

1. 이 리포지토리를 인스턴스에 복사합니다 (git clone / scp -r).

2. cp .env.example .env를 실행하고 최소한 TOKENS를 채웁니다 — 팀원당 name:token 쌍 하나, 쉼표로 구분. 토큰은 openssl rand -hex 32로 생성합니다.

3. 인스턴스의 보안 그룹에서 인바운드 22(SSH)만 허용하고, 팀의 IP 또는 배스천으로 제한합니다. 다른 것은 열지 마세요 — 443, 8420도 열지 마세요. 앱은 127.0.0.1에 바인딩되어 SSH 터널을 통해서만 접근할 수 있습니다.

4. 프로비저닝 스크립트를 실행합니다:

   sudo ./deploy/setup_ec2.sh

   이 스크립트는 멱등적입니다 — 누락된 경우에만 Docker/nvidia-container-toolkit을 설치하고, DLMUSE 이미지를 가져오고, 전용 nichart-mcp 서비스 사용자를 만들고, 코드를 /opt/nichart-mcp에 배포하고, 자체 서명 TLS 인증서(SAN = 127.0.0.1/localhost)를 생성하고, nichart-mcp systemd 서비스를 설치합니다.

5. 인스턴스 자체에서 확인합니다:

   curl --cacert /opt/nichart-mcp/tls/server.crt https://127.0.0.1:8420/healthz

6. 인스턴스에서 /opt/nichart-mcp/tls/server.crt를 복사하여 각 팀원에게 전달합니다 (예: scp -i key.pem ec2-user@<instance-ip>:/opt/nichart-mcp/tls/server.crt .).

나중에 사용자를 추가하거나 해지하려면: 인스턴스의 /opt/nichart-mcp/.env에서 TOKENS를 편집한 후 sudo systemctl restart nichart-mcp를 실행합니다.

코드 업데이트

인스턴스의 업데이트된 체크아웃에서 sudo ./deploy/setup_ec2.sh를 다시 실행합니다 — /opt/nichart-mcp를 다시 동기화하고(기존 TLS 인증서는 그대로 둠), 의존성을 재설치하고, 서비스를 재시작합니다.

노트북에서 연결하기

각 팀원은 SSH 개인 키(Windows PuTTY .ppk 키의 경우 표준 ssh 클라이언트가 사용할 수 있도록 puttygen key.ppk -O private-openssh -o key.pem으로 한 번 변환), 자신의 bearer 토큰, 그리고 설정 6단계의 server.crt 파일이 필요합니다.

1. 자체 서명 인증서를 한 번 신뢰합니다, 그러면 curl/Claude Code가 더 이상 거부하지 않습니다:

• macOS: security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db server.crt

• Linux: sudo cp server.crt /usr/local/share/ca-certificates/nichart-mcp.crt && sudo update-ca-certificates

• Windows: certutil -addstore -f "ROOT" server.crt

2. SSH 터널을 엽니다 (Claude Code를 사용하는 동안 터미널에서 계속 실행해 둡니다):

ssh -i key.pem -N -L 8420:127.0.0.1:8420 <ssh_user>@<instance-ip>

인스턴스에 공용 IP가 없고 배스천을 통해서만 접근할 수 있다면 -J <bastion_user>@<bastion_host>를 추가합니다.

3. MCP 서버를 Claude Code에 한 번 등록합니다:

claude mcp add --transport http nichart-dlmuse https://127.0.0.1:8420/mcp \
  --header "Authorization: Bearer <their-token>"

사용하기

터널이 열린 상태에서 Claude Code에게 스캔 분할을 요청하면 다음 단계를 수행합니다:

1. 파일을 업로드합니다 (터널을 통해 업로드하므로 파일이 원격 인스턴스로 향하더라도 127.0.0.1:8420이 맞습니다):

   curl -X POST -H "Authorization: Bearer <token>" \
     -F "file=@/path/to/scan.nii.gz" \
     https://127.0.0.1:8420/upload
   # -> {"upload_id": "..."}

2. 해당 upload_id로 run_dlmuse_segmentation 도구를 호출 -> job_id를 받습니다.

3. status == "done"이 될 때까지 get_job_status(job_id)를 폴링합니다 (GPU에서 보통 ~1-2분).

4. get_job_result(job_id) 호출 -> ROI 볼륨 CSV 인라인 및 ICV/MUSE 마스크 NIfTI 파일용 /download/{job_id}/{filename} 링크가 제공됩니다 (같은 bearer 토큰을 사용하여 같은 터널을 통해 https://127.0.0.1:8420/download/...에서 가져옵니다).

운영 참고 사항

• GPU 동시성: 설계상 한 번에 하나의 작업만 실행됩니다 (단일 공유 GPU). 팀이 바쁘면 작업이 대기열에 쌓입니다. get_job_status는 queue_position을 보고합니다.

• 작업 상태는 메모리 내에 저장됩니다: systemctl restart nichart-mcp를 실행하면 진행 중인 작업 기록이 유실됩니다 (업로드된 스캔과 디스크의 부분 출력물은 영향이 없지만, 작업을 다시 제출해야 합니다). 소규모 팀 규모에서는 문제없습니다. 규모가 커지면 server/jobs.py의 인메모리 dict를 Redis/RQ로 교체하세요.

• PHI: 스캔은 실제 환자 데이터입니다. RETENTION_HOURS는 디스크에 보관되는 시간을 제한하지만, 실제 환자에게 적용하기 전에 데이터 처리 요구사항과 호환되는지 확인하세요. 아직 활성화하지 않았다면 인스턴스 볼륨에 EBS 암호화를 활성화하는 것을 고려하세요.

• DLMUSE 컨테이너는 내부에서 root로 실행됩니다 (/app/pipeline.log에 대한 쓰기 경로가 하드코딩되어 있어 --user로 실행할 수 없습니다). 출력물은 root 소유가 됩니다. server/jobs.py의 정리 로직은 강제 제거를 위해 일회용 alpine 컨테이너를 사용합니다.

로컬 개발

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp .env.example .env   # fill in TOKENS
TOKENS=dev:devtoken DATA_DIR=/tmp/nichart-dev .venv/bin/python -m server.app

이것은 전체 서버(인증, 업로드, 작업 큐, MCP 도구)를 로컬에서 실행합니다. 실제 분할을 실행하려면 여전히 GPU에 접근할 수 있는 Docker가 필요합니다 — GPU가 없는 머신에서는 docker run 단계에서 작업이 실패하지만 그 외의 모든 것(라우팅, 인증, 큐잉, 상태/오류 보고)은 테스트할 수 있습니다.