MCP 속성 과정: TypeScript를 사용한 초보자 가이드

이 포스트는 저의 발표 자료인 "A Crash Course in MCP: A Beginners Guide Using TypeScript"를 바탕으로 작성되었습니다.

기술 산업은 간단한 개념을 설명하기 위해 무거운 전문 용어(jargon)에 자주 의존합니다. Model Context Protocol (MCP)의 공식 문서를 읽어보면 다음과 같이 명시되어 있습니다: "AI 애플리케이션을 연결하기 위한 오픈 소스 표준... AI 애플리케이션을 위한 USB-C 포트라고 생각하면 됩니다."

이 설명은 정확하지만, 소프트웨어 엔지니어들에게 가장 직관적인 멘탈 모델(mental model)은 아닙니다.

저에게는 다음과 같이 더 실용적인 정의로 이해하는 것이 훨씬 명확했습니다:

MCP는 모델에 컨텍스트(context)를 주입하는 방법을 정의하는 일련의 규칙입니다.

이를 통해 AI 에이전트(agent)가 애플리케이션의 기저에 있는 데이터와 아키텍처(architecture)를 이해할 수 있게 됩니다. JSON 페이로드(payload)를 수동으로 입력하거나 UI를 탐색하는 대신, 에이전트가 이미 시스템의 컨텍스트를 가지고 있기 때문에 자연어(natural language) 명령을 사용하여 복잡한 함수를 실행할 수 있습니다.

MCP의 세 가지 기둥

이 프로토콜은 세 가지 핵심 프리미티브(primitives)를 기반으로 작동합니다:

리소스 (Resources): 데이터를 보유하는 모든 것. 정적 JSON 파일, HTML 문서 또는 PostgreSQL 데이터베이스에 대한 연결이 될 수 있습니다.
도구 (Tools): 실행 가능한 함수. 이는 MCP 서버가 AI 에이전트에게 노출하는 동작으로, 에이전트가 데이터를 조작하거나 외부 서비스와 상호작용할 수 있도록 합니다.
프롬프트 (Prompts): 특정 작업을 수행하기 위해 사용 가능한 리소스와 도구를 활용하도록 에이전트에 부착된 사전 정의된 지침(instructions).

TypeScript로 MCP 서버 구축하기

만약 ExpressJS를 사용하여 기본적인 서버를 구축해 본 적이 있다면, MCP 서버의 아키텍처는 매우 친숙하게 느껴질 것입니다. 서버를 정의하고, 기능을 설정하며, 엔드포인트(endpoints)(리소스 또는 도구)를 노출하는 방식입니다.

하지만 AI 에이전트를 위해 구축하는 것은 데이터 무결성(data integrity)과 관련된 독특한 과제를 안겨줍니다.

TypeScript의 한계: TypeScript는 개발자 경험(developer experience) 측면에서 환상적이지만, 컴파일 시점에 타입이 모두 제거됩니다. 런타임(runtime) 시점에 서버는 순수 JavaScript(vanilla JavaScript)를 실행합니다.
AI 변수: LLM이 자연어에 기반하여 입력을 결정할 때, 데이터 구조가 올바른지 확인하기 위해 컴파일 타임(compile-time) 체크에 의존할 수 없습니다.
해결책: 우리는 Zod와 같은 런타임 검증(runtime validation) 라이브러리를 사용해야 합니다.

만약 도구가 age 파라미터를 number 타입으로 기대하고 있는데, LLM이 문자열인 "twenty-five"를 입력한다면, Zod는 런타임에서 스키마 위반(schema violation)을 포착하여 잘못된 데이터가 데이터베이스를 오염시키거나 서비스를 중단시키는 것을 방지합니다.

도구 및 메타데이터 정의하기

새 사용자를 생성하는 함수와 같은 도구를 만들 때는 엄격한 메타데이터를 정의해야 합니다. 이는 LLM이 해당 함수와 상호작용하는 방식을 결정합니다:

readOnlyHint: 도구가 단순히 데이터를 가져오는 것이 아니라 데이터를 수정하는 경우(예: 사용자 생성) false로 설정합니다.
destructiveHint: 도구가 데이터를 삭제하거나 돌이킬 수 없게 변경할 수 있는 경우에만 true로 설정합니다.
idempotentHint: 동일한 명령을 여러 번 실행해도 의도하지 않은 부작용 없이 동일한 상태를 유지하는지(멱등성)를 정의합니다.

이러한 파라미터들을 정의함으로써, AI가 자율적으로 실행할 수 있는 것과 없는 것에 대한 가드레일(guardrails)을 구축하게 됩니다. 개발 과정에서는 에이전트가 쓰기 명령(write commands)을 실행하기 전에 클라이언트가 수동 승인을 요청하도록 구성할 수 있습니다.

기본 JSON에서 실제 API로: Google Calendar 연동

로컬 JSON 파일을 대상으로 MCP 서버를 테스트하는 것은 학습에 도움이 되지만, 이 프로토콜의 진정한 힘은 인증된 외부 API와 상호작용할 때 발휘됩니다.

저는 Google Calendar API에 연결된 커스텀 MCP 서버를 구축했습니다. 이 서버는 OAuth 및 JSON 토큰 인증을 처리하여, 저의 로컬 AI 에이전트가 제 개인 일정에 직접 접근할 수 있도록 권한을 부여합니다.

여기 제 Google Calendar MCP 프로젝트를 보여주는 2분짜리 데모가 있습니다.

에이전트가 MCP 서버를 통해 캘린더 API (Calendar API)의 컨텍스트 (Context)를 가지고 있기 때문에, 저는 순수하게 자연어 (Natural Language)만을 사용하여 명령을 실행할 수 있습니다:

쿼리 (Querying): 에이전트에게 _"9월 21일에 일정이 뭐야?"_라고 물어볼 수 있습니다. 그러면 에이전트는 MCP 리소스 (Resource)를 읽고 _"당신의 일정에는 'NYC Code & Coffee: A Crash Course in MCP'가 포함되어 있습니다."_라고 답변합니다.
실행 (Executing): 이벤트 양식을 수동으로 채우거나 API 요청 (API Request)을 작성하는 대신, 에이전트에게 _"이벤트 생성해줘: 10월 22일에 아내와 저녁 식사하기."_라고 말할 수 있습니다. 에이전트는 자연어를 필요한 파라미터 (Parameters) (제목, 시작 시간, 종료 시간)로 매핑하고 도구 (Tool)를 실행합니다. 이벤트는 즉시 Google Calendar에 등록됩니다.

AI 툴링 (AI Tooling)의 현실

LLM (Large Language Models)을 로컬 환경 (Local Environments) 및 백엔드 시스템 (Backend Systems)에 직접 통합하는 것은 일시적인 유행이 아닙니다. 이는 소프트웨어 엔지니어링 (Software Engineering)의 근본적인 변화입니다. 우리는 실행 계층 (Execution Layer)으로서의 자연어를 향해 나아가고 있습니다.

개발자로서 여러분은 명확한 선택에 직면해 있습니다. 워크플로 (Workflows)를 자동화하기 위해 이러한 에이전트형 도구 (Agentic Tools)를 구축하고 제어하는 방법을 배울 것인지, 아니면 그렇게 하는 엔지니어들과 경쟁할 것인지 말입니다.

소통해요!

웹사이트: callmeizzy.dev
YouTube: Call Me Izzy
GitHub: @MrItzreal
X / Twitter: @fullstackizzy
LinkedIn: Israel (Izzy) Santana