AI앱 대화 저장 MCP 서버: 데이터 흐름도와 API 엔드포인트 이해하기
2026.06.10
MCP 서버 통합 정리
대화하며 하나씩 정리한 내용 + 데이터 흐름도를 한 문서에 담았다. 하위 페이지에 개념정리(상세)와 실행가이드가 있다.
데이터 흐름도 개요
앱에서 출발한 요청이 서버 바깥(연결 경로)을 지나 서버 안(처리)에 도달하는 순서. [문]이 그 사이의 보호 토큰.
Open optionsauto
[ 서버 바깥 — 연결 경로 ]
앱 (claude.ai 창 · 폰) 입출력 창
│
▼
claude.ai 커넥터 등록된 서버 URL
│
▼
Anthropic 서버 여기서 툴 호출 발생
│
▼
[문] 공개 HTTPS + 보호 토큰 내가 만든 무료 키
│
════════╪═══════════ (바깥 / 안 경계) ═══════════
▼
[ 서버 안 — 처리 ]
MCP 서버 내부 처리 도구 받아 검색 분기
│
┌──┴──┐
▼ ▼
SQL키워드 의미검색
(SQLite) (로컬 임베딩)
비용 0 비용 0
─────────────────────────────────────────
읽는 법: 위쪽(앱→커넥터→Anthropic 서버)은 "누가 내 서버를 부르냐"의 경로이고 출발점은 Anthropic 클라우드. 문(공개 HTTPS+보호 토큰)을 통과해야 서버 안으로 들어간다. 두 검색 갈래는 모두 서버 안에서 끝나 비용 0. Console 키·외부 API를 추가할 때만 과금이 생긴다.
기본 구성 요소
데이터를 저장하고(CRUD) 꺼내보는 작은 서버.
Bun — JS/TS 실행 런타임.
bun:sqlite내장 드라이버로 별도 설치 없이 DB 사용.Hono — 라우터 + 웹 프레임워크. "어떤 URL+메서드 → 어떤 함수" 매칭.
SQLite — 데이터가 저장되는 파일 기반 DB.
API 엔드포인트 개요
메서드 + 경로 | 동작 |
|---|---|
| 노트 목록 조회 |
| 특정 노트 상세 |
| 새 노트 생성 |
| 노트 수정 |
| 노트 삭제 |
MCP 서버의 역할
MCP 서버는 데이터를 직접 저장하지 않는다. AI가 쓸 도구(tool)를 노출하고, AI가 부르면 내부적으로 API를 호출하는 중계자다.
Open optionsauto
Claude ──(MCP)──▶ MCP 서버 ──(HTTP)──▶ 노트 API ──▶ SQLite
save_note— 내용을 받아 저장 (POST /notes)search_notes— 검색해서 꺼냄 (GET /notes)
구분: API 엔드포인트 = 기계가 호출하는 정형 창구 / MCP 서버 = AI가 자연어로 그 창구를 골라 쓰게 하는 다리.
결정 과정 요약
대화하며 좁혀온 선택들:
무엇을 만드나 → 캘린더가 아니라 개인 노트/대화 저장 서버.
같은 bun+hono+sqlite 패턴, 데이터만
notes로.도구는 →
save_note(저장),search_notes(검색) 두 개로 시작.검색 방식 → 우선 SQL 키워드 검색으로 무료 시작.
부족하면 나중에 로컬 임베딩 의미 검색을 얹는다. (둘 다 비용 0)
어디서 돌리나 → (미정 — 아래 분기에서 택1)
집 PC(WSL) + Tailscale 사설 → 폰·랩탑 직접 연결용
집 PC(WSL) + Tailscale Funnel + 보호 토큰 → claude.ai 커넥터용
클라우드 배포 + 보호 토큰 → PC 안 켜둬도 + 커넥터용
인증 → 공개로 열면 보호 토큰(헤더 검사) 필수. 개인용은 토큰 방식으로 충분.
비용 → 위 구성만이면 0원.
(Console API 키/외부 임베딩 API를 안 넣는 한)
파일 → 대화는 "파일"이 아니라 텍스트로
save_note하면 됨.서버가 원하면 .md로 떨어뜨리게 만들 수 있음.
Anthropic 서버 경유 이해하기
오해: "Anthropic에 내 대화가 저장돼 있고 MCP가 그걸 내 서버로 옮긴다" → 틀림
실제:
저장은 자동이 아니라, 내가 "저장해줘" 하면 Claude가 그 순간 대화 내용을
save_note인자로 만들어 보낸다.내용도, 어떤 도구를 부를지 판단도 내 폰이 아니라 Anthropic 클라우드에서 일어난다. 폰/웹은 입출력 창일 뿐.
Open optionsauto
1. 폰/웹: "저장해줘" (입력창)
│
2. Anthropic 클라우드: Claude가 돎 → 도구 호출 발생
│
3. Anthropic 클라우드 ──▶ 내 서버 (커넥터 URL)
│
4. 내 서버 ──▶ SQLite
내 서버를 부르는 쪽은 폰이 아니라 Anthropic 클라우드. 이 사실이 Tailscale 문제로 이어진다.
클라이언트엔 설치할 MCP가 없다: MCP 클라이언트(도구 고르고 호출)는 이미 claude.ai·폰 앱에 내장. 나는 커넥터 설정에 서버 URL 한 줄 등록만 하면 됨.
연결 옵션과 Tailscale
갈래 A — 기기에서 직접 (Tailscale 사설 OK): 폰·랩탑이 내 기기 → 내 서버로 직접. 같은 테일넷이면 공인 IP·포트 개방 없이 통신. 컴퓨터만 켜두면 됨.
갈래 B — claude.ai 커넥터 (Tailscale 사설은 안 됨): 커넥터는 Anthropic 클라우드에서 접속. 사설 주소는 테일넷 밖에서 안 보임.
Open optionsauto
Anthropic 클라우드 ──▶ 공개 인터넷 주소 ✅
Anthropic 클라우드 ──X─ Tailscale 사설 주소 ❌
→ 커넥터로 쓰려면: ① Tailscale Funnel로 공개 HTTPS 노출(PC 켜둬야 함), 또는 ② 클라우드 배포(PC 안 켜둬도 됨). 어느 쪽이든 인증 필수.
Open optionsauto
켜두기 + Tailscale 사설 → 폰·랩탑 직접 연결 OK (커넥터 X)
켜두기 + Funnel(공개) + 토큰 → claude.ai 커넥터 OK
클라우드 배포 + 토큰 → PC 안 켜둬도 + 커넥터 OK
보안 고려 사항
인증 없으면 = 문 활짝 → 아무나 읽고 씀 ❌
인증 있으면 = 문은 보이되 열쇠 필요 → 나만 ✅
방식: 토큰 방식(헤더로 비밀 문자열 검사, 개인용 충분) 또는 OAuth(커넥터 정식 지원, 더 안전). 추가로 요청 횟수 제한을 두면 무차별 시도 방어.
파일 전송의 어려움
이 창에서 만든 다운로드 파일(docx 등) → 다운로드 링크로 줌. 내 서버로 가는 자동 통로 없음.
MCP 도구로 오가는 것 → 가능.
save_file같은 도구를 정의하면 내용을 인자로 전달.
제약: MCP는 본질적으로 텍스트/구조화 데이터. 텍스트·md·json·코드는 자연스럽고, 바이너리는 base64로 가능하나 용량 크면 비효율. → 대화 저장은 굳이 파일로 안 하고 save_note로 텍스트를 넘기면 됨.
작업 순서
아래는 "집 PC + Funnel + 보호 토큰 → claude.ai 커넥터" 기준의 큰 흐름.
클라우드 배포를 택했다면 5단계만 배포로 바뀐다.
준비물 확인
Bun 설치 (WSL 안에)
Tailscale 계정 (Funnel 쓸 경우)
claude.ai 계정 (커넥터 등록용)
프로젝트 뼈대
Open optionsauto
notes-mcp/
├─ db.ts # SQLite 연결 + 테이블 생성
├─ api.ts # hono로 /notes CRUD 엔드포인트
├─ mcp.ts # MCP 서버: save_note / search_notes 도구 정의
├─ auth.ts # 보호 토큰 검사 미들웨어
└─ index.ts # 전부 묶어서 서버 실행
DB와 테이블 설정
노트 한 건 = id, body(본문), created_at(저장 시각), tags(키워드).
bun:sqlite로 파일 하나(notes.db) 만들고 테이블 생성.
API 엔드포인트 설정
POST /notes→ 본문 받아 INSERTGET /notes?q=키워드→WHERE body LIKE '%키워드%'로 검색(나중에)
GET /notes/:id,DELETE /notes/:id등 추가
보호 토큰 인증
길고 추측 불가능한 문자열 하나 생성 (예:
openssl rand -hex 32)모든 요청에서
Authorization헤더의 토큰이 일치할 때만 통과, 아니면 401이 토큰은 내가 만든 비밀 — 어디 등록·결제 대상 아님
공개 주소로 노출
서버를 로컬 포트(예: 3000)에서 실행
Tailscale Funnel로 그 포트를 공개 HTTPS 주소로 노출 →
https://내기기.테일넷.ts.net형태 주소가 생김(클라우드 배포 택했으면: 이 단계 대신 클라우드에 올림 → 자동으로 공개 HTTPS)
MCP 도구 정의
save_note(body, tags?)→ 내부에서POST /notes호출search_notes(query)→ 내부에서GET /notes?q=...호출MCP 서버 엔드포인트를 위 공개 주소 아래 경로로 노출 (예:
/mcp)
커넥터 등록
claude.ai → 설정 → 커넥터 → 커스텀 커넥터 추가
공개 MCP 주소 입력 (예:
https://내기기.테일넷.ts.net/mcp)보호 토큰은 커넥터 인증 설정에 넣음
연결되면 폰 앱에서도 같은 계정으로 사용 가능
테스트
이 창에서 "방금 대화 요약해서 내 노트에 저장해줘" →
save_note호출 확인새 대화에서 "지난번 MCP 얘기 찾아줘" →
search_notes호출 확인
시도하고자 했던 것과 그 이유를 알려주세요.
(내용 입력)
진행 방법
어떤 도구를 사용했고, 어떻게 활용하셨나요?
Tip: 사용한 프롬프트 전문을 꼭 포함하고, 내용을 짧게 소개해 주세요.
Tip: 활용 이미지나 캡처 화면을 꼭 남겨주세요.
Tip: 코드 전문은 코드블록에 감싸서 작성해주세요. ( / 을 눌러 '코드 블록'을 선택)
(내용 입력)
결과와 배운 점
배운 점과 나만의 꿀팁을 알려주세요.
과정 중에 어떤 시행착오를 겪었나요?
도움이 필요한 부분이 있나요?
앞으로의 계획이 있다면 들려주세요.
(내용 입력)
도움 받은 글 (옵션)
참고한 지피터스 글이나 외부 사례를 알려주세요.
(내용 입력)소개
시도하고자 했던 것과 그 이유를 알려주세요.
(내용 입력)
진행 방법
어떤 도구를 사용했고, 어떻게 활용하셨나요?
Tip: 사용한 프롬프트 전문을 꼭 포함하고, 내용을 짧게 소개해 주세요.
Tip: 활용 이미지나 캡처 화면을 꼭 남겨주세요.
Tip: 코드 전문은 코드블록에 감싸서 작성해주세요. ( / 을 눌러 '코드 블록'을 선택)
(내용 입력)
결과와 배운 점
배운 점과 나만의 꿀팁을 알려주세요.
과정 중에 어떤 시행착오를 겪었나요?
도움이 필요한 부분이 있나요?
앞으로의 계획이 있다면 들려주세요.
(내용 입력)
도움 받은 글 (옵션)
참고한 지피터스 글이나 외부 사례를 알려주세요.
(내용 입력)



