본문 바로가기
Q&A해결2026년 4월 21일1분 읽기

Claude Code MCP 서버에서 stdin 응답이 멈추는 현상

M
MCP개발자
조회 807댓글 1

자체 MCP(Model Context Protocol) 서버를 stdio transport로 만들고 있습니다. Claude Code에 연결했더니 처음 몇 번 호출은 잘 되는데, 5~10분 사용 후 응답이 멈춰서 다시 안 옵니다.

서버 프로세스는 살아 있고 stderr에 에러도 안 찍힙니다. 재시작하면 또 잠시 동작합니다.

stdin/stdout 버퍼 문제 같은데 정확한 원인과 해결법이 궁금합니다.

댓글 1

김김영삼7개월 전

MCP stdio 서버에서 가장 흔한 deadlock입니다. 원인은 거의 항상 stdout 버퍼 + 동기 write 조합입니다.

핵심 메커니즘

Node.js의 process.stdout.write는 stdout이 파이프(터미널이 아닌)일 때 버퍼링됩니다. Claude Code가 부모 프로세스라 stdout은 파이프 모드입니다. 한편 클라이언트가 stdin으로 다음 메시지를 안 보내고 있는 동안 서버는 응답을 stdout에 썼다고 생각하지만 실제로는 OS 버퍼에 쌓이고 있습니다.

버퍼가 차면 write가 backpressure를 일으키고, 잘못 처리하면 영영 안 풀립니다.

잘못된 패턴 (자주 보는 케이스):

// stdout 버퍼 안 비워짐
process.stdout.write(JSON.stringify(response) + '\n')
// 다음 요청 처리로 바로 넘어감

올바른 패턴:

function send(payload) {
return new Promise((resolve, reject) => {
const data = JSON.stringify(payload) + '\n'
if (!process.stdout.write(data)) {
// backpressure — drain 이벤트 대기
process.stdout.once('drain', resolve)
} else {
resolve()
}
})
}

// 사용
await send(response) // 다음 처리 전 반드시 await

또 다른 흔한 함정 — JSON 한 줄 단위

MCP는 JSON-RPC 메시지를 newline으로 구분합니다. 응답 내부에 raw newline이 있으면 메시지 파싱이 어긋나면서 클라이언트가 다음 요청을 영영 안 보냅니다.

// JSON.stringify에 두 번째 인자 절대 넣지 말기
JSON.stringify(obj) // OK
JSON.stringify(obj, null, 2) // 멈춤! (newline 포함됨)

로깅을 stderr로 보내라

stdout은 MCP 프로토콜 전용입니다. 디버그 로그를 stdout에 찍으면 클라이언트 파서가 깨집니다.

// console.log는 stdout — 절대 사용 금지
console.error('debug:', x) // stderr는 안전

stdin 끝 처리

process.stdin.setEncoding('utf8')
let buf = ''
process.stdin.on('data', (chunk) => {
buf += chunk
let idx
while ((idx = buf.indexOf('\n')) >= 0) {
const line = buf.slice(0, idx)
buf = buf.slice(idx + 1)
if (line.trim()) handleMessage(JSON.parse(line))
}
})
process.stdin.on('end', () => process.exit(0))

실무 체크리스트:

  1. stdout write에 backpressure 처리 (drain 이벤트)
  2. JSON.stringify에 indent 인자 금지
  3. 로깅은 stderr만 사용 (console.log 절대 금지)
  4. stdin은 buffer + newline split (chunk 분할 가정)
  5. SIGPIPE 핸들러 — process.on('SIGPIPE', () => process.exit(0))
  6. 긴 작업은 setImmediate로 yield해서 read 채널 막지 않기

참고로 HTTP transport는 이런 버퍼 이슈가 없습니다. MCP 서버 검증을 빠르게 하고 싶으면 stdio 대신 HTTP로 띄워서 디버깅하는 것도 방법입니다.

Ctrl+Enter로 등록