STDIO Transport

STDIO Transport는 같은 머신에서 실행되는 두 프로세스 간 통신 방식으로, 운영체제가 제공하는 표준 입출력 스트림(stdin, stdout, stderr)을 통신 채널로 사용한다.

MCP Server에서는 로컬 서버의 기본 전송 방식으로 사용된다.

해당 개념이 필요한 이유

• MCP Server를 로컬에서 실행할 때 네트워크 설정 없이 바로 통신 가능
• 별도 포트 바인딩, HTTP 서버 구성이 불필요
• Claude Code, Claude Desktop 등 대부분의 MCP Host가 로컬 서버에 STDIO를 기본으로 사용

AS-IS

sequenceDiagram
    autonumber
    participant App as AI 앱
    participant Server as 외부 서버

    App->>Server: HTTP 요청 (포트 설정 필요)
    Server-->>App: HTTP 응답
    Note over App,Server: 포트 충돌, 방화벽, CORS 등<br/>네트워크 이슈 발생 가능

TO-BE

sequenceDiagram
    autonumber
    participant Host as Claude Code (부모)
    participant Server as MCP Server (자식)

    Host->>Server: spawn 프로세스
    Host->>Server: stdin에 JSON-RPC write
    Server-->>Host: stdout에 JSON-RPC write
    Server-->>Host: stderr에 디버그 로그
    Note over Host,Server: 네트워크 불필요<br/>OS 수준의 프로세스 통신

3개의 표준 스트림

스트림	파일 디스크립터	방향	MCP에서의 역할
stdin	fd 0	부모 → 자식	JSON-RPC 요청 수신
stdout	fd 1	자식 → 부모	JSON-RPC 응답 전송
stderr	fd 2	자식 → 부모	디버그 로그 출력

graph LR
    subgraph "부모 프로세스 (Claude Code)"
        W["stdin.write()"]
        R["stdout.read()"]
        L["stderr.read()"]
    end

    subgraph "자식 프로세스 (MCP Server)"
        SI["process.stdin"]
        SO["process.stdout"]
        SE["process.stderr"]
    end

    W -->|"JSON-RPC 요청"| SI
    SO -->|"JSON-RPC 응답"| R
    SE -->|"로그 메시지"| L

동작 원리

1. 프로세스 생성 (spawn)

MCP Host가 설정 파일의 command와 args로 자식 프로세스를 생성한다:

{
  "mcpServers": {
    "todo-server": {
      "command": "node",
      "args": ["/path/to/build/index.js"]
    }
  }
}

Host 내부에서 일어나는 일 (개념적 코드):

const child = child_process.spawn("node", ["/path/to/build/index.js"]);
// child.stdin  → 부모가 write (요청 전송)
// child.stdout → 부모가 read  (응답 수신)
// child.stderr → 부모가 read  (로그 수신)

2. 메시지 교환

stdin/stdout을 통해 줄바꿈으로 구분된 JSON-RPC 2.0 메시지를 주고받는다:

→ stdin:  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}\n
← stdout: {"jsonrpc":"2.0","id":1,"result":{...}}\n

3. 프로세스 종료

MCP Host가 연결을 끊으면 자식 프로세스의 stdin이 닫히고, 서버는 정상 종료된다.

console.log() 금지 규칙

STDIO 서버에서 가장 흔한 실수이자 가장 중요한 규칙:

// stdout은 JSON-RPC 전용 채널
 
console.log("hello");    // stdout → JSON-RPC 파싱 실패 → 서버 크래시
console.error("hello");  // stderr → 안전 (로그용)

왜 크래시가 발생하는가:

sequenceDiagram
    autonumber
    participant Host as MCP Host
    participant Server as MCP Server

    Server->>Host: stdout: "hello" (console.log)
    Host->>Host: JSON.parse("hello") 시도
    Host->>Host: SyntaxError 발생
    Host->>Host: 연결 종료 (프로토콜 위반)

언어별 안전한 로깅:

언어	금지	안전
TypeScript/Node.js	console.log()	console.error()
Python	print()	print(..., file=sys.stderr)
Java	System.out.println()	logger.info() (stderr 설정)
Rust	println!()	eprintln!()

STDIO vs Streamable HTTP

항목	STDIO	Streamable HTTP
실행 위치	로컬 전용	로컬 + 원격
연결 방식	프로세스 spawn	HTTP POST + SSE
클라이언트 수	1:1	1:N
네트워크 오버헤드	없음	있음
인증	불필요 (같은 머신)	OAuth, API Key 등
설정 복잡도	낮음	높음
적합한 경우	개인 개발 도구, 로컬 DB	SaaS 서비스, 팀 공유

참고 문서

• MCP Architecture - Transport Layer
• MCP Server Build Guide