stdio Transport

가장 단순한 MCP transport 는 stdio: host 가 server 를 subprocess 로 띄우고 자식의 stdin/stdout pipe 로 JSON-RPC 메시지 교환. 네트워크 없음, port 없음, TLS 없음. Host lifecycle 이 server 소유; host 종료 시 subprocess 도 같이.

Stdio 의 framing 은 line-delimited JSON: 각 JSON-RPC 메시지가 정확히 한 줄 — newline 으로 종결. Server 는 stdout 에 다른 거 MUST NOT print — diagnostic, log, 경고 다 stderr 로. Server 코드의 떠도는 print() 가 stream 손상시키고 host hang. 이게 새 MCP server 작가가 가장 자주 만나는 단일 bug 야.

Stdio 가 개인 도구에 맞아: 계산기 server, 개인 노트 server, 파일 맡기는 로컬 filesystem server. 모델은 'user 가 install 하는 만큼 비용 지불' — install 이 trust 사건, install 후엔 user 권한 레벨에서 살아.

Stdio 가 공유 서비스엔 안 맞음. Stdio server 를 'network 에' 못 둠 — network protocol 없으니까. Scale 못 함 — 각 client 가 자기 subprocess copy 띄움. 한 server 가 여러 user back 하고 싶은 순간 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

Code

External links

Exercise

Progress

댓글 0