요약
MCP 메시지가 실제로 어떻게 오가는지 한 단계씩 보여 주는 인터랙티브 해설 사이트입니다.
MCP(모델 컨텍스트 프로토콜, AI 앱을 도구·데이터에 연결하는 공개 표준)를 다룬 해설서입니다. MCP 게이트웨이를 만드는 런레이어가 공개했습니다. 스펙 2025-11-25판을 기준으로 JSON-RPC 메시지를 애니메이션으로 보여 줍니다.
왜 중요한가
- 개념 설명에서 그치지 않고 전송·인증·도구 호출마다 실제로 오가는 메시지를 공식 스펙 링크와 함께 보여 줍니다.
- 스펙 타임머신에서 같은 흐름을 판별로 비교할 수 있어, 2026-07-28판에서 핸드셰이크와 세션이 사라지는 변화도 확인할 수 있습니다.
- 도구 포이즈닝(도구 설명에 악성 지시를 숨기는 공격) 같은 위험을 재현해 보는 공격 레슨도 들어 있습니다.
핵심 내용
- 모델은 서버와 직접 통신하지 않고, 호스트(AI 앱)가 도구 목록을 보여 주고 호출을 대신 실행합니다.
- MCP는 REST가 아니며, JSON-RPC라는 봉투 안에 메서드·기능 협상·전송·인증을 정한 규약이라고 설명합니다.
- 커넥터가 40개면 도구가 1,000개를 넘어 컨텍스트를 거의 다 차지하므로, 필요한 스키마만 불러오는 도구 검색을 소개합니다.
- codemode는 모델에 TypeScript 실행 도구 하나만 주고, 여러 호출을 샌드박스 코드 안에서 묶어 결과만 돌려받게 합니다.
- 공격 레슨마다 런레이어 게이트웨이가 막는 것과 막지 못하는 것을 함께 적었습니다.
HN 반응
- 너무 빽빽해 이미 아는 사람에게만 친절하다는 지적이 많았고, AI로 만든 해설서라 보여 줄 정보를 고르는 안목이 없다는 비판도 나왔습니다.
- MCP 자체를 두고는 CLI와 스킬(에이전트용 지침 파일)이면 충분하다는 회의론과, 셸이 없는 에이전트에 제한된 원격 접근을 주는 데 유용하다는 반론이 맞섰습니다.
너무 빽빽해요. 차라리 주석을 충분히 단 파이썬 코드를 올리는 게 같은 요점을 전달하는 데 낫겠어요. 도식 몇 개를 곁들여 잘 쓴 글 하나면 훨씬 도움이 됐을 겁니다. 때로는 적은 게 더 많은 법이죠.
MCP는 이 정도로 기술적인 설명까지 필요하지 않아요. 기본적으로 에이전트를 겨냥해 탐색용 엔드포인트를 표준화한 REST API일 뿐이니까요. 그리고 이런 일에서는 AI 에이전트가 안목이 정말 부족합니다.
맞아요. 이런 건 이미 시스템이 어떻게 돌아가는지 아는 사람한테는 훌륭하게 느껴지는 '설명 자료'인데, 정작 초보자에게는 소용이 없습니다. 그 분야에 푹 빠진 사람에게는 '당연해' 보이는 시스템의 전체 모양을 독자가 안다고 암묵적으로 전제하기 때문입니다.
제가 접하는 문서 대부분이 이 문제를 안고 있어요. 좋은 문서라면 사용자에게 그것을 어떻게 쓰는지도 가르쳐 줘야지, 그저 별도 파일에 담긴 거창한 코드 주석 수준에 그쳐서는 안 됩니다.
> 제가 접하는 문서 대부분이 이 문제를 안고 있어요.
대부분의 문서는 레퍼런스 문서입니다. 말씀하신 대로 처음 시작하는 데는 별로 쓸모가 없습니다. 문서화하는 대상에 대해 최소한 약간의 기초 지식은 있다고 전제하니까요.
> 좋은 문서라면 사용자에게 그것을 어떻게 쓰는지도 가르쳐 줘야지
좋은 문서는 보통 최소 두 부분, 즉 안내서·입문서와 레퍼런스로 이루어집니다. 종이책이 프로그래머의 핵심 학습 수단이던 시절, 오라일리(ORA)의 괜찮은 책들이 이런 식으로 쓰였습니다. 세 부분으로 구성되었는데, 하나는 아주 기초적인 내용(시작하기 전에 알아야 할 것으로, 많은 독자가 건너뛸 수 있는 부분)이고, 둘째는 새로운 대상(언어, 라이브러리, 서버 등)의 개념과 비슷하거나 관련된 것들과 무엇이 다른지를 보통 예제를 곁들여 소개하는 입문이고, 적어도 뒤쪽 절반 이상의 분량은 (필요하면 의미 있는 단위로 나눈) 레퍼런스 자료였습니다. 때로는 이를 둘로 쪼개 같은 주제에 대해 입문서와 레퍼런스를 따로 내기도 했습니다("완전 레퍼런스"라는 이름을 달았지만 이쪽에도 입문 성격의 글이 조금은 들어 있었습니다). 다만 늘 그랬던 것은 아닙니다.
안내서와 레퍼런스를 너무 바짝 합치면, 숙련된 독자에게는 지나치게 기초적이거나 짜증 날 만큼 장황하고, 맨바닥에서 시작하는 사람에게는 여전히 불투명한 문서가 되기 십상입니다.
요즘은 안내서 역할을 README 하나로 충분히 할 때도 있고, 그 README에서 특정 부분의 더 긴 입문 글로 뻗어 나가는 링크가 필요할 때도 있습니다. 프로젝트 규모에 따라 다릅니다.
저도 제가 깊이 이해하는 것을 문서로 쓸 때 자주 저지르던 실수예요. 그 이해에 이르게 해 준 질문들을 잊어버리는 겁니다. 지금은 대상 독자가 아는 수준을 의식적으로 생각하려고 노력합니다. 그래도 놓치는 게 있는데, 그래서 다른 사람이 검토해 주는 게 좋은 겁니다.
모든 기술 문서가 어떤 개념을 설명할 때 제1원리부터 시작하면 좋겠습니다. 그러면 세상이 더 나아질 거예요.
도움이 되는 피드백입니다. 저도 양쪽 입장을 다 겪어 봤는데, 그 문제를 이렇게 또렷하게 정리한 말은 처음 들어 봐요.
그래서 방금 뭔가를 배운 사람이 문서를 쓰는 게 더 낫습니다(물론 전문가가 검수해야겠지만요).
말 그대로 JSON-RPC인데 왜 REST API라고 하시는지 모르겠네요. REST API와는 비슷하지도 않아요.
이 맥락과 용도에서는 닮은 점이 많다고 봅니다.
둘 다 상태를 갖지 않는(stateless) RPC 메서드와, 사람이 읽을 수 있는 메타데이터를 제공해서 라우팅하기 쉽습니다.
2.0에서 json-rpc가 왜 굳이 필요했는지 물을 수도 있겠죠. 제 생각엔 대부분 stdio와 하위 호환성 때문이었을 겁니다.
REST는 명시적으로 RPC가 아닙니다.
MCP와 REST의 벤 다이어그램을 그리면 (선택적인) 겹치는 부분이 있는 건 분명하지만, 한쪽이 다른 쪽을 포함하지는 않습니다.
지금은 더 나아 보이네요. 작성자가 지적을 반영한 모양입니다. 본인도 그렇다는 취지의 댓글을 몇 개 달았는데 전부 죽어 있어요. 섀도밴을 당한 것 같습니다. 제가 그 댓글들을 vouch 해 두긴 했는데, 어디까지나 제 체감으로는 글을 살리는 데는 죽이는 데 필요한 신고(flag)보다 훨씬 많은 vouch가 필요한 것 같아요.
왜 차단됐느냐에 따라 달라요. vouch 한 번으로 바로 풀릴 때도 있습니다. AI가 쓴 글로 감지된 건 vouch로 복구하기 어려울 거예요.
제가 vouch 하는 flag 걸린 댓글은 대부분 한 번이면 되던데요. 한 번 넘게 필요하다면 그 댓글은 flag를 꽤 많이 받았거나 아니면 특정 감지 규칙에 걸렸을 거라는 느낌이 듭니다.
생성형 AI가 쓴 댓글은 vouch 하지 않는 편이 커뮤니티에 더 좋을 겁니다.
이런 바이브 코딩 식 설명 페이지는 겉보기엔 근사한데, 실제로는 오히려 더 헷갈리게 만들어요. 어떤 정보를 언제 보여 줄지 골라내는 큐레이션이 필요한데, 여기서는 그게 전혀 전달되지 않습니다.
동의합니다. LLM이 만든 이런 설명 자료는 그걸 프롬프트로 요청한 사람에게만 쓸모 있는 경향이 있어요. 그 사람은 자기에게 뭐가 불분명한지 알고, 자기만 아는 머릿속 모델이 있으며, 마음에 드는 모양이 되고 원하는 방식으로 개념이 설명될 때까지 계속 프롬프트를 다듬을 수 있으니까요. 저도 이런 걸 항상 쓰지만, 다른 누구라도 프롬프트 몇 번이면 얻을 수 있는 것을 굳이 공유할 이유는 모르겠습니다.
MCP는 엔터프라이즈용 도구입니다.
잠깐 쓰고 말 것이면 -> 그냥 스킬을 쓰세요.
MCP의 장점은 얇고, 정말 잘 통합되어 있을 때, 그리고 회사의 플랫폼 제공자가 그 통합을 해 줄 때에야 비로소 드러나기 시작합니다.
그렇지 않으면 CLI를 온갖 MCP와 계속 연동해 두는 게 엄청나게 골치 아파요.
MCP는 말 그대로 '항상' 쓰는 것이거나, 시스템에 매끄럽게 통합돼 있어서 신경 쓸 필요가 없는 경우에 좋습니다.
그게 아니라면 AI에게 CLI 사용법을 알려 주기만 하면 돼요.
제 생각엔 MCP는 실수였을지도 모릅니다. 로컬 서비스라는 측면은 곁가지에 불과했고요.
'엔터프라이즈 통합' 부분은 '도구'나 다른 무엇과 어떻게 통합되는지와 엮지 말고, 일종의 API 표준으로 정리했어야 가장 좋았을 겁니다.
너무 일찍 나왔어요.
혹시 codex 같은 데서 이제 MCP 호출을 조합(compose)할 수 있나요? 예를 들어 모델이 jira MCP 호출 결과를 grep이나 sed로 파이프로 넘기거나, 하다못해 파일로라도 저장할 수 있나요? 제가 마지막으로 본 MCP는 curl, .netrc, 그리고 호출을 설명하는 짧은 텍스트 파일 몇 개(이것들 자체도 grep으로 검색할 수 있죠)보다 훨씬 못한 버전일 뿐이었어요. 제가 놓치고 있는, 그 이상의 쓸모가 있나요?
제가 마지막으로 확인했을 땐 여전히 안 됩니다. 클라이언트에게 CLI를 호출하라고 알려 주고 도움말 메뉴로 점진적 공개(progressive disclosure)를 하는 스킬이 벤치마크에서 더 좋게 나와요. 개발자들이 이걸 곧바로 알아챘고, 그래서 일종의 반(反)MCP 정서가 있습니다. 이 프로토콜은 아마 코더가 아닌 사람들이 쓰는 비코딩 에이전트를 염두에 두고 주로 구상된 것 같아요.
이론상으로는 에이전트가 이걸 더 잘하는 법을 기본으로 알고 있어서, 원하시는 조합 기능을 그대로 얻을 수 있을 겁니다. 사실 CLI로 mcp-caller를 하나 만들고 에이전트에게 MCP는 반드시 그걸 통해서만 호출하라고 하면 끝이에요. 그걸로 해결됩니다.
코더에게도 MCP가 다시 의미를 갖는 지점은 샌드박스를 좀 더 통제된 방식으로 벗어나게 해 주는 부분입니다.
덧붙이자면 이런 건 점점 덜 중요해집니다. 늘 나오는 쓴 교훈(bitter lesson)이죠. 모델이 워낙 빠르게 좋아지니 뭐든 최적화하려는 시도는 바다에 물 한 방울일 뿐입니다.
로컬 코딩 어시스턴트를 너무 많이 접하면 개발자들은 모든 에이전트가 보통 완전한 셸이 있고 임의의 파이썬 스크립트와 curl 명령을 작성해 실행할 수 있는 환경에서 돌아간다고 가정하게 되는 것 같아요.
그런 도구가 없는 에이전트를 생각해 보세요. MCP는 그런 에이전트에게 원격 리소스에 대한 제한된 접근 권한을 주는 훌륭한 방법입니다.
저라면 오히려 왜 그런 도구가 없느냐부터 물을 거예요. 뭐든 인터프리터가 있으면 모델이 컨텍스트를 관리하고 분석하는 능력이 훨씬 좋아질 게 뻔하니까요. 그러니 적어도 stdin/stdout 말고는 입출력이 없는 파이썬 인터프리터 같은 데로 MCP 호출을 파이프로 넘길 수 있어야 합니다.
네, 됩니다. CodeMode를 찾아보세요(Opencode와 Pi 둘 다에서 쓸 수 있어요). 에이전트가 코드 실행 도구를 쓸 수 있고, 이 도구로 코드를 작성해 다른 도구나 MCP를 호출하고 조합할 수 있습니다.
네, 새 Pi 하니스에 codemode가 있고 다른 곳에도 많을 거라 생각해요.
저희 스타트업 내부에서는 자바스크립트의 부분집합을 위한 인터프리터를 만들었는데, 에이전트가 거기서 자기 도구와 MCP를 조합할 수 있어요. 멋진 점은 같은 스크립트로 지속 가능한 워크플로와 자동화까지 만들 수 있다는 겁니다.
REST냐 JSON-RPC냐 하는 논쟁은 곁다리 같아요. 잘 설계된 CLI와 코드 실행으로는 못 얻고 MCP만 주는 게 정확히 뭔가요?
글쎄요, 어떤 서비스든 대부분의 CLI는 그냥 REST를 감싼 래퍼예요.
MCP에서 흥미롭고 꼭 필요한 부분은 인증입니다. 더 쓸모 있는 설명이라면 "왜"를 훨씬 더 다뤄야 해요. MCP가 언급된 스레드를 보면 어김없이 "CLI와 전통적인 REST API가 똑같은 일을 하는데 왜 또 다른 스펙이 필요하냐"고 말하는 사람이 수두룩하거든요.
물론 지금은 특정 사용 사례를 다루려고 스펙에 앱과 태스크가 들어와 있지만, 그런 것도 프로토콜 없이 직접 만들 수 있고 에이전트는 여전히 그걸 쓸 수 있습니다.
깃허브 링크를 못 찾겠네요. 이 코드를 어디서 구할 수 있는지 아시는 분 있나요? 비기술직 관리자들이 보기 편한 입문 자료로 고쳐 보고 싶어서요.
HTML 파일 한 장짜리예요. 그냥 내려받아서 하려는 작업의 입력으로 쓰시면 됩니다.