NiChart DLMUSE MCP
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시간) 후 삭제됩니다.
Related MCP server: agent-bridge-mcp
아키텍처
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가 보통 이미 설치되어 있습니다).
이 리포지토리를 인스턴스에 복사합니다 (
git clone/scp -r).cp .env.example .env를 실행하고 최소한TOKENS를 채웁니다 — 팀원당name:token쌍 하나, 쉼표로 구분. 토큰은openssl rand -hex 32로 생성합니다.인스턴스의 보안 그룹에서 인바운드
22(SSH)만 허용하고, 팀의 IP 또는 배스천으로 제한합니다. 다른 것은 열지 마세요 —443,8420도 열지 마세요. 앱은127.0.0.1에 바인딩되어 SSH 터널을 통해서만 접근할 수 있습니다.프로비저닝 스크립트를 실행합니다:
sudo ./deploy/setup_ec2.sh이 스크립트는 멱등적입니다 — 누락된 경우에만 Docker/nvidia-container-toolkit을 설치하고, DLMUSE 이미지를 가져오고, 전용
nichart-mcp서비스 사용자를 만들고, 코드를/opt/nichart-mcp에 배포하고, 자체 서명 TLS 인증서(SAN =127.0.0.1/localhost)를 생성하고,nichart-mcpsystemd 서비스를 설치합니다.인스턴스 자체에서 확인합니다:
curl --cacert /opt/nichart-mcp/tls/server.crt https://127.0.0.1:8420/healthz인스턴스에서
/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.crtLinux:
sudo cp server.crt /usr/local/share/ca-certificates/nichart-mcp.crt && sudo update-ca-certificatesWindows:
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에게 스캔 분할을 요청하면 다음 단계를 수행합니다:
파일을 업로드합니다 (터널을 통해 업로드하므로 파일이 원격 인스턴스로 향하더라도
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": "..."}해당
upload_id로run_dlmuse_segmentation도구를 호출 ->job_id를 받습니다.status == "done"이 될 때까지get_job_status(job_id)를 폴링합니다 (GPU에서 보통 ~1-2분).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 단계에서 작업이 실패하지만 그 외의 모든 것(라우팅, 인증, 큐잉, 상태/오류 보고)은 테스트할 수 있습니다.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted MCP server for task-first delegation to remote workstations and workers.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for audio stem separation, denoise, reverb, and MIDI export.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for "taming the Claude" with structured task queues.14134 npm71MIT
- AlicenseAqualityDmaintenanceAn MCP-only server that launches AI CLI tasks (Claude, Codex, Gemini, Forge, OpenCode) as background subprocesses and manages them via PID for status, output, and lifecycle control.98 npmMIT
- FlicenseAqualityAmaintenanceWraps the Micu image API as an MCP server for generating, editing, batch processing, and multi-reference image fusion, supporting GPT-image-2 and Grok models.5332-
- AlicenseAqualityBmaintenanceA fire-and-poll MCP server that lets Claude Code run long background jobs without hitting tool-call timeouts.3MIT