로컬 STDIO에서는 잘 작동하던 것이 HTTP로 옮기니 고장 났을까? 아마도 두 가지 설정 때문일 가능성이 높습니다.

이 글은 Anthropic Academy의 《Model Context Protocol: Advanced Topics》 제11과 실습 교육 내용입니다. 원제는 《The StreamableHTTP transport (StreamableHTTP 전송)》를 직역한 것입니다. 결론부터 말씀드리겠습니다. 이 내용은 다소 반직관적입니다:

StreamableHTTP는 클라이언트가 HTTP를 통해 원격 서버에 연결하는 방식이며, 공개 서버에 적합합니다. 하지만 두 가지 핵심 설정이 강제로 true로 지정되면 기능이 현저하게 제한됩니다. 즉, 로컬 STDIO에서는 잘 작동하던 것이 HTTP 환경으로 배포되면서 고장 난 것처럼 보이지만, 이는 대부분 코드가 아닌 '설정'의 문제입니다.

먼저 용어를 명확히 하겠습니다. **StreamableHTTP(스트리밍 가능한 HTTP)**는 MCP 클라이언트가 HTTP를 통해 원격 서버에 연결하는 전송 방식입니다. **stateless_http(무상태 HTTP)**는 연결 상태 관리 방식을 제어하는 설정입니다. **json_response(JSON 응답)**는 응답 형식 처리 방식을 제어하는 설정입니다. **서버 주도 요청(server-initiated request)**이란 서버가 능동적으로 클라이언트에게 보내는 요청을 말하며, 예를 들어 샘플링이나 권한 디렉토리 목록 조회 등이 있습니다.

실제 예시를 들자면 이렇습니다. 로컬 STDIO 환경에서 잘 돌아가던 애플리케이션에 진행률 표시줄(progress bar)이 있고, 로그 기록 기능이 있으며, 서버 주도 샘플링 요청이 포함되어 있다고 가정해 봅시다. 이것을 HTTP 환경으로 배포하면 진행률 표시줄은 사라지고, 로그는 멈추며, 샘플링 요청마저 실패합니다. 코드는 단 한 줄도 수정하지 않았는데, 모든 것이 설정에 의해 제한받아 작동하지 않는 것입니다.

그들은 우리가 흔히 접하는 '오래된 경로'를 지적했습니다. 마치 전송 방식만 바꾼다고 해서 기능이 그대로 유지될 것처럼 생각하지만, 공식적인 분석은 매우 직설적입니다: HTTP에는 선천적인 제약이 있습니다. 클라이언트는 서버가 알려준 URL을 통해 쉽게 요청을 보낼 수 있고, 서버도 응답하기 쉽습니다. 하지만 서버가 능동적으로 클라이언트에게 요청을 보내기는 어렵습니다. 왜냐하면 클라이언트는 미리 알고 있는 URL이 없기 때문입니다. 또한, 클라이언트가 서버로 응답하는 패턴 역시 문제가 됩니다.

모든 것을 말씀드리자면: 모든 기능이 HTTP 환경에서 고장 나는 것은 아닙니다. 다음 중 어느 하나라도 기능을 사용하는 경우에만 제한적인 설정의 영향을 받게 됩니다:

• 서버가 클라이언트로 요청을 보내는 기능 (예: 샘플링, 권한 디렉토리 목록 조회);
• 알림(Notification)이 필요한 기능 (예: 진행률, 로그, 초기화 확인, 취소);
• 배포 환경상 stateless_http 또는 json_response를 true로 설정해야 하는 경우.

1. HTTP 환경에서만 문제가 되는 세 가지 실패 방식

• 진행률 표시줄 사라짐: 진행 알림이 원활하지 않아 사용자가 무작정 기다리는 상태가 됩니다.
• 로그 중단: 로그 알림이 끊기면서, 장시간 작업 중에 무슨 일이 일어났는지 아무도 모르게 됩니다.
• 서버 주도 요청 실패: 샘플링 요청을 보낼 수 없게 되어, 서버가 텍스트를 생성하는 기능 자체가 마비됩니다.

2. 대안: 두 설정을 기본값 false로 두고, 그 비용을 이해한 후 활성화하기

두 핵심 설정인 stateless_http와 json_response는 기본적으로 모두 false입니다. 이 기본 상태에서는 StreamableHTTP가 HTTP의 제한을 우회할 수 있는 영리한 방법을 가지고 있어 기능이 대체로 유지됩니다. 하지만 특정 배포 환경에서 이를 true로 강제 설정하면, 이는 곧 HTTP 제약 내에서 작동하며 우회하는 방식을 포기한다는 의미와 같습니다. 활성화하기 전에 명확히 생각해야 합니다: 이 상황이 정말로 반드시 필요합니까? 그리고 만약 활성화한다면, 어떤 기능들이 축소되어야 합니까?

3. 목표 형태: 선택 전 우선순위를 명확히 하기

이상적인 상태는 전송 방식을 선택할 때부터 트레이드오프(trade-off)를 생각하는 것입니다. 어떤 배포 환경에서 어떤 전송 방식을 사용할지, 서버가 HTTP 제약을 우아하게 처리하도록 어떻게 설계할지, 그리고 언제 원격 호스팅의 이점을 위해 기능 축소를 받아들일지를 결정해야 합니다. 우선순위는 상용화(on-line) 후에 발견하는 것이 아니라, 선택 단계에서부터 종이에 적어두어야 하는 것입니다.

4. 전환 3단계: STDIO에서 HTTP로 옮길 때, 기능 목록을 먼저 확인하기

첫 번째 단계: 서버 주도 기능을 나열하기

샘플링, 권한 디렉토리 목록 조회, 진행률, 로그 등 서버가 능동적으로 말을 해야 하는 모든 기능을 빠짐없이 나열해야 합니다.

두 번째 단계: 배포 환경이 제한적 설정을 강제하는지 확인하기

환경이 강요하지 않는다면 두 설정은 기본값 false로 유지합니다. 만약 환경이 강요한다면, 축소될 기능 목록을 사용자에게 먼저 알려야 합니다.

세 번째 단계: 상용화 전에 HTTP와 동일한 설정을 사용하여 테스트하기

로컬 STDIO만 테스트해서는 안 됩니다. 배포에 사용할 설정으로 반드시 전체 과정을 한 번 완벽하게 실행해 봐야 합니다.

5. 팀이 같은 선택 습관을 구축하는 방법

전송 방식 선택의 가장 큰 함정은 기술 자체가 아니라 '설정'입니다. 배포 담당자가 제한적인 설정을 활성화했는데, 개발 담당자는 모든 기능이 정상 작동한다고 착각할 수 있습니다. 팀은 세 가지 규칙을 먼저 정해야 합니다: 두 설정 값은 배포 명세서에 기재하고 변경 시에는 심사를 거쳐야 합니다; 기능 축소 목록은 설정과 함께 전달되어야 하며, 설정만 전달해서는 안 됩니다; 상용화 전에 반드시 배포 환경과 동일한 설정으로 테스트를 진행해야 하며, 기본 설정을 사용해 테스트해서는 안 됩니다.

6. 공식 도구 키트 외에 기억해야 할 것들

이번 강의에서는 완벽한 도구 상자를 제공하지 않았지만, 경계(boundary)를 매우 명확하게 설명했습니다. StreamableHTTP는 공개 서버에 적합하며 이것이 그 가치입니다. 하지만 이 가치는 공짜가 아니며, 제한적인 설정 자체가 대가입니다. 다음 강의에서는 HTTP 제약을 우회하는 구체적인 방법을 다룰 것이고, 왜 그 두 가지 설정이 우회 방식을 망가뜨리는지도 설명할 것입니다.

결론: 원칙이 구조보다 중요하다

전송 방식은 주소가 아니라 '선택과 포기'입니다. 원칙이 구조보다 중요합니다. 어떤 기능들은 절대로 축소될 수 없는지 먼저 생각한 다음, 설정을 열지 말지를 결정해야 합니다. 순서가 바뀌면, 고장 난 것은 항상 상용화 후에야 발견됩니다.

반복 가능한 행동 규칙은 다음과 같습니다: 다음에 애플리케이션을 HTTP로 배포할 때는 세 가지 질문을 먼저 해야 합니다—서버가 시작하는 기능에 의존하는지, 제한적 설정이 반드시 활성화되어야 하는지, 동일한 설정을 배포 환경에서 테스트했는지—이 세 가지 질문 모두 답할 수 있을 때만 온라인 서비스가 가능합니다.

원문 링크: https://t.co/mLgqaNisz4
원문: Anthropic Academy (S1哥 편집)

S1哥의 관점

이 글에서 가장 강력한 부분은, 많은 사람들이 가진 '전송 방식만 바꾼 것이지 주소가 바뀐 것뿐'이라는 환상을 산산조각 낸다는 점입니다. 과거에는 코드를 수정하지 않으면 기능이 고장 나지 않을 거라고 생각했지만, 이제 공식적으로는 두 가지 설정만으로도 진행 상황(progress), 로그(log), 샘플링(sampling)이 모두 사라질 수 있다고 말합니다. 진정으로 값비싼 것은 몇 줄의 설정 코드(configuration code)를 추가하는 것이 아니라, 로컬 경험에 기반하여 전체 시스템을 배포한 후, 기능이 설정 변경으로 인해 조용히 저하된 것을 발견하는 것입니다.

저는 이 입장에 서 있습니다: 설정을 기능처럼 다뤄야 합니다. 제한적 설정을 변경했지만, 그로 인해 기능이 저하되었다는 사실을 누구에게도 알리지 않은 배포는 '모르겠다'고 말하는 것보다 더 위험합니다. 전자는 독자들에게 '기능은 모두 정상이다'라는 착각을 심어주고 온라인 서비스에 투입하게 만들지만, 후자는 적어도 멈춰 서서 생각할 시간을 벌어줍니다.

그러니 질문합니다: 현재의 HTTP 배포 환경에서, 활성화되어 있지만 그로 인해 기능이 저하되었다는 사실을 아무도 모르는 제한적 설정은 몇 개나 있습니까? 댓글 창에 숫자를 보고해 주세요. 솔직하게 말할 수 있겠습니까?