Claude Code를 REST API로 감싸기: 세션, 스트리밍, MCP

Claude Code API화 핵심 의사결정

• Claude Code의 강력한 에이전트 기능을 웹 환경에서 활용하기 위해 REST API로 래핑.
• AI SDK와의 호환성을 최우선으로 고려하여 기존 인터페이스 재사용.
• 주요 결정은 세션 관리, 스트림 처리, 도구 연결 세 가지. 주요 기술적 해결 방안
• 세션 관리: API 메시지 배열을 JSONL 파일로 변환하여 로컬에 저장하고, SDK의 resume 옵션으로 이전 대화 맥락 복원.
• 스트리밍 응답: SDK의 AsyncIterable 이벤트를 텍스트/추론/완료 스트림으로 분리하여 클라이언트가 선택적으로 구독.
• MCP 도구 브릿지: 기존 AI SDK 도구를 **createSdkMcpServer()**를 통해 MCP 서버로 변환하여 Claude Code와 연동. 운영 및 트러블슈팅
• 도구 컨텍스트 메시지 처리: 마지막 메시지가 'user' 역할이어야 하는 SDK 제약을 해결하기 위해 메시지 병합 로직 구현.
• 안전장치: disallowedTools 및 maxTurns 설정으로 위험한 도구 차단 및 무한 루프 방지.
• Docker 배포: 컨테이너 환경에서 Claude Code CLI 설치 및 실행 파일 경로 설정 필요.