본문으로 건너뛰기

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 엔드포인트 개요

메서드 + 경로

동작

GET /notes

노트 목록 조회

GET /notes/:id

특정 노트 상세

POST /notes

새 노트 생성

PUT /notes/:id

노트 수정

DELETE /notes/:id

노트 삭제

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가 자연어로 그 창구를 골라 쓰게 하는 다리.

결정 과정 요약

대화하며 좁혀온 선택들:

  1. 무엇을 만드나 → 캘린더가 아니라 개인 노트/대화 저장 서버.

    같은 bun+hono+sqlite 패턴, 데이터만 notes로.

  2. 도구는 → save_note(저장), search_notes(검색) 두 개로 시작.

  3. 검색 방식 → 우선 SQL 키워드 검색으로 무료 시작.

    부족하면 나중에 로컬 임베딩 의미 검색을 얹는다. (둘 다 비용 0)

  4. 어디서 돌리나 → (미정 — 아래 분기에서 택1)

    • 집 PC(WSL) + Tailscale 사설 → 폰·랩탑 직접 연결용

    • 집 PC(WSL) + Tailscale Funnel + 보호 토큰 → claude.ai 커넥터용

    • 클라우드 배포 + 보호 토큰 → PC 안 켜둬도 + 커넥터용

  5. 인증 → 공개로 열면 보호 토큰(헤더 검사) 필수. 개인용은 토큰 방식으로 충분.

  6. 비용 → 위 구성만이면 0원.

    (Console API 키/외부 임베딩 API를 안 넣는 한)

  7. 파일 → 대화는 "파일"이 아니라 텍스트로 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 → 본문 받아 INSERT

  • GET /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: 코드 전문은 코드블록에 감싸서 작성해주세요. ( / 을 눌러 '코드 블록'을 선택)

(내용 입력)

결과와 배운 점

배운 점과 나만의 꿀팁을 알려주세요.

과정 중에 어떤 시행착오를 겪었나요?

도움이 필요한 부분이 있나요?

앞으로의 계획이 있다면 들려주세요.

(내용 입력)

도움 받은 글 (옵션)

참고한 지피터스 글이나 외부 사례를 알려주세요.

(내용 입력)

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기