소개
안녕하세요. 22기 인터페이스 개발 스터디를 맡고 있는 이재엽입니다.
지난 사례글에서는 인터페이스를 사람과 컴퓨터를 잇는 모든 지점으로 넓게 봤었는데요, 이번에는 거기서 가장 대표적인 형태인 API를 직접 간단하게 하나 만들어보려고 합니다. 그리고 거기서 멈추지 않고, 그 API를 AI가 직접 호출할 수 있게 해주는 MCP까지 한 겹 더 얹어볼 거예요.
작은 캘린더 하나를 두고 풀스택 → API → MCP 순서로 인터페이스를 한 겹씩 쌓아가는 이야기입니다. 같은 기능인데 그걸 쓰는 대상이 사람 → 프로그램 → AI로 넓어지는 과정을 그대로 보여드리고 싶었어요.
진행 방법
거창하지 않게, 캘린더 하나
뭘 만들지 고민할 때 일부러 작은 걸 골랐어요. 일정을 만들고, 보고, 지우는 정도의 캘린더입니다. 주제가 인터페이스인 만큼 결과물 자체가 화려한 것보다, 인터페이스가 한 겹씩 쌓여가는 과정이 눈에 보이는 게 더 중요했거든요.
스택은 가볍게 가려고 이렇게 정했습니다.
서버: Bun + Hono
DB: SQLite
따로 무겁게 설치할 것 없이 파일 하나로 DB가 돌아가고, 서버도 명령어 한 줄로 가볍게 뜨는 조합이라 처음 시작하기에 부담이 없습니다.
1단계 — 풀스택부터
먼저 사람이 직접 보고 쓰는 화면을 만듭니다. 달력이 뜨고, 일정을 적으면 저장되고, 다시 들어가면 그대로 남아 있는 정도예요. 여기서 화면(UI)은 사람을 위한 인터페이스입니다. 우리가 가장 익숙하게 떠올리는 형태의 인터페이스죠.
2단계 — API를 만든다
그다음, 화면이 데이터베이스를 직접 만지지 않도록 중간에 API를 둡니다. 일정 목록을 가져와줘(조회), 새 일정을 추가해줘(추가), 이 일정을 지워줘(삭제) 같은 요청을 받아서 처리하는, 약속된 호출 지점을 만드는 거예요.
이렇게 분리해두면 화면이든 다른 프로그램이든, 누가 호출하든 똑같은 규칙으로 캘린더를 다룰 수 있게 됩니다. API는 이름 그대로 다른 프로그램(클라이언트)이 약속된 방식으로 호출하는 인터페이스예요. 화면(UI)이 사람을 위한 인터페이스였다면, API는 프로그램을 위한 인터페이스인 셈이죠. 같은 캘린더인데 호출하는 쪽이 사람에서 프로그램으로 바뀐 겁니다. 인터페이스 개발에서 가장 기본이 되는 형태라, 이번에 그 대표 주자를 직접 만들어봤어요.
3단계 — MCP를 붙인다
여기가 이번 사례의 핵심입니다. 이렇게 만든 API를, 이번엔 AI가 직접 호출할 수 있게 만들 거예요. 그걸 위한 표준 포맷이 MCP입니다.
방식은 생각보다 단순해요. 제 캘린더 API를 그대로 감싸는 얇은 MCP 서버를 하나 따로 만듭니다. 이 MCP 서버가 하는 일은, AI가 내일 3시에 일정 추가해줘라고 하면 그 요청을 받아 제가 만든 캘린더 API를 대신 호출해주는 거예요. 말하자면 AI와 제 API 사이를 이어주는 번역기 같은 역할입니다.
그리고 이 MCP 서버를 평소에 쓰는 AI에 등록해둡니다. 한 번 등록해두면 그 AI가 MCP 클라이언트가 되어서 제 캘린더를 직접 다룰 수 있게 되고요. MCP는 표준이라 특정 AI 하나에만 묶이지 않고, MCP를 지원하는 여러 AI가 같은 캘린더를 공통으로 호출해 쓸 수 있다는 것도 큰 장점입니다.
결과와 배운 점
같은 캘린더에 인터페이스가 세 계층으로 쌓였다
이번에 만들면서 같은 캘린더 하나에 인터페이스가 세 계층으로 쌓였어요.
UI(화면) — 사람(사용자)을 위한 인터페이스
API — 다른 프로그램(클라이언트)을 위한 인터페이스
MCP — AI(LLM 클라이언트)를 위한 인터페이스
기능은 똑같습니다. 일정을 만들고, 보고, 지우는 캘린더 하나죠. 다만 그걸 누가 호출하느냐에 따라 인터페이스를 한 계층씩 더 얹은 거예요. 재밌었던 건 UI와 API에서 멈추지 않고, AI 클라이언트를 위한 MCP 계층까지 자연스럽게 이어붙일 수 있다는 점이었습니다.
가장 드라마틱한 지점 — AI한테 자기소개 시키기
MCP 서버를 AI에 등록해서 연결해두면, AI는 그 서버한테 너 무슨 기능을 갖고 있어? 하고 목록을 직접 불러올 수 있습니다. 그런데 이때 단순히 기능 이름만 오는 게 아니에요. 각 기능을 어떤 값으로 어떻게 호출해야 하는지(설명, 그리고 입력 스키마)까지 함께 옵니다.
그래서 제가 AI한테 연결된 MCP들한테 자기소개 를 한번 시켜봐라고 하면, AI가 제 캘린더 MCP에 물어보고 일정을 추가하려면 날짜와 제목을 이런 형식으로 넣으면 됩니다 같은 사용법을 스스로 받아옵니다.
이게 왜 드라마틱하냐면, 제가 AI한테 이 주소로 이렇게 호출해라고 하나하나 알려주지 않아도 AI가 알아서 도구의 설명과 스키마를 읽고 정확하게 호출하기 때문이에요. 사용법을 사람이 주입하는 게 아니라 AI가 직접 읽어서 파악하는 구조인 거죠. 그래서 MCP는 거창한 게 아니라 AI가 읽을 수 있는 사용설명서(description·schema)가 붙은 API입니다. 사용설명서가 또렷하게 붙어 있을수록 AI가 그만큼 더 확실하게 호출하고요. 이렇게 AI가 스스로 사용법을 읽어가는 기능이 실제로 된다는 걸 보여드리는 게, 이번 사례에서 제가 가장 드라마틱하다고 생각하는 부분이에요.
시행착오
처음엔 스택을 뭘로 할지 너무 오래 고민했어요. 이것저것 따지다가 결국 일단 작게 시작하자로 정리하고 Bun + Hono + SQLite로 갔는데, 돌이켜보면 스택 고르는 데 쓴 시간보다 일단 만들어보면서 배운 게 훨씬 많았습니다. 완벽한 선택을 기다리기보다 작게라도 굴려보는 게 빨랐어요.
앞으로의 계획
캘린더 말고 다른 API들도 같은 방식으로 MCP를 씌워보려고 합니다. 그렇게 해두면 제가 쓰는 여러 AI 클라이언트가 공통으로 제 API들을 호출해 쓸 수 있게 되거든요. 인터페이스를 한 계층 더 얹는 이 감각을 스터디원분들과도 같이 해보려고 해요.
그리고 이 사례는 오늘 저녁 9시 스터디 라이브 에서 직접 보여드릴 예정입니다. 캘린더 풀스택부터 API, MCP까지 처음부터 만들고, 마지막엔 실제로 쓰는 클로드 코드에 MCP를 연결한 뒤 도구 목록을 새로고침해서, 그 자리에서 AI가 제 캘린더를 직접 호출하는 것까지 함께 확인해보려고 합니다.
도움 받은 글
(없음)
