MCP 서버를 stdio로 붙이면 서버 프로세스의 stdout은 사람이 보는 화면이 아니라 클라이언트가 응답을 읽어 가는 통로가 됩니다. 디버깅하려고 넣은 console.log 한 줄도 그 통로로 나갑니다. Node.js만으로 만든 작은 서버와 클라이언트로 정상 응답, console.log 한 줄, 들여쓴 JSON, console.error로 고친 경우를 차례로 돌려 보았습니다. 다 읽고 나면 내 서버 코드에서 무엇을 찾아 고쳐야 하는지, 고친 뒤 무엇으로 확인하면 되는지 알 수 있습니다.
stdio 전송에서 stdout은 메시지 통로입니다
stdio 전송에서는 클라이언트가 MCP 서버를 하위 프로세스로 띄웁니다. 클라이언트는 서버의 stdin에 요청을 쓰고, 서버는 stdout에 응답을 씁니다. 응답과 알림이 모두 이 한 통로를 지나가고, 요청마다 따로 열리는 통로는 없습니다.
MCP 사양 2026-07-28판의 stdio 전송 페이지는 이 통로에 몇 가지 규칙을 둡니다.
- 메시지 하나는 JSON-RPC 요청, 알림, 응답 가운데 하나이고, 메시지끼리는 줄바꿈으로 구분합니다. 메시지 안에는 줄바꿈이 들어가면 안 됩니다(MUST NOT).
- 서버는 유효한 MCP 메시지가 아닌 것을 stdout에 쓰면 안 됩니다(MUST NOT). 클라이언트도 서버의 stdin에 MCP 메시지가 아닌 것을 쓰면 안 됩니다.
- 서버는 정보, 디버그, 오류 같은 로그를 UTF-8 문자열로 stderr에 써도 됩니다(MAY). 클라이언트는 stderr를 받아 두거나 다른 곳으로 넘기거나 무시할 수 있고, stderr에 무언가 나왔다고 오류로 여기지 않아야 합니다(SHOULD NOT).
Node.js의 전역 console은 process.stdout과 process.stderr에 쓰도록 만들어져 있고, console.log는 그 가운데 stdout에 씁니다. 그래서 MCP 서버 안의 console.log는 규칙이 말하는 「MCP 메시지가 아닌 것」을 메시지 통로에 섞습니다. 서버 코드가 직접 부르지 않아도, 같은 프로세스에서 도는 다른 모듈이 console.log를 부르면 같은 stdout으로 나갑니다.
개발 노트
stdio 전송의 세 통로
클라이언트가 서버를 하위 프로세스로 띄우고 표준 스트림으로 주고받는다
stdin: 클라이언트 → 서버
{"jsonrpc":"2.0","id":2,…}- JSON-RPC 요청과 알림, 한 줄에 하나
- MCP 메시지가 아닌 것 금지(MUST NOT)
- 클라이언트는 응답을 쓰지 않는다
stdout: 서버 → 클라이언트, 메시지만
JSON.stringify(msg) + '\n'- 응답과 알림만, 한 줄에 하나
- 메시지 안 줄바꿈 금지(MUST NOT)
- MCP 메시지가 아닌 것 금지(MUST NOT)
- console.log·info·debug가 여기로
stderr: 서버의 로그
console.error('got request', …)- 로그를 UTF-8 문자열로 써도 된다(MAY)
- 클라이언트는 보관·전달·무시 가능(MAY)
- 오류 신호로 보지 않는다(SHOULD NOT)
- console.error·warn이 여기로
규칙은 MCP 사양 2026-07-28판 stdio 전송 페이지 기준이다(2026-11-09 확인). console 메서드의 통로는 Node.js v24.21.0에서 돌려 확인했다.
Node.js만으로 서버와 클라이언트를 만들어 돌렸습니다
실험에는 SDK를 쓰지 않았습니다. 통로에서 일어나는 일만 보려고 두 파일을 직접 썼습니다.
server.mjs: stdin을 줄 단위로 읽어tools/list와tools/call(덧셈 도구add)에 답합니다. 두 응답의result에는 2026-07-28판이 모든 결과에 요구하는resultType을 넣었고, 나머지 모양은 사양 tools 페이지의 예를 줄여 따랐습니다.server/discover,_meta검사, 능력 선언은 넣지 않았으니 완전한 MCP 서버가 아니라 통로를 보기 위한 데모입니다. 실행 인자로 네 가지 모드를 고릅니다.client.mjs: 서버를 하위 프로세스로 띄우고 요청 두 개(id 1tools/list, id 2tools/call)를 한 줄씩 stdin에 씁니다. stdout은 줄바꿈마다 잘라JSON.parse하고, 읽힌 메시지의 id를 보낸 요청과 맞춥니다. stderr는 앞에stderr:를 붙여 따로 찍습니다. 1초 뒤 서버의 stdin을 닫고, 맞춘 응답 수와 파싱 오류 수를 셉니다.
네 모드는 이렇습니다. ok는 응답을 JSON.stringify(msg)로 한 줄씩 쓰고, log는 응답 전에 console.log('got request', req.method)를 한 줄 찍습니다. pretty는 응답을 JSON.stringify(msg, null, 2)로 들여 쓰고, stderr는 log와 같은 줄을 console.error로 찍습니다. 2026년 11월 9일 macOS 27.0.1, Node.js v24.21.0에서 돌렸고 패키지는 설치하지 않았습니다.

console.log 한 줄: 응답 사이에 JSON이 아닌 줄이 끼었습니다
log 모드에서 클라이언트가 받은 stdout은 네 줄이었습니다. 1번째와 3번째 줄이 got request tools/list, got request tools/call이었고, JSON.parse는 Unexpected token 'g'로 실패했습니다. 이 데모 클라이언트는 읽히지 않는 줄을 건너뛰고 다음 줄을 읽도록 짰기 때문에 응답 두 개는 제대로 맞췄습니다.
건너뛸지 멈출지는 클라이언트가 정합니다. 같은 클라이언트를 첫 잘못된 줄에서 읽기를 멈추고 서버를 끝내도록 바꿔(--strict) 돌리자, 그 뒤에 온 줄은 응답이어도 처리하지 않아 응답을 하나도 맞추지 못했습니다(0/2). 실제 클라이언트인 Claude Code, Claude Desktop, 공식 SDK가 이런 줄을 만나 무엇을 하는지는 확인하지 않았습니다. Claude Code와 Claude Desktop은 설정을 바꿔야 하고 공식 SDK는 패키지를 설치해야 해서 이 실험에서는 뺐습니다. 어느 쪽이든 서버는 사양이 금지한 일을 한 것이고, 그 결과는 클라이언트가 그런 줄을 어떻게 다루느냐에 달려 있습니다.
들여쓴 JSON: 응답 하나가 여러 줄로 쪼개졌습니다
pretty 모드에서는 로그를 한 줄도 찍지 않았는데 결과가 더 나빴습니다. 응답 두 개가 stdout 42줄로 나뉘었고, 클라이언트는 41줄에서 파싱 오류를 냈습니다. { 한 글자만 있는 줄이나 "jsonrpc": "2.0",처럼 쉼표로 끝나는 줄은 그 자체로 JSON이 아니기 때문입니다. 두 응답은 모두 도착했지만 조각으로 쪼개져 id 1과 2 어느 쪽에도 맞춰지지 않았습니다(0/2).
22번째 줄은 파싱에 성공했습니다. 도구 목록의 "required": ["a", "b"] 배열에서 마지막 원소 "b"가 한 줄에 혼자 놓였고, 이것은 JSON 문자열로는 맞는 값입니다. 쪼개진 조각이 우연히 JSON이 되어도 메시지는 아닙니다. 이 데모 클라이언트는 jsonrpc와 id를 따로 확인하기 때문에 이 줄을 응답으로 받아들이지 않았습니다.
문자열 안에 줄바꿈이 든 응답은 걱정하지 않아도 됩니다. 덧셈 도구의 결과 텍스트에는 줄바꿈이 들어 있는데, 들여쓰기 인자 없이 JSON.stringify(msg)로 쓰면 그 줄바꿈이 \n 두 글자로 이스케이프되어 메시지 전체가 한 줄로 나왔습니다. 같은 응답을 JSON.stringify(msg, null, 2)로 쓰면 14줄이었습니다. 사양 문서의 예시 메시지는 여러 줄로 펼쳐져 있지만, stdio 통로에는 한 줄로 실어야 합니다.
![터미널 실행 결과. node client.mjs log --strict는 stdout line 1의 parse error 뒤 strict: closing the connection을 찍고 replies matched 0/2, parse errors 1, no reply for id 1, 2. tools/call 요청 한 줄을 echo로 node server.mjs ok에 넣으면 {"jsonrpc":"2.0","id":2,"result":{"resultType":"complete","content":[{"type":"text","text":"sum: 5\ninputs: 2, 3"}],"isError":false}} 한 줄이 나온다. 같은 요청을 node server.mjs pretty에 넣고 wc -l로 세면 14. node console-streams.mjs 2>/dev/null은 log, info, debug를, node console-streams.mjs >/dev/null은 warn, error를 찍는다.](/images/ko/mcp-stdio-stdout-log-run-02.png)
로그는 stderr로: console.error로 바꾼 결과
stderr 모드에서는 같은 로그 두 줄이 stderr:로 따로 들어왔고, stdout에는 응답 두 줄만 남았습니다. 파싱 오류는 0개였습니다. 두 통로는 따로 흐르기 때문에 11월 9일 실행에서는 stderr 줄이 stdout 줄보다 먼저 찍혔습니다. 나중에 로그와 응답을 맞춰 보려면 로그에 요청 id를 함께 남기는 편이 낫습니다.
console.log만 피한다고 끝나지는 않습니다. Node.js에서 console.info와 console.debug는 console.log의 별칭이라 stdout으로 가고, console.warn은 console.error의 별칭이라 stderr로 갑니다. 실제로 stderr를 버리고 돌리자 log, info, debug가 남았고, stdout을 버리고 돌리자 warn, error가 남았습니다.
별칭이 아닌 메서드도 있습니다. 같은 방법으로 돌려 보니 console.dir, console.count, console.timeEnd, console.group의 라벨, console.table도 stdout에 썼고, 함께 돌린 메서드 가운데 stderr로 간 것은 실패한 console.assert의 메시지와 console.trace뿐이었습니다. Node.js v24 문서도 console.dir, console.count, console.timeEnd, console.timeLog는 stdout에, console.trace는 stderr에 쓴다고 적습니다.
MCP에는 서버가 notifications/message 알림으로 클라이언트에 로그를 보내는 Logging 기능도 있습니다. 이 알림은 MCP 메시지라 stdout으로 보내도 stdio 규칙에는 어긋나지 않지만, 아무 때나 보낼 수 있는 것은 아닙니다. 같은 판의 Logging 페이지는 요청의 _meta에 io.modelcontextprotocol/logLevel이 없으면 그 요청에 이 알림을 보내지 말라고(MUST NOT) 적습니다. 이 기능은 2026-07-28판에서 사용 중단(deprecated)으로 표시되기도 했습니다. 새 구현은 이 기능을 쓰지 않아야 하고(SHOULD NOT), 이미 쓰는 구현은 stdio라면 stderr 로깅으로, 구조화된 관측이 필요하면 OpenTelemetry로 옮겨야 한다고(SHOULD) 적혀 있습니다.
내 서버에서 찾아 고칠 것
- stdout에 쓰는 곳을 한 곳으로 모읍니다. 메시지를 보내는 함수 하나만
process.stdout.write(JSON.stringify(msg) + '\n')를 부르고, 들여쓰기 인자는 넘기지 않습니다. - 코드에서
console.log,console.info,console.debug,console.dir,console.dirxml,console.table,console.count,console.timeEnd,console.timeLog,console.group,console.groupCollapsed, 그리고 그 함수 밖의process.stdout.write를 찾아console.error나 stderr로 바꿉니다. - 고친 뒤에는 서버가 답하는 요청 한 줄을 넣고 stderr를 버린 채 stdout을 봅니다. 줄마다
JSON.parse가 되고"jsonrpc": "2.0"을 단 메시지여야 하며, 응답과 알림 말고 다른 줄은 없어야 합니다.
이 글의 규칙은 MCP 사양 2026-07-28판 기준이고, 이전 판의 문구는 이 글을 쓰며 다시 확인하지 않았습니다. 실행 결과는 직접 만든 데모 클라이언트의 동작입니다. stdio로 붙인 MCP 서버라면 stdout에 쓰는 코드는 메시지를 보내는 한 곳만 남기고, 나머지 출력은 모두 stderr로 보내면 됩니다.
이 기록에 대화를 더해 주세요.
궁금한 점, 다른 접근, 직접 해 본 결과를 나눠 주세요.
로그인 상태 확인 중…
댓글을 불러오는 중…