stdio Transport

MCP transport 중 제일 단순한 건 stdio 야. Host 가 server 를 자식 프로세스로 띄우고, 그 자식의 stdin/stdout pipe 로 JSON-RPC 메시지를 주고받아. 네트워크도 없고, port 도 없고, TLS 도 없어. Server 의 수명은 host 가 쥐고 있어서, host 가 꺼지면 자식 프로세스도 같이 꺼져.

Stdio 의 메시지 구분은 줄 단위 JSON 이야. JSON-RPC 메시지 하나가 정확히 한 줄이고 개행으로 끝나. Server 는 stdout 에 그 외의 어떤 것도 찍으면 안 돼 — 진단도, log 도, 경고도 전부 stderr 로 보내야 해. Server 코드 어딘가에 떠도는 print() 하나가 stream 을 망가뜨리고 host 를 멈춰 세워. MCP server 를 처음 짜는 사람이 가장 자주 만나는 사고가 바로 이거야.

Stdio 는 개인 도구에 어울려. 계산기 server, 개인 노트 server, 내 파일을 맡기는 로컬 filesystem server. 비용 모델은 'user 가 설치하는 만큼' 이야. 설치 자체가 신뢰를 주는 사건이고, 설치된 뒤에는 user 권한으로 살아가는 거지.

반대로 공유 서비스에는 안 맞아. Stdio server 는 애초에 네트워크 protocol 이 없으니 '망에 올린다' 는 게 성립하지 않아. 규모도 못 키워 — client 마다 자기 몫의 자식 프로세스를 하나씩 띄우니까. Server 하나로 여러 user 를 받쳐야겠다 싶은 순간이 Streamable HTTP 로 졸업할 때야.

Code

Stdio server 연결 (Python client)·python

from mcp.client.stdio import StdioServerParameters, stdio_client
from mcp.client.session import ClientSession

params = StdioServerParameters(command="uvx", args=["my-cool-server"])
async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print(tools)

흔한 stdio gotcha — print() 가 stream 손상·python

# 잘못 — stdout 오염
@app.tool()
def add(a: int, b: int) -> int:
    print(f"Adding {a} + {b}")  # stdout 새서 host 가 garbage 봄
    return a + b

# 맞음 — diagnostic 은 stderr (또는 log 파일) 로
import sys
@app.tool()
def add(a: int, b: int) -> int:
    print(f"Adding {a} + {b}", file=sys.stderr)
    return a + b

Exercise

커뮤니티 MCP server 아무거나 stdio 로 띄우고, tool 하나 안에 stdout 으로 나가는 잘못된 print() 를 한 줄 넣어봐. Client 가 멈추거나 parse 에러를 뱉는 걸 확인해. 그 다음 그 줄을 stderr 로 옮기고 전부 멀쩡해지는 걸 봐. Stdout 이 얼마나 약한지는 한 번만 배우면 돼.

Code

External links

Exercise

Progress

댓글 0