코딩 에이전트가 Docker에서 필요로 하는 것
실제 프로젝트에서 작업하는 에이전트는 몇 가지 질문을 반복합니다. 무엇이 실행 중인지, 포트 3000의 앱은 무엇인지, 컨테이너가 왜 종료되었는지, 로그에 무엇이 나오는지, 일회용 환경에서 테스트를 실행할 수 있는지 등입니다. 셸만 있으면 docker ps, docker inspect, docker logs를 실행하고 반환된 모든 줄을 읽어 답합니다. 작동은 하지만 느리고 비용이 큽니다. 매 턴마다 원시 JSON과 수백 줄의 로그가 모델 컨텍스트에 들어갑니다.
MCP 서버는 이런 질문을 답 자체를 반환하는 도구로 바꿉니다. Oxcart 도구는 Docker API 엔드포인트가 아니라 질문에 맞춰 설계되어 한 번의 호출로 여러 명령을 대체합니다.
도구 13개
| 목적 | 도구 | 도구가 표시되는 최소 권한 수준 |
|---|---|---|
| 확인 | status, projects, ports, images, logs | Read only(읽기 전용) |
| 설명 | diagnose: 종료 코드, OOM 종료, 상태 확인 실패, 포트 문제, 중요한 로그 줄 | Read only(읽기 전용) |
| 실행 | container(시작, 중지, 재시작), exec, compose(up, down), 네트워크 없는 sandbox | Manage(관리) |
| 변경 및 정리 | build, remove, cleanup(먼저 미리 보기), 네트워크가 있는 sandbox | Full(전체 권한) |
status는 각 Compose 프로젝트의 폴더, git 브랜치, localhost URL을 보여 주므로 사용자와 에이전트가 '포트 3000의 앱'을 같은 대상으로 이해합니다. 리소스를 구독하는 클라이언트는 폴링 없이 충돌, OOM 종료, 상태 변경이 발생할 때 알림을 받습니다.
더 작은 응답, 더 낮은 세션 비용
에이전트가 각 질문에 답하기 위해 Oxcart로 읽는 내용과 대신 읽어야 하는 docker CLI 출력을 비교했습니다. 같은 시점에 같은 컨테이너에서 측정했습니다.
| 질문 | Oxcart MCP | 대응하는 docker CLI 명령 | docker CLI | 축소 배율 |
|---|---|---|---|---|
| 이 컨테이너는 왜 중지되었나요? | 159 | inspect + logs --tail 300 | 2,014 | 13× |
| 최근 로그 500줄에 오류가 있나요? | 39 | logs --tail 500 | 703 | 18× |
| 무엇이 실행 중인가요? | 106 | ps -a + stats --no-stream + compose ls -a | 332 | 3.1× |
테스트 컨테이너 5개(충돌, 비정상 상태, OOM 종료, Compose 프로젝트, 게시된 포트)를 사용했습니다. 로그가 아무리 길어져도 diagnose와 logs의 크기는 일정합니다. 도구 목록 자체는 세션당 한 번 읽기 전용 수준(도구 6개)에서 510토큰, 전체 13개 도구에서 1,463토큰이 듭니다.
전체 세션에서도 같은 경향을 보였습니다. Claude Opus 5.5를 사용하는 Claude Code가 일상적인 질문 두 개에 대해 docker CLI만 사용하는 경우와 Oxcart MCP 서버를 사용하는 경우로 각각 답했습니다. 두 조건 모두 두 질문에 정확히 답했습니다.
| 작업 | 시간 | 비용 | 토큰 수 | 턴 수 |
|---|---|---|---|---|
“worker에서 오류가 발생하나요? 오류를 보여 주세요.” | 4.2 s 대 31.0 s | $0.022 대 $0.157 | 10,686 대 52,266 | 2 대 8 |
“api 컨테이너가 계속 종료됩니다. 왜 그런가요?” | 8.5 s 대 14.9 s | $0.036 대 $0.070 | 11,283 대 19,510 | 2 대 4 |
각 작업을 Oxcart 사용 및 미사용 조건에서 세션 1회씩, 인위적으로 구성한 테스트 컨테이너와 Oxcart 0.1.0으로 실행한 참고 수치입니다. 비용은 프롬프트 캐시에 따라 달라지며 실행 순서는 교대로 배치하지 않았습니다.
모든 코딩 에이전트에 Oxcart MCP 서버 설정
- Oxcart를 설치하세요. Oxcart(Apple Silicon, macOS 26 이상)를 다운로드해 엽니다. 설정은 오프라인으로 몇 초면 완료됩니다.
- 설정 문장을 복사하세요. Oxcart 사이드바의 MCP Integrations를 열고 다음 문장을 복사하세요. “Oxcart MCP 서버를 설정해 주세요.
/Applications/Oxcart.app/Contents/Helpers/oxcart agent setup을 실행하고 안내를 따르세요.” - 에이전트에 붙여넣으세요. Claude Code, Codex, Cursor 또는 명령을 실행할 수 있는 에이전트에 붙여넣습니다. 에이전트가 명령을 실행하고 자신에게 맞는 절차를 읽은 뒤
oxcart라는 서버를 등록합니다. - 컨테이너에 대해 질문하세요. “무엇이 실행 중인가요?” 또는 “
api는 왜 중지되었나요?”라고 물어보세요. 에이전트가 MCP Integrations 페이지에 읽기 전용으로 표시되며 모든 호출은 활동 로그에 기록됩니다. - 필요하면 권한 수준을 높이세요. Manage로 설정하면 시작, 중지, exec, Compose 실행을 허용하며, Full로 설정하면 빌드, 삭제, 정리도 허용합니다. Block은 모든 호출을 거부합니다.
에이전트가 명령을 실행할 수 없다면(Claude Desktop, LM Studio 등) Oxcart가 앱의 MCP 설정에 추가할 JSON 조각을 표시합니다. Claude Code의 직접 설정 명령은 다음과 같습니다.
claude mcp add -s user oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client claude-codeCodex에서는 codex mcp add oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client codex가 Codex CLI와 IDE 확장에 서버를 등록합니다.
에이전트별로 설정하는 권한 수준
| 수준 | 에이전트가 할 수 있는 작업 |
|---|---|
| Read only(기본값, 읽기 전용) | 컨테이너, 로그, 포트, 프로젝트, 이미지 확인 및 장애 진단 |
| Manage(관리) | 추가로 시작, 중지, 재시작, 명령 실행, Compose up/down, 네트워크 없는 샌드박스 실행 |
| Full(전체 권한) | 추가로 빌드, 삭제, 정리, 샌드박스 네트워크 접근 허용 |
| Block(차단) | 아무 작업도 불가. 도구를 표시하지 않고 모든 호출을 거부하며 에이전트에 이유를 알림 |
에이전트 권한보다 높은 도구는 목록에 표시되지 않으므로 컨텍스트도 작게 유지됩니다. 모든 호출은 Mac에 기록되어 MCP Integrations 페이지에 표시되며 기록은 Mac 밖으로 나가지 않습니다. 권한 수준은 Oxcart 도구가 에이전트를 위해 수행하는 작업을 제어합니다. 샌드박스는 아니므로 셸 명령을 실행할 수 있는 에이전트는 직접 docker를 실행할 수 있습니다. 에이전트 자체 명령 권한과 함께 사용하세요.
설정 절차가 제공되는 에이전트
Claude Code, Claude Desktop, Codex, Cursor, Copilot을 사용하는 VS Code, Devin Desktop, Zed, Gemini CLI, GitHub Copilot CLI, OpenCode, Cline, Junie, JetBrains AI Assistant, Goose, Kiro, Amp, Warp, LM Studio와 그 외 MCP 클라이언트용 일반 절차를 제공합니다. 절차는 설치된 Oxcart(oxcart agent setup)에서 Mac의 실제 경로를 사용해 제공되므로 오프라인에서 작동하며 설치된 버전과 일치합니다.
MCP 외의 에이전트 컨테이너 워크플로
- Dev Containers: 에이전트를 Dev Container 안에서 실행해 셸, 도구, 네트워크를 프로젝트 컨테이너 안에 유지하세요. Oxcart는 Dev Containers CLI를 실행합니다. Mac에서 Dev Containers 및 Testcontainers 사용을 확인하세요.
- 빠른 반복 작업: 에이전트는 컨테이너를 계속 실행하고 정리합니다. Oxcart는
docker run --rm에 42 ms, 컨테이너 20개 중지 및 삭제에 77 ms를 기록해 테스트한 세 런타임 중 가장 빨랐습니다(비교). - Compose 스택: 에이전트의
compose도구는 Manage 수준에서 프로젝트를 올리고 내립니다. Apple Silicon에서 Docker Compose 사용을 확인하세요.
자주 묻는 질문
Mac의 Docker 컨테이너용 MCP 서버가 있나요?
네. Oxcart에 포함된 oxcart mcp는 상태, 진단, 로그, 포트, 이미지, exec, Compose, 빌드, 샌드박스, 정리를 위한 도구 13개를 제공하는 로컬 stdio MCP 서버입니다. 네트워크 포트를 열지 않으며 토큰도 필요하지 않습니다.
Claude Code를 Docker 컨테이너에 어떻게 연결하나요?
Oxcart의 설정 문장을 Claude Code에 붙여넣거나 claude mcp add -s user oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client claude-code를 실행하세요. 그러면 Claude Code가 oxcart 서버를 표시하고 도구를 호출할 수 있습니다.
Codex, Cursor, Copilot을 사용하는 VS Code에서도 작동하나요?
Oxcart는 Codex, Cursor, Copilot을 사용하는 VS Code, Claude Desktop, Zed, Gemini CLI, GitHub Copilot CLI, Cline, Goose, Kiro, Amp, Warp, LM Studio를 포함해 이름이 명시된 클라이언트 18개의 설정 절차와 그 외 MCP 클라이언트용 일반 절차를 제공합니다. 처음부터 끝까지 실행해 확인한 클라이언트는 Claude Code입니다.
에이전트가 컨테이너나 볼륨을 삭제할 수 있나요?
기본적으로는 불가능합니다. 모든 에이전트는 읽기 전용으로 시작하며 개별적으로 Manage나 Full로 높이거나 Block으로 설정할 수 있습니다. Full에서도 cleanup은 먼저 미리 보기와 토큰을 반환하고 미리 보기에 나온 항목만 삭제합니다. 권한 수준은 Oxcart 도구를 제어하며 샌드박스는 아닙니다. 셸 접근 권한이 있는 에이전트는 docker CLI를 직접 실행할 수 있습니다.
에이전트가 docker 명령을 직접 실행하게 하면 안 되나요?
가능하지만 에이전트가 많은 원시 출력을 읽어야 합니다. '이 컨테이너는 왜 중지되었나요?'에 답할 때 Oxcart의 diagnose 도구는 159토큰, docker inspect와 docker logs --tail 300는 2,014토큰을 사용해 13×의 축소 배율을 보였습니다. 작업별 Claude Code 세션 1회의 참고 결과에서 로그 오류를 찾는 시간은 31.0 s에서 4.2 s로 줄었습니다.
MCP 서버가 데이터를 외부로 보내나요?
아니요. 로컬 엔진 소켓과만 통신하며 자체 네트워크 연결을 만들지 않습니다. 모든 호출은 Mac의 활동 로그에 기록됩니다. 도구가 이미지를 필요로 하는 항목을 시작하거나 빌드할 때는 docker run처럼 레지스트리에서 이미지를 가져옵니다.
에이전트가 일회용 컨테이너에서 코드를 실행할 수 있나요?
네. sandbox 도구는 메모리 2 GiB와 프로세스 1,024개로 제한된 일회용 컨테이너를 제공합니다. 에이전트가 Full 수준에서 네트워크를 요청한 경우를 제외하면 네트워크가 없습니다.
출처와 측정 방법
- 응답 크기: 2026-10-10에 테스트 컨테이너 5개로 측정. 토큰 수는 문자 수 ÷ 4로 추정.
- 세션: Claude Code 2.1.296,
claude-opus-5-5, Oxcart 0.1.0. 작업과 조건별 1회 실행. - 속도 수치: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, CPU 8개 및 12 GiB. 비교 런타임은 같은 날 앞서 동일한 Mac과 테스트 하네스에서 docker 29.4 클라이언트로 측정했습니다.