자체 MCP(Model Context Protocol) 서버를 stdio transport로 만들고 있습니다. Claude Code에 연결했더니 처음 몇 번 호출은 잘 되는데, 5~10분 사용 후 응답이 멈춰서 다시 안 옵니다.
서버 프로세스는 살아 있고 stderr에 에러도 안 찍힙니다. 재시작하면 또 잠시 동작합니다.
stdin/stdout 버퍼 문제 같은데 정확한 원인과 해결법이 궁금합니다.
자체 MCP(Model Context Protocol) 서버를 stdio transport로 만들고 있습니다. Claude Code에 연결했더니 처음 몇 번 호출은 잘 되는데, 5~10분 사용 후 응답이 멈춰서 다시 안 옵니다.
서버 프로세스는 살아 있고 stderr에 에러도 안 찍힙니다. 재시작하면 또 잠시 동작합니다.
stdin/stdout 버퍼 문제 같은데 정확한 원인과 해결법이 궁금합니다.
댓글 1
MCP stdio 서버에서 가장 흔한 deadlock입니다. 원인은 거의 항상 stdout 버퍼 + 동기 write 조합입니다.
핵심 메커니즘
Node.js의
process.stdout.write는 stdout이 파이프(터미널이 아닌)일 때 버퍼링됩니다. Claude Code가 부모 프로세스라 stdout은 파이프 모드입니다. 한편 클라이언트가 stdin으로 다음 메시지를 안 보내고 있는 동안 서버는 응답을 stdout에 썼다고 생각하지만 실제로는 OS 버퍼에 쌓이고 있습니다.버퍼가 차면 write가 backpressure를 일으키고, 잘못 처리하면 영영 안 풀립니다.
잘못된 패턴 (자주 보는 케이스):
올바른 패턴:
또 다른 흔한 함정 — JSON 한 줄 단위
MCP는 JSON-RPC 메시지를 newline으로 구분합니다. 응답 내부에 raw newline이 있으면 메시지 파싱이 어긋나면서 클라이언트가 다음 요청을 영영 안 보냅니다.
로깅을 stderr로 보내라
stdout은 MCP 프로토콜 전용입니다. 디버그 로그를 stdout에 찍으면 클라이언트 파서가 깨집니다.
stdin 끝 처리
실무 체크리스트:
process.on('SIGPIPE', () => process.exit(0))setImmediate로 yield해서 read 채널 막지 않기참고로 HTTP transport는 이런 버퍼 이슈가 없습니다. MCP 서버 검증을 빠르게 하고 싶으면 stdio 대신 HTTP로 띄워서 디버깅하는 것도 방법입니다.