이 게시물은 Claude Code CLI를 웹/외부 시스템에서 호출할 수 있도록 AI SDK 호환 REST API로 감싸는 설계와 구현 이슈를 정리합니다.

핵심 의사결정

• 세션 기반 메모리: HTTP로 받은 CoreMessage 배열을 Claude Code 세션(JSONL)로 변환해 로컬(~/.claude/projects/)에 저장하고, SDK의

  resume

  옵션으로 맥락을 복원합니다.
• 스트리밍 처리: SDK가 반환하는 혼합 이벤트(텍스트/추론/결과)를 파싱해 textStream·reasoningStream·completion으로 분리하고 SSE로 전달해 클라이언트 파싱 복잡도를 낮춥니다.
• MCP 도구 브릿지: 기존 Vercel AI SDK 도구들을 createSdkMcpServer()로 MCP 서버로 변환해 Claude Code 도구 호출에 연결하며, mcp__{server}__{tool} 네이밍 규칙을 프롬프트에 명시합니다.

트러블슈팅 및 운영

• 마지막 메시지가 user여야 하는 제약 때문에 tool로 끝나는 시퀀스를 병합/치환해 입력을 정규화하고, 통합 테스트로 resume·도구 호출을 검증합니다.
• REST API는 SSE 스트리밍/동기 JSON 모드를 제공하며, includeTools 옵션과 disallowedTools·maxTurns·Docker 설치/경로 설정 등 운영 안전장치를 다룹니다.