AI 에이전트 도구가 많아질수록 이상한 일이 생긴다. 모델은 똑똑해지는데, 사람이 붙여야 하는 도구 설명은 더 길어진다. GitHub는 GitHub 방식, Slack은 Slack 방식, Notion은 Notion 방식, S3는 S3 방식으로 붙다 보면 에이전트는 일을 하기 전에 도구 사용법부터 외워야 한다.
Mirage는 이 문제를 정면으로 바꿔 묻는다. 에이전트에게 새 API와 새 MCP를 계속 가르칠 게 아니라, 여러 서비스를 하나의 Unix식 파일시스템처럼 보이게 만들면 어떨까. GitHub, Slack, Gmail, S3, Google Drive, Notion 같은 백엔드를 /github, /slack, /s3, /docs 아래에 마운트하고, 에이전트는 cat, grep, cp, wc 같은 익숙한 명령으로 다루게 하는 발상이다.
이 글은 Mirage 사용기를 가장한 글이 아니다. 아직 운영에 넣기 전이라면 먼저 봐야 할 것은 멋진 데모보다 권한, credential, 캐시, 감사 로그다. 에이전트에게 파일시스템을 하나 더 주는 순간, 편해지는 만큼 사고 반경도 넓어진다.
먼저 답을 잡으면
Mirage는 AI 에이전트를 위한 통합 가상 파일시스템이다. 핵심은 “모든 백엔드를 파일처럼 다루자”가 아니라, “에이전트 도구 인터페이스를 하나의 추상화로 줄이자”에 가깝다.
MCP가 서비스별 도구를 붙이는 방식이라면, Mirage는 여러 리소스를 하나의 mount tree로 보이게 한다. 에이전트 입장에서는 Slack 메시지를 읽고, GitHub README를 보고, S3 로그를 grep하는 일이 같은 형태의 파일 조작으로 바뀐다.
그래서 Mirage를 볼 때 질문은 세 가지다.
| 질문 | 왜 중요한가 | 운영 체크 |
|---|---|---|
| MCP를 대체하나, 보완하나 | 도구 경계가 달라진다 | 서비스별 권한 정책과 mount 권한을 분리 |
| 캐시는 어디에 남나 | 민감 데이터가 복제될 수 있다 | RAM/Redis TTL, 암호화, 삭제 정책 확인 |
| 실패하면 어떻게 복구하나 | 에이전트 작업은 길게 이어질 수 있다 | snapshot, 로그, 재실행 기준 정의 |
Mirage가 해결하려는 문제
에이전트 운영에서 제일 귀찮은 부분은 모델보다 도구 표면이다. 서비스가 하나 늘 때마다 인증, rate limit, 입력 스키마, 출력 포맷, 에러 처리 방식이 늘어난다. 처음에는 강력해 보이지만, 일정 수준을 넘으면 도구가 생산성보다 인지 부하를 만든다.
Mirage의 GitHub README는 자신을 AI 에이전트를 위한 unified virtual filesystem으로 설명한다. 하나의 파일시스템 트리에 S3, Google Drive, Slack, Gmail, Redis 같은 리소스를 나란히 마운트하고, 에이전트가 Unix-like tools로 백엔드들을 다루게 한다는 구조다.
이 발상이 TECHTAEK 관점에서 흥미로운 이유는 명령어가 새롭지 않기 때문이다. LLM은 이미 bash, 파일 경로, grep, cat, pipe 같은 텍스트 작업 패턴을 많이 알고 있다. 에이전트가 가장 잘 아는 작업 표면을 API 통합 계층으로 쓰겠다는 점이 실용적이다.
MCP와 Mirage는 어디서 다르나
MCP는 모델과 외부 도구 사이의 표준 인터페이스를 만드는 쪽에 가깝다. 서비스가 제공하는 도구를 함수처럼 노출하고, 에이전트는 그 도구를 호출한다. 잘 맞으면 명확하고 안전하다.
Mirage는 관점이 조금 다르다. 도구를 함수 목록으로 늘리는 대신, 여러 서비스를 파일시스템 semantics로 맞춘다. 에이전트는 “GitHub의 이 API를 호출해”가 아니라 “이 경로의 파일을 읽고, 이 명령을 실행해”라는 형태로 일할 수 있다.
둘 중 하나가 무조건 낫다는 이야기는 아니다. 오히려 운영에서는 섞일 가능성이 크다. 중요한 것은 어떤 추상화가 더 안전한 기본값을 주는지다.
| 상황 | MCP가 편한 경우 | Mirage가 편한 경우 |
|---|---|---|
| 명확한 단일 작업 | issue 생성, calendar 등록, 티켓 상태 변경 | 여러 파일과 로그를 훑어 패턴 찾기 |
| 권한 분리 | 도구 단위로 허용/차단 | mount 단위 read/write 제한 |
| 에이전트 조사 작업 | 스키마가 고정된 조회 | find, grep, cat 조합이 자연스러운 탐색 |
| 긴 실행 | tool call 로그 중심 | workspace snapshot과 파일 기반 산출물 중심 |
Codex와 Claude Code에 붙일 때 먼저 볼 것
Mirage README는 Claude Code와 Codex 같은 코딩 에이전트에 CLI와 daemon 방식으로 붙을 수 있다고 설명한다. 이 문장은 흥미롭지만, 바로 운영에 꽂기 전에 체크리스트가 필요하다.
첫 번째는 mount별 권한이다. /github는 읽기만 허용할지, 특정 repo만 쓰게 할지, branch 생성까지 열지 정해야 한다. /slack은 읽기 범위가 특히 민감하다. 에이전트가 전체 워크스페이스를 grep할 수 있으면 편하지만, 그만큼 내부 대화가 작업 맥락 밖으로 새기 쉽다.
두 번째는 credential 저장 위치다. S3, Slack, Gmail, GitHub, Notion 토큰은 모두 사고 반경이 크다. .env에 넣는 것으로 끝내면 편하지만, 운영에서는 토큰 회전, 최소 권한, 감사 로그, secret masking이 필요하다.
세 번째는 쓰기 작업의 승인 흐름이다. 읽기 중심 탐색은 자동으로 돌릴 수 있어도, 쓰기 작업은 다르다. cp /data/report.md /docs/report.md처럼 보이는 명령도 실제로는 외부 문서 변경일 수 있다. 파일 명령이라고 가벼운 작업이 되는 것은 아니다.
캐시가 장점이자 위험인 이유
Mirage는 index cache와 file cache를 제공한다고 설명한다. 디렉터리 리스팅과 메타데이터를 캐시하고, 오브젝트 바이트도 캐시한다. 기본 RAM 캐시는 단일 프로세스에서 가볍고, Redis를 쓰면 워커와 머신 사이에서도 캐시를 공유할 수 있다.
이건 성능에는 좋다. 원격 API를 매번 때리지 않아도 되고, 긴 에이전트 작업에서 같은 자료를 반복 읽을 때 비용과 latency를 줄일 수 있다. 문제는 캐시가 곧 복제라는 점이다.
민감한 Slack 메시지, 고객 데이터, 비공개 문서, repo 파일이 캐시에 남으면 원본 서비스의 권한 모델 밖에 또 다른 데이터 위치가 생긴다. 그래서 캐시를 켤 때는 TTL과 저장 위치를 먼저 봐야 한다. Redis를 쓴다면 접근 제어, 암호화, 백업 포함 여부까지 확인해야 한다.
| 캐시 항목 | 좋은 점 | 위험 | 먼저 정할 것 |
|---|---|---|---|
| Index cache | 목록 탐색이 빨라짐 | 존재하면 안 되는 경로 노출 | TTL, mount별 scope |
| File cache | 반복 분석 비용 감소 | 민감 데이터 복제 | 암호화, 삭제, 크기 제한 |
| Redis cache | 여러 워커가 공유 | 운영 데이터 저장소가 하나 더 생김 | 네트워크 접근, 인증, 백업 정책 |
도입 전 체크리스트
Mirage를 실험할 때는 기능 목록보다 경계를 먼저 정하는 편이 좋다.
| 체크 | 질문 | 권장 시작점 |
|---|---|---|
| Read/write 분리 | 모든 mount가 쓰기 가능해야 하나 | 처음에는 read-only mount부터 |
| Credential | 토큰은 어디에 저장하고 누가 회전하나 | 서비스별 최소 권한 토큰 |
| Audit | 어떤 명령이 어떤 데이터를 읽었나 | 명령 로그와 산출물 경로 기록 |
| Cache | 민감 데이터가 캐시에 남나 | 짧은 TTL, 작은 limit, 민감 mount 캐시 off |
| Snapshot | 상태 복구가 필요한가 | 데모와 운영 workspace 분리 |
| Cost | API 호출과 대용량 파일 접근 비용은 | cache miss, 스트리밍, rate limit 모니터링 |
작은 실험이라면 /data 같은 RAM mount와 공개 repo mount부터 시작하는 편이 낫다. 내부 Slack, Gmail, Notion을 처음부터 붙이면 데모는 화려해지지만 검토할 보안 항목도 같이 커진다.
Mirage를 허브에 붙이는 방법
Mirage는 단독 도구 글보다 AI 에이전트 운영 허브의 하위 개념으로 두는 편이 좋다. 핵심 키워드는 “가상 파일시스템”, “MCP 보완”, “credential 경계”, “캐시 보안”, “portable workspace”다.
Claude Code나 Codex를 이미 쓰고 있다면, Mirage는 더 많은 일을 하게 만드는 도구가 아니라 더 적은 인터페이스로 같은 일을 하게 만드는 실험으로 보는 게 안전하다. 도구를 늘리는 것이 목표가 아니라, 에이전트가 이해해야 할 표면을 줄이는 것이 목표다.
내 기준으로는 바로 프로덕션에 넣기보다 세 단계가 맞다. 첫째, 공개 repo와 샘플 S3 같은 낮은 위험 데이터로 데모를 돌린다. 둘째, 읽기 전용 내부 문서 한두 개만 붙여 감사 로그와 캐시를 본다. 셋째, 쓰기 작업은 승인 게이트를 붙인 뒤 제한적으로 연다.
마무리
Mirage의 매력은 거창한 AI 단어보다 단순한 파일 경로에 있다. 에이전트에게 매번 새로운 도구 문법을 가르치는 대신, 이미 익숙한 파일과 bash 표면으로 여러 서비스를 묶는 발상이다.
다만 통합 인터페이스는 양날이다. 한 번에 많은 곳을 읽을 수 있으면, 한 번에 많은 곳을 잘못 읽을 수도 있다. 한 번에 여러 곳에 쓸 수 있으면, 실수도 여러 시스템으로 퍼진다.
그래서 Mirage를 볼 때의 결론은 이렇다. 데모는 파일시스템으로 보고, 운영은 권한 시스템으로 보자. 에이전트가 편해지는 만큼 사람이 정해야 할 경계가 더 중요해진다.
FAQ
Q. Mirage는 MCP를 대체하나?
완전한 대체라기보다 다른 추상화다. MCP가 도구 호출 표준에 가깝다면, Mirage는 여러 리소스를 파일시스템 semantics로 통일한다. 실제 운영에서는 함께 쓰일 가능성이 크다.
Q. Claude Code나 Codex에 바로 붙여도 되나?
기술적으로는 CLI나 daemon 방식으로 연결할 수 있지만, 운영적으로는 read-only mount, 낮은 위험 데이터, 짧은 캐시 TTL부터 시작하는 편이 안전하다.
Q. 가장 큰 위험은 무엇인가?
credential과 캐시다. 여러 서비스 토큰을 한 곳에서 다루고, 원격 데이터가 로컬이나 Redis 캐시에 남을 수 있기 때문에 최소 권한, TTL, 감사 로그가 필요하다.
Q. 어떤 팀에 먼저 맞나?
여러 SaaS와 저장소를 넘나들며 조사, 요약, 로그 분석, 문서 생성을 자동화하는 팀에 먼저 맞다. 단일 서비스 작업만 한다면 MCP나 기존 SDK가 더 단순할 수 있다.