SSE로 응답 스트리밍하기

도구에 따라 시간이 걸릴 수 있습니다. 예를 들어 검색이 오래 걸리거나 API 호출이 느릴 수 있습니다. 클라이언트가 아무 응답 없이 기다리게 하는 대신 서버는 진행되는 대로 업데이트를 스트리밍할 수 있습니다. ⏳

Streamable HTTP는 Server-Sent Events, 즉 SSE를 사용해 스트리밍합니다. SSE는 서버가 하나의 열린 연결을 통해 여러 메시지를 차례로 푸시하는 간단한 웹 기반 방식입니다.

SSE는 서버에서 클라이언트로 한 방향으로만 흐릅니다. 서버는 연결을 열린 상태로 유지하고 새로운 내용이 생길 때마다 이벤트를 클라이언트로 푸시합니다.

Content-Type을 보면 응답이 스트림인지 알 수 있습니다. 서버가 Content-Type을 text/event-stream으로 설정하면 클라이언트는 최종 본문 하나가 아니라 이벤트를 읽습니다.

각 SSE 이벤트는 단순한 텍스트입니다. data:로 시작하는 줄에 페이로드가 들어가고, 빈 줄이 하나의 이벤트가 끝났음을 표시한 뒤 다음 이벤트가 시작됩니다.

각 이벤트 안에는 익숙한 JSON-RPC 메시지가 들어 있습니다. 스트리밍은 새로운 형식을 만들지 않고, 동일한 메시지를 시간에 따라 전달할 뿐입니다.

스트리밍 응답은 먼저 진행 상황 알림을 보내고 마지막에 최종 결과를 보낼 수 있습니다. 사용자는 로딩 표시기만 바라보는 대신 도구가 작업 중임을 확인할 수 있습니다.

스트리밍은 선택 사항입니다. 빠른 도구라면 서버가 단일 JSON 응답만 반환하고 연결을 닫으면 되므로 이벤트 스트림이 전혀 필요하지 않습니다.

SSE를 사용하면 서버가 이벤트에 식별자를 붙일 수 있습니다. 이 작은 기능은 나중에 중요해집니다. 연결이 끊긴 뒤 클라이언트가 스트림을 재개할 수 있게 해 주기 때문입니다.

직접 원시 SSE를 작성하는 일은 거의 없습니다. MCP SDK가 이벤트 형식을 지정해 주므로, 진행 상황과 결과를 보내기만 하면 올바르게 스트리밍됩니다.

스트리밍은 도구가 반환하는 내용을 바꾸지 않고, 결과를 받는 느낌만 바꿉니다. 최종 답변은 동일하며 사용자는 더 매끄럽고 반응성 높은 경험을 하게 됩니다. ✨

서버는 응답이 실시간 스트림임을 어떻게 알릴까요?

SSE를 사용하면 서버가 하나의 열린 연결을 통해 JSON-RPC 이벤트를 클라이언트로 푸시할 수 있습니다. 먼저 진행 상황을 보내고 마지막에 결과를 보냅니다. 선택 사항이며 웹에 자연스럽게 통합되고, 느린 도구도 빠르게 느껴지게 합니다. 🎉