아프니까 개발자다 아프니까 개발자다

MCP(Model Context Protocol, AI 모델을 외부 도구·데이터와 잇는 표준 규약)의 원격 트랜스포트는 처음에 HTTP + SSE 조합이었다. 동작은 잘 했다. 그런데 2025년 3월, MCP 명세는 트랜스포트를 Streamable HTTP라는 새 방식으로 갈아탔다. 잘 굴러가던 걸 왜 바꿨을까? 이 글은 그 이유를 따라간다 — 옛 방식이 남긴 어떤 숙제 때문에, Streamable HTTP가 무엇을 어떻게 바꿨고, 그래서 MCP에 무엇이 좋아졌는지를 순서대로 본다.(이 글은 SSE가 무엇이고 MCP가 왜 그걸 골랐는지를 다룬 앞 글의 후속이다. SSE의 기본 — 서버가 HTTP 위에서 클라이언트에게 데이터를 밀어 넣는 단방향 스트림 — 은 안다고 보고 출발한다.)출발점: 잘 돌아가던 두..

MCP(Model Context Protocol, AI 모델을 외부 도구·데이터와 잇는 표준 규약) 문서를 처음 읽으면 SSE라는 세 글자에서 한 번 멈칫하게 된다. "원격 트랜스포트는 HTTP + SSE를 쓴다"는 문장은 나오는데, 정작 왜 하필 SSE인지는 설명 없이 지나가기 때문이다. 이 글은 그 빈자리를 채운다 — MCP가 왜 SSE를 끌어들일 수밖에 없었고, SSE가 어떤 문제를 어떻게 풀었으며, 그래서 MCP에 무엇이 좋아졌는지를 순서대로 본다.SSE는 Server-Sent Events의 약자다. 이름 그대로 "서버가 먼저 보내는 이벤트", 즉 서버가 클라이언트에게 데이터를 밀어 넣는(push) 표준 방식이다. 이 한 줄에 MCP가 SSE를 고른 이유가 이미 절반쯤 담겨 있다 — MCP에서는 ..

처음 JSON-RPC 요청을 손으로 만들어 보면 누구나 한 번은 멈칫하는 자리가 있다. id에 1을 적어 넣는 순간이다. "이걸 내가 1로 정해도 되나? 같은 서버에 접속한 다른 클라이언트도 1을 쓰면 응답이 섞이지 않나?" 그럴듯한 걱정이다. 그리고 이 걱정이 어디서 어긋났는지 따라가다 보면 JSON-RPC라는 프로토콜의 설계 의도가 거의 통째로 드러난다.이 글은 그 한 줄짜리 의문에서 출발한다. id는 누가, 어떻게 정하는가? 다른 클라이언트가 같은 id를 쓰면 정말 무슨 일이 벌어지는가? 그리고 보통 어떤 식으로 id를 정하며, 그 선택이 실제로 어떤 문제를 막아 주는지 — 사례 중심으로 풀어 본다.먼저, JSON-RPC 요청 한 개의 생김새JSON-RPC는 "함수 하나를 원격으로 호출하는 약속"을..

서브에이전트의 tools 필드에는 기본 도구(Read, Edit, Bash, Grep)를 지정한다. 그런데 이 기본 도구만으로 커버되지 않는 능력이 필요할 때가 있다. 웹 페이지를 직접 가져오거나, 가설을 단계별로 구조화해서 추론하거나, 외부 API를 호출하거나. 이런 새 도구는 MCP 서버에서 온다. 어떤 MCP 서버를 쓸지를 정의하는 파일이 .mcp.json이다.MCP(Model Context Protocol)는 AI 모델이 외부 시스템·도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 다양한 장치를 하나의 표준 포트로 연결하는 것과 같다..mcp.json이 없을 때 vs 있을 때▲ .mcp.json 없음 — 기본 도구만, 외부 능력 없음▲ .mcp.json 있음 — MCP 도구로 외부 능..

Tool Search Tool이 "build"를 검색하면 왜 build_app이 나오는가. 어떤 알고리즘이 100개 도구 카탈로그에서 관련 있는 3~5개만 골라내는가. 답은 BM25다 — 검색 엔진의 고전적 랭킹 알고리즘으로, Google 이전 시대부터 쓰인 방법이 AI 도구 검색의 핵심으로 돌아왔다. 이 글은 BM25가 어떻게 작동하는지, 왜 도구 검색에 잘 맞는지, 그리고 개발자가 여기서 어떤 설계 결정을 해야 하는지를 풀어낸다.검색의 기초 — 역색인BM25를 이해하려면 먼저 역색인(Inverted Index)을 알아야 한다. 역색인은 "어떤 단어가 어떤 문서에 있는가"를 미리 계산해 놓은 테이블이다. 일반 색인이 "문서 A에는 어떤 단어들이 있는가"를 저장한다면, 역색인은 방향을 뒤집어 "단어 X는..

지난 글에서 deferred loading으로 도구 100개를 컨텍스트 밖으로 밀어낼 수 있다고 했다. 이 글은 그 전 단계, 도구를 어떻게 정의하고 등록하는가를 다룬다. 도구 등록의 본질은 JSON 스키마다 — 세 가지 필수 필드가 각각 무엇을 결정하는지, input_schema를 어떻게 설계해야 LLM이 파라미터를 혼동하지 않는지, description이 왜 단순한 메모가 아니라 BM25 검색 인덱스이기도 한지를 다이어그램으로 해부한다.도구 호출은 어떻게 작동하는가LLM이 도구를 "직접 실행"한다는 인상이 있지만, 실제로는 다르다. LLM은 도구를 어떤 파라미터로 불러야 하는지를 JSON 형태로 출력할 뿐이다. 그 JSON을 받아 실제로 실행하는 것은 LLM 밖의 코드다. 결과가 다시 LLM에게 전달..

내 개인 개발 서버에는 커맨드라인 도구가 수십 개 깔려 있다. 앱을 빌드하는 도구, 디바이스에 연결하는 도구, 에뮬레이터를 띄우는 도구, 패키징·서명하는 도구, 디버거… 각 도구는 또 수개에서 수십 개의 서브커맨드를 가진다. 어느 날 이런 생각이 들었다. "이걸 전부 코딩 어시스턴트가 자연어로 불러 쓰게 하면 어떨까?"여기서 코딩 어시스턴트란 Claude Code나 Cursor처럼 LLM이 외부 도구를 직접 호출할 수 있는 개발 도구를 말한다. 이들은 대부분 MCP(Model Context Protocol, AI 모델과 외부 도구·데이터를 잇기 위해 공개된 표준 규약 — "AI용 USB-C 포트"에 비유되곤 한다)를 지원한다. MCP 서버를 하나 띄워 도구들을 등록하면, 어시스턴트가 그 도구들을 자기 손..

지금까지 수십 개의 커맨드라인 도구를 코딩 어시스턴트에 노출하는 이야기를 세 편에 걸쳐 했다 — 3단 깔때기로 도구를 줄이고, Descriptor로 호출법을 가르치고, 비동기 job으로 긴 작업을 다뤘다. 그런데 이 모든 전제에는 구멍이 하나 있다. "도구가 CLI일 때"라는 전제다.현실의 도구 중에는 명령줄이 아예 없는 것들이 있다. GUI(그래픽 화면)로만 동작하는 도구 — 창을 띄우고, 버튼을 누르고, 마우스로 클릭해야 일이 되는 도구다. LLM에게는 누를 버튼도, 받아 읽을 표준 출력(stdout)도 없다. 이런 도구를 코딩 어시스턴트에 어떻게 태울 것인가?문제: GUI는 LLM이 잡을 손잡이가 없다코딩 어시스턴트가 도구를 부르는 방식은 결국 "명령을 문자열로 만들어 실행하고, 출력 텍스트를 받아..