작은 캘린더로 이해한 AI 시대의 인터페이스: UI에서 API, MCP까지

## 소개

처음에는 단순한 캘린더를 만들어보는 실습이라고 생각했습니다.

일정을 등록하고, 날짜별로 확인하고, 필요하면 수정하거나 삭제하는 정도의 기능이면 충분하다고 생각했습니다. 그런데 직접 만들어보니 이 작은 캘린더 안에도 여러 종류의 “인터페이스”가 숨어 있었습니다.

사람이 화면에서 클릭하고 입력하는 **UI**,  
프로그램이 정해진 규칙으로 호출하는 **API**,  
그리고 AI가 도구 설명을 읽고 직접 호출하는 **MCP**까지 이어지는 구조였습니다.

이번 실습에서는 Bun, Hono, SQLite를 사용해 로컬 웹 캘린더를 만들고, 여기에 MCP 서버를 붙여 Claude Code에서 직접 일정을 조회하고 생성할 수 있도록 구성했습니다.

처음 목표는 단순했습니다.

> “캘린더를 하나 만들어보자.”

하지만 해보고 나니 실제로 배운 것은 캘린더 자체보다도,  
**기능을 누구에게 어떤 방식으로 열어줄 것인가**였습니다.

## 진행 방법

### 1. 사람이 쓰는 캘린더 화면 만들기

먼저 로컬에서 실행되는 웹 캘린더를 만들었습니다.

사용한 구성은 다음과 같습니다.

- 런타임: Bun
- 웹 프레임워크: Hono
- 데이터베이스: SQLite
- UI: 단일 HTML 페이지
- 서버 주소: `http://localhost:3000`

기본 화면은 왼쪽에는 달력, 오른쪽에는 일정 목록이 보이는 구조였습니다.

처음에는 일반적인 캘린더처럼 다음 기능을 구현했습니다.

- 일정 목록 보기
- 일정 추가하기
- 일정 삭제하기
- 날짜별 일정 확인하기

이 단계에서 캘린더는 사람이 화면을 보고 직접 사용하는 서비스였습니다.  
즉, **UI는 사람을 위한 인터페이스**였습니다.

---

### 2. 캘린더 기능을 API로 분리하기

그다음에는 화면에서만 동작하던 캘린더 기능을 API로 분리했습니다.

예를 들어 다음과 같은 기능을 정해진 방식으로 호출할 수 있게 만들었습니다.

- 일정 생성
- 특정 날짜 일정 조회
- 날짜 범위 일정 조회
- 일정 수정
- 일정 삭제
- 카테고리 생성, 수정, 삭제

이렇게 하니 화면뿐 아니라 다른 프로그램도 같은 방식으로 캘린더 기능을 사용할 수 있게 되었습니다.

여기서 API는 사람을 위한 화면이 아니라,  
**프로그램이 기능을 호출하기 위한 인터페이스**였습니다.

---

### 3. MCP 서버 붙이기

이번 실습의 핵심은 MCP 서버를 붙인 부분이었습니다.

`src/mcp.ts`에 MCP stdio 서버를 만들고, Claude Code에서 캘린더 기능을 직접 호출할 수 있도록 했습니다.

MCP 서버에는 다음 5개의 도구를 정의했습니다.

| 도구 | 설명 |
|---|---|
| `create_schedule` | 일정 생성 |
| `list_schedules_by_date` | 특정 날짜 일정 조회 |
| `list_schedules_by_range` | 날짜 범위 조회 |
| `update_schedule` | 일정 수정 |
| `delete_schedule` | 일정 삭제 |

MCP 서버 등록은 CLI 명령으로 진행했습니다.

```bash
claude mcp add calendar-mcp -- /opt/homebrew/bin/bun \
  "/Volumes/X10 Pro/GPTers_vault/Interface_API TEST/src/mcp.ts"

예를 들어 사용자가 Claude Code에게 이렇게 요청할 수 있습니다.

“6월 10일에 인터페이스 스터디 마지막 날 일정 등록해줘. 저녁 9시부터 11시까지.”

그러면 AI는 MCP 도구를 통해 아래와 같은 일정 생성 요청을 만들 수 있습니다.

{
  "title": "인터페이스 스터디 마지막 날",
  "start_at": "2026-06-10T21:00:00",
  "end_at": "2026-06-10T23:00:00"
}

이 경험을 통해 MCP가 단순한 API 호출과는 조금 다르다는 것을 느꼈습니다.

API는 사람이 문서를 보고 사용법을 이해해야 합니다.
반면 MCP는 AI가 도구의 설명과 입력 형식을 읽고, 어떤 기능을 어떻게 호출해야 하는지 이해할 수 있게 해줍니다.

즉, MCP는
AI가 사용할 수 있도록 설명서와 입력 규칙이 붙은 인터페이스에 가깝다고 느꼈습니다.

4. 실제 캘린더처럼 기능 다듬기

MCP 연결 이후에는 캘린더 자체도 실제로 쓸 수 있는 형태로 다듬었습니다.

추가한 기능은 다음과 같습니다.

• 업무, 개인, 기타 카테고리 구분

• 카테고리별 색상 표시

• 사용자가 직접 카테고리 추가·수정·삭제

• 날짜 셀 클릭 시 일정 추가 모달 열기

• 기존 일정 클릭 시 수정 모달 열기

• 장소와 비고 입력란 추가

• 더미 일정 데이터 생성

예를 들어 일정 카테고리는 다음과 같이 기본 색상을 지정했습니다.

이 과정을 거치면서 단순한 캘린더가 점점 “실제로 쓸 수 있는 도구”처럼 변했습니다.

특히 날짜 셀을 클릭하면 바로 일정 추가 모달이 열리고, 기존 일정을 클릭하면 수정할 수 있게 만든 부분이 사용성 측면에서 가장 크게 체감되었습니다.

결과와 배운 점

이번 실습에서 가장 크게 배운 것은
같은 캘린더 기능도 사용하는 주체에 따라 인터페이스가 달라진다는 점이었습니다.

정리하면 다음과 같습니다.

처음에는 캘린더를 만든다고 생각했지만, 실제로는 인터페이스의 계층을 하나씩 쌓아본 경험이었습니다.

특히 MCP는 막연하게 들으면 어렵게 느껴졌습니다.
하지만 작은 캘린더에 붙여보니 조금 다르게 이해되었습니다.

MCP는 AI에게 기능을 “그냥 연결”하는 것이 아니라,
AI가 이해할 수 있는 방식으로
무엇을 할 수 있는지, 어떤 값을 넣어야 하는지 알려주는 연결 방식이었습니다.

기억에 남는 시행착오

1. MCP 등록 방식

처음에는 설정 파일에 MCP 서버 정보를 넣으면 될 것이라고 생각했습니다.
하지만 실제로는 CLI 명령으로 등록해야 했습니다.

이 과정을 통해 MCP는 코드 작성뿐 아니라, 실행 환경과 연결 방식도 함께 이해해야 한다는 것을 알게 되었습니다.

2. 날짜 범위 조회 문제

날짜 범위로 일정을 조회할 때 종료일 처리를 단순하게 하면, 해당 날짜의 늦은 시간 일정이 누락될 수 있었습니다.

그래서 종료일에는 하루의 마지막 시간까지 포함되도록 처리했습니다.

$end: `${date}T23:59:59.999`

날짜 데이터는 단순해 보여도 실제로는 경계값 처리가 중요하다는 것을 배웠습니다.

3. 클릭 이벤트 충돌

달력의 날짜 셀을 클릭하면 일정 추가가 열리고, 기존 일정 칩을 클릭하면 일정 수정이 열려야 했습니다.

그런데 일정 칩이 날짜 셀 안에 있다 보니 클릭 이벤트가 충돌했습니다.
이를 해결하기 위해 이벤트 전파를 막았습니다.

onclick="openEdit(id, ds); event.stopPropagation()"

이 문제를 해결하면서 UI에서는 “무엇을 클릭했는가”뿐 아니라
“그 클릭이 어디까지 전달되는가”도 중요하다는 것을 배웠습니다.

마무리

이번 캘린더 프로젝트는 거창한 서비스는 아니었습니다.

하지만 작은 기능 하나를 가지고도
UI, API, MCP를 차례대로 붙여보니 인터페이스의 의미가 훨씬 선명해졌습니다.

사람이 쓰는 화면을 만들고,
프로그램이 쓰는 API를 만들고,
마지막으로 AI가 쓰는 MCP를 붙였습니다.

이 과정을 통해 MCP를 어렵고 추상적인 개념이 아니라,
AI가 도구를 안전하게 이해하고 호출할 수 있도록 돕는 또 하나의 인터페이스로 이해하게 되었습니다.

이번 실습을 한 문장으로 정리하면 이렇습니다.

작은 캘린더 하나로, 사람이 쓰는 UI에서 프로그램이 쓰는 API를 거쳐 AI가 쓰는 MCP까지 인터페이스의 확장을 경험했다.

도움 받은 글

• 이재엽 스터디장님 캘린더 MCP 사례