Claude Code를 REST API로 감싸기: 세션, 스트리밍, MCP
AI
Claude Code를 REST API로 감싸기: 세션, 스트리밍, MCP
두줄요약
Claude Code를 REST API로 감싸 세션 복원, 스트리밍 분리, MCP 도구 연동 구조를 정리했습니다. 기존 AI SDK 도구를 재사용하면서 웹 환경에서 에이전트를 운영하는 방법을 공유했습니다.
구조와 흐름
- Claude Code CLI를 웹/외부 시스템에서 쓰기 위한 REST API 래핑 구조
- 세션 복원, 스트리밍 분리, MCP 도구 브릿지를 핵심 설계로 선택
- 기존 Vercel AI SDK 인터페이스와의 호환성 유지에 초점
선택 이유
- AI SDK 기반 기존 코드베이스를 그대로 재사용하기 위한 인터페이스 정합성 확보
- 메시지 배열, 스트림 이벤트, 도구 형식의 차이를 API 계층에서 흡수
- Claude Code의 에이전트 기능을 웹 환경으로 확장하기 위한 구조 필요
트레이드오프
- 세션 저장을 로컬 JSONL 파일에 의존하는 CLI 구현 세부사항 종속성
- 도구 이름 접두사 매핑과 시스템 프롬프트 규칙 추가 필요
- 강력한 파일/쉘 도구 사용을 위한 명시적 차단과 운영 제어 필요
성능/운영 포인트
- text, reasoning, completion 이벤트를 분리한 AsyncIterable 스트리밍
- disallowedTools와 maxTurns로 위험 동작과 무한 루프 제한
- Docker 배포 시 CLI 설치 경로와 실행 파일 경로 환경별 처리