MCP 접근 (AI 에이전트)

최근 변경 사항

MCP는 이제 iPhone에서도 완전히 사용할 수 있어요(웹 앱과 더불어). iPhone 화면은 웹 화면을 그대로 따라가며 지원되는 모든 AI 클라이언트의 동일한 설정 스니펫을 포함해요.

Pro 요금제 이상

MCP 접근은 Pro 또는 Ultra 요금제가 필요해요. 두 요금제 모두 전체 읽기 + 쓰기 접근(27개 도구)을 받고, 원하면 읽기 전용 모드로 전환할 수 있어요.

MCP(Model Context Protocol)는 AI 코딩 어시스턴트와 자동화 도구를 TellDone 데이터에 직접 연결할 수 있게 해줘요. 연결되면 AI 에이전트가 노트, 할 일, 이벤트, 리포트, 태그, 변경 기록을 읽을 수 있고 항목을 만들고 업데이트하고 삭제하고 복원할 수 있어요. 총 27개 도구가 있어요: 데이터 읽기용 10개, 쓰기용 17개.

iPhone 앱(설정 → 연동 → AI 에이전트)과 웹 앱(설정 → AI 에이전트) 모두에서 사용할 수 있어요.

연결하는 두 가지 방법

AI 클라이언트를 인증하는 방법은 두 가지이고, 둘 다 완전히 지원돼요.

1. OAuth 2.1(권장) - 표준 "TellDone으로 로그인" 동의 흐름이에요. Claude Desktop의 커넥터 UI와 Claude.ai가 사용하는 방식이에요. 토큰을 복사할 필요 없이 TellDone 계정으로 로그인하고 클라이언트가 요청하는 권한을 승인하면 돼요.
2. 베어러 토큰 - 설정에서 개인 접근 토큰을 복사해 클라이언트 구성에 붙여넣어요. 스크립트, CLI, 그리고 OAuth 흐름이 내장되지 않은 클라이언트에 가장 간단해요.

클라이언트	권장
Claude Desktop / Cowork	OAuth - MCP URL로 커스텀 커넥터를 추가한 다음 로그인
Claude Code (CLI)	둘 다 가능 - claude mcp add가 브라우저에서 OAuth를 안내하거나, 토큰 방식으로 Bearer 헤더 추가
스크립트나 직접 만든 코드	베어러 토큰 - 자동화하기 가장 간단
등록된 커넥터 목록에서만 고를 수 있는 클라이언트	지금은 베어러 토큰이나 mcp-remote 브리지를 사용하세요 - TellDone은 아직 어떤 커넥터 디렉터리에도 등록되지 않았어요

요금제 요구 사항

요금제	MCP
Free	잠김
Basic	잠김
Pro	Read + Write (27개 도구) - Read-only 모드로 전환 가능
Ultra	Read + Write (27개 도구) - Read-only 모드로 전환 가능

인앱 화면

AI 에이전트 화면은 요금제와 MCP 활성화 여부에 따라 세 가지 상태가 있어요.

잠김 (Free와 Basic)

Free나 Basic 요금제라면 화면이 MCP가 무엇을 하는지 설명하고 업그레이드 버튼을 보여줘요. 누르면 Pro나 Ultra로 이동할 수 있는 페이월이 열려요.

비활성화 (Pro와 Ultra, 기능 꺼짐)

Pro나 Ultra인데 아직 MCP를 켜지 않았다면 화면이 요금제로 할 수 있는 것의 짧은 요약(도구 수, 접근 모드, 할당량)과 활성화 버튼을 보여줘요. 누르면 연결 토큰을 생성하고 연동을 시작해요.

활성화됨

활성화되면 화면이 AI 클라이언트를 연결하는 데 필요한 모든 것을 보여줘요.

• 모드 토글 - Ultra에서는 Read-only와 Read + Write 사이를 전환할 수 있어요. Pro에서는 모드가 Read + Write로 고정돼요.
• 토큰을 표시하거나 숨기는 눈 토글과 복사 버튼이 있는 접근 토큰 행.
• Claude Code, Cursor, Windsurf, Other 탭이 있는 설정 선택기. 일치하는 코드 스니펫이 탭 아래에 나타나요. 복사해서 AI 클라이언트에 붙여넣기만 하면 돼요.
• 재생성 버튼 - 토큰을 즉시 회전하고 이전 토큰을 사용하는 모든 활성 세션을 끊어요.
• 비활성화 버튼 - MCP를 끄고 토큰을 삭제해요. 나중에 다시 활성화할 수 있지만 새 토큰이 발급돼요.

팁

연결 토큰을 비공개로 유지하세요. 토큰을 가진 사람은 누구나 TellDone 데이터에 접근할 수 있어요. 토큰이 유출되었다고 의심되면 재생성을 사용하세요.

활성화 방법

두 플랫폼 중 하나에서 MCP를 구성할 수 있어요.

• iPhone: 설정 → 연동 → AI 에이전트 (MCP)
• 웹: app.telldone.app → 설정 → AI 에이전트

단계:

1. 활성화를 누르세요.
2. 접근 모드를 선택하세요(Ultra 전용 - Pro는 항상 Read + Write).
3. 눈과 복사 아이콘을 사용해 토큰을 표시하고 복사하세요.
4. 설정 섹션에서 도구를 선택하세요(Claude Code, Cursor, Windsurf, 또는 Other).
5. 스니펫을 AI 클라이언트 구성에 붙여넣으세요.

OAuth로 연결

OAuth는 Claude Desktop, Claude.ai, Cowork, Claude Code에 권장하는 방식이에요. 토큰을 복사해 옮기는 대신 TellDone 계정으로 로그인해요.

OAuth용 MCP URL: https://api.telldone.app/mcp/user (뒤에 /mcp를 붙이지 마세요 - 그건 아래 베어러 토큰 방식에만 쓰는 다른 URL이에요)

Claude Desktop / Cowork

1. 클라이언트에서 Add custom connector를 선택하세요.
2. 서버 URL을 입력하세요: https://api.telldone.app/mcp/user
3. 클라이언트가 브라우저에서 TellDone 동의 페이지를 열어요. 어떤 앱이 접근을 요청하는지, 정확히 어떤 권한을 원하는지, 그리고 로그인 폼이 보여요.
4. TellDone 계정 이메일과 비밀번호로 로그인한 다음 Allow를 누르세요.
5. 클라이언트가 접근 토큰을 자동으로 받아 연결돼요. 복사할 토큰이 없어요.

노트

동의 페이지의 로그인은 TellDone 계정 이메일과 비밀번호를 사용해요. 계정에 Apple이나 Google 로그인만 있고 비밀번호를 설정하지 않았다면 지금은 아래 베어러 토큰 방식을 사용하세요.

Claude Code

OAuth(브라우저 로그인이 열려요):

claude mcp add --transport http telldone https://api.telldone.app/mcp/user

Claude Code가 OAuth 흐름을 자동으로 찾아내지만 첫 호출에서 로그인까지 해주지는 않아요. Claude Code 안에서 /mcp를 실행하고 Authenticate를 선택하면 브라우저 로그인이 열려요. 그 다음부터는 접근 토큰을 알아서 갱신해줘서 따로 관리할 게 없어요.

베어러 토큰(브라우저 없이, 헤드리스 환경에 좋아요):

claude mcp add telldone --transport http \
  https://api.telldone.app/mcp/user/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

YOUR_TOKEN은 앱에서 가져오세요: 설정 → 연동 → AI 에이전트 → 토큰 복사(위 활성화 방법 참고).

베어러 토큰으로 연결

OAuth를 기본 지원하지 않는 클라이언트(Cursor, Windsurf 등)에서는 개인 접근 토큰을 클라이언트 구성에 직접 붙여넣으세요. 아래 모든 예시에서 YOUR_TOKEN을 설정의 토큰으로 바꾸세요.

Cursor

.cursor/mcp.json에 추가하세요.

{
  "mcpServers": {
    "telldone": {
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Windsurf

.codeium/windsurf/mcp_config.json에 추가하세요.

{
  "mcpServers": {
    "telldone": {
      "serverUrl": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Other

인앱 선택기가 Other 아래 그룹화한 클라이언트에는 다음 스니펫을 사용하세요.

Codex

codex.json에 추가하세요.

{
  "mcpServers": {
    "telldone": {
      "type": "http",
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

OpenClaw

설정 > MCP Servers > 추가:

• 이름: TellDone
• URL: https://api.telldone.app/mcp/user/mcp
• 인증: Bearer YOUR_TOKEN

다른 MCP 클라이언트

HTTP를 통해 MCP를 지원하는 어떤 도구든 연결할 수 있어요. 엔드포인트 https://api.telldone.app/mcp/user/mcp와 Bearer YOUR_TOKEN 인증 헤더를 사용하세요.

대체 인증 헤더

클라이언트나 프록시가 Authorization 헤더를 예약한다면(예: 일부 Smithery 스타일 게이트웨이), 대신 X-MCP-Token: YOUR_TOKEN으로 토큰을 보내세요. 두 헤더 모두 작동해요. 둘 다 있으면 Authorization이 우선해요.

연결 테스트

간단한 cURL 명령으로 토큰이 작동하는지 확인할 수 있어요.

curl -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

성공 응답은 사용 가능한 모든 도구를 나열해요.

권한 (스코프)

OAuth 연결에는 스코프가 적용돼요. 로그인 중에 클라이언트가 무엇을 요청하는지 정확히 보고 직접 승인해요.

스코프	앱이 할 수 있는 것
notes:read	노트 읽기, 검색, 전체 노트 상세 열기
notes:write	노트 생성, 편집, 삭제(그리고 음성 노트 파이프라인 실행)
tasks:read / tasks:write	할 일 읽기 / 생성, 편집, 완료, 삭제
events:read / events:write	이벤트 읽기 / 생성, 편집, 삭제
reports:read	일간, 주간, 월간, 연간 리포트 읽기
tags:read / tags:write	태그 목록 보기 / 태그 생성과 이름 변경
profile:read	프로필과 구독 정보 읽기
offline_access	자리를 비운 동안에도 연결 유지(리프레시 토큰을 발급해 매 세션마다 로그인하지 않아도 돼요)

스코프는 상한선이지 보장이 아니에요. notes:read만 가진 연결은 무엇을 시키든 쓰기 도구를 호출할 수 없어요. 요금제는 스코프 위에 놓인 두 번째 관문이에요.

베어러 토큰 연결에는 개별 스코프가 없어요. 요금제의 읽기/쓰기 모드로만 통제돼요.

할 수 있는 것

읽기 도구 (10) - Pro와 Ultra

도구	작동
get_notes	필터(태그, 날짜 범위, 텍스트 검색)로 노트 나열
get_note	자식 할 일, 이벤트, 전체 전사본이 있는 단일 노트 보기
get_notes_full	한 번의 호출로 임베디드된 할 일과 이벤트가 있는 여러 노트 가져오기
get_tasks	상태(할 일, 완료, 전체), 태그, 날짜로 필터링한 할 일 나열
get_events	캘린더 이벤트 나열, 날짜 범위로 필터링
get_reports	일간, 주간, 월간, 연간 리포트 읽기(전체 마크다운)
get_tags	사용량으로 정렬된 모든 태그 보기
get_profile	계정 정보와 사용량 통계 보기
search	노트, 할 일, 이벤트 전반 검색(노트는 텍스트 + 의미 검색)
get_change_log	노트, 할 일, 이벤트의 편집 기록과 각 편집의 취소 여부 보기

팁

search 도구는 노트에 대한 의미 검색을 지원해요. 키워드뿐만 아니라 의미로 결과를 찾아요. 예를 들어 "예산에 관한 회의"를 검색하면 "예산"이라는 단어가 포함되지 않은 재정 논의에 대한 노트도 찾아내요.

쓰기 도구 (17) - Pro와 Ultra

도구	작동
process_note	전체 AI 파이프라인 - 텍스트나 오디오를 보내면 할 일, 이벤트, 태그가 있는 노트를 받아요
create_note	일반 텍스트 노트 추가(AI 분석 없음)
create_task	우선순위, 마감일, 알림, 태그가 있는 할 일 추가
create_event	날짜, 시간, 장소, 알림, 참석자, 반복이 있는 캘린더 이벤트 추가
update_note	노트 제목, 요약, 유형, 태그, 우선순위, 상태 변경
update_task	할 일 제목, 설명, 우선순위, 마감일, 알림, 태그, 상태 변경
complete_task	할 일을 완료로 표시
update_event	이벤트 세부 정보, 시간, 장소, 알림, 참석자, 반복, 태그, 상태 변경
delete_note	노트와 모든 연결된 할 일, 이벤트 삭제
delete_task	할 일 삭제
delete_event	이벤트 삭제
undo_change_log_entry	추적된 편집 하나를 취소 - AI가 만든 것이든 직접 만든 것이든 - 해당 필드의 이전 값을 복원
restore_entity	삭제되거나 보관된 노트, 할 일, 이벤트를 되살리기
create_tag	새 태그를 만들거나, 자동 제안된 태그를 영구 태그로 전환
set_tag_pinned	태그를 고정하거나 고정 해제해서 맨 위로 정렬
delete_tag	태그 제거(restore_tag로 복원 가능)
restore_tag	삭제된 태그를 되살리기

모든 쓰기와 삭제 작업은 실시간 동기화를 통해 연결된 기기(폰, 웹 앱)에 즉시 나타나요.

도구 참조

get_notes

선택적 필터링으로 노트 나열. 날짜 필터는 created_at이 아닌 recorded_at(음성 노트를 녹음한 때)를 사용해요.

매개변수	유형	기본값	설명
limit	int	20	반환할 노트 수(최대 50)
offset	int	0	이 만큼의 노트 건너뛰기(페이지네이션, 최대 10000)
tags	string	-	태그로 필터링, 쉼표로 구분(아무거나 일치)
search	string	-	제목과 요약에 대한 텍스트 검색
date_from	string	-	시작 날짜, YYYY-MM-DD(포함)
date_to	string	-	종료 날짜, YYYY-MM-DD(미포함)
standalone_only	bool	false	true이면 후속 노트(상위 노트/작업/이벤트에 연결된 노트)를 숨기고 독립적인 노트만 반환해요

반환: id, title, summary, type, tags, priority, status, recorded_at, created_at이 있는 노트 목록.

get_note

전체 전사본과 모든 연결된 할 일 및 이벤트가 있는 단일 노트 가져오기.

매개변수	유형	설명
note_id	string	노트의 UUID

반환: title, summary, transcript, type, tags, priority, status, metadata, created_at, 그리고 tasks[]와 events[] 배열이 있는 노트.

transcript_speakers(화자가 여러 명인 회의의 화자 표시 전사 발화 - 그 외에는 null), speaker_count(녹음이 화자별로 분리된 경우가 아니면 null), parent_note_id/parent_task_id/parent_event_id(이 노트가 다른 항목의 후속 편집일 때 설정됨)도 반환해요. 각 tasks[]/events[] 항목에는 reminders_at/recurrence_rule(할 일) 또는 reminder_minutes/attendees/recurrence_rule(이벤트)도 포함돼요.

get_notes_full

한 번의 호출로 할 일과 이벤트가 있는 여러 노트 가져오기. get_notes와 같은 필터지만 각 노트에 임베디드된 tasks[]와 events[]가 포함돼요.

매개변수	유형	기본값	설명
limit	int	10	노트 수(최대 20)
offset	int	0	이 만큼의 노트 건너뛰기
tags	string	-	태그로 필터링
date_from	string	-	시작 날짜, YYYY-MM-DD
date_to	string	-	종료 날짜, YYYY-MM-DD
standalone_only	bool	false	true이면 후속 노트(상위 노트/작업/이벤트에 연결된 노트)를 숨기고 독립적인 노트만 반환해요

get_tasks

필터링으로 할 일 나열.

매개변수	유형	기본값	설명
status	string	"todo"	필터: todo, done, all
limit	int	30	할 일 수(최대 100)
offset	int	0	이 만큼의 할 일 건너뛰기
tags	string	-	태그로 필터링, 쉼표로 구분
date_from	string	-	시작 날짜, YYYY-MM-DD(마감일 기준 필터링; 마감일 없는 할 일은 제외)
date_to	string	-	종료 날짜, YYYY-MM-DD(마감일 기준 필터링; 마감일 없는 할 일은 제외)

반환: id, title, description, status, priority, tags, deadline, reminder_at, reminders_at, completed_at, completed_by, source, created_at이 있는 할 일 목록. reminder_at은 하위 호환성을 위해 reminders_at의 첫 번째 항목을 반영해요 - 할 일의 모든 알림을 보려면 reminders_at을 사용하세요.

get_events

날짜 범위 필터링으로 캘린더 이벤트 나열.

매개변수	유형	기본값	설명
limit	int	30	이벤트 수(최대 100)
offset	int	0	이 만큼의 이벤트 건너뛰기
date_from	string	-	시작 날짜, YYYY-MM-DD(이벤트 시작 시간으로 필터링)
date_to	string	-	종료 날짜, YYYY-MM-DD

반환: id, title, description, status, start_at, end_at, location, is_all_day, tags, note_id, reminder_minutes, attendees, recurrence_rule, created_at이 있는 이벤트 목록.

get_reports

전체 마크다운 콘텐츠가 있는 AI 생성 리포트 가져오기.

매개변수	유형	기본값	설명
report_type	string	"daily"	유형: daily, weekly, monthly, yearly
limit	int	5	리포트 수(최대 10)

반환: id, type, period_start, period_end, content_md, created_at이 있는 리포트 목록.

노트

월간 리포트는 3,000-5,000단어가 될 수 있어요. AI 도구의 컨텍스트 창이 좁다면 limit=1을 사용하세요.

get_tags

고정된 것을 먼저, 그 다음 사용량 카운트로 정렬된 모든 태그 가져오기.

매개변수 없음. 각각 tag, usage_count, is_pinned, is_manual이 있는 최대 100개 태그를 반환해요.

get_profile

계정 정보와 사용량 통계 가져오기.

매개변수 없음. email, display_name, locale, transcription_locale, timezone, subscription, mcp_mode, created_at, stats(노트/할 일/이벤트 카운트)를 반환해요.

search

노트, 할 일, 이벤트 전반을 한 번에 검색. 노트는 텍스트 검색과 의미 검색(AI 임베딩으로 의미로 결과 찾기)을 모두 지원해요.

매개변수	유형	기본값	설명
query	string	필수	검색 텍스트(최대 500자)
limit	int	20	유형당 최대 결과(최대 20)
semantic	bool	true	노트에 대한 의미 검색 활성화

유형별로 그룹화된 결과 반환: notes[], tasks[], events[]. 각 결과에 id, type, title, detail, created_at이 있어요.

더 빠른 텍스트 전용 검색을 위해 semantic=false를 설정하세요.

get_change_log

노트, 할 일, 이벤트의 편집 기록 보기 - AI가 만든 모든 후속 편집과 직접 만든 모든 수동 편집을 최신순으로 보여줘요.

매개변수	유형	기본값	설명
entity	string	필수	notes, tasks, 또는 events
entity_id	string	필수	항목의 UUID
include_manual	bool	false	AI가 만든 것뿐 아니라 직접 만든 수동 편집도 포함

반환: id(취소 시 entry_id로 사용), field_name, old_value, new_value, source(follow_up, smart_context, 또는 manual), origin_note_id, edited_at, reverted_at(취소되면 설정됨)이 있는 변경 항목 목록.

process_note (Pro와 Ultra)

전체 AI 파이프라인 - 앱에서 녹음하는 것과 동일하게 작동해요. 텍스트나 오디오를 보내면 TellDone이 음성 인식하고, AI로 분석하고, 추출된 할 일, 이벤트, 태그, 임베딩이 있는 구조화된 노트를 만들어요.

이 도구는 비동기예요. audio_id와 함께 즉시 반환되고 백그라운드에서 처리돼요. 결과는 연결된 기기로 실시간 동기화로 도착하거나 get_notes()로 폴링할 수 있어요.

매개변수	유형	설명
text	string	분석할 텍스트(오디오가 제공되지 않으면 음성 인식 건너뜀)
audio_base64	string	Base64 인코딩 오디오 파일(최대 50MB, 음성 인식 트리거)
audio_format	string	m4a, ogg, wav, mp3, aac, webm(기본값: m4a)
parent_task_id	string	후속하는 할 일의 UUID
parent_note_id	string	후속하는 노트의 UUID
parent_event_id	string	후속하는 이벤트의 UUID

text 또는 audio_base64 중 하나(또는 둘 다 - 오디오가 있으면 음성 인식이 우선)를 제공해야 해요.

반환: {"audio_id": "...", "status": "processing", "mode": "text-only"} 또는 오디오가 제공되었다면 "mode": "audio+stt".

노트

process_note는 요금제의 할당량(일 업로드, 월 노트, 최대 텍스트 길이)에 따라요. 현재 사용량을 확인하려면 get_profile을 사용하세요.

create_note (Pro와 Ultra)

일반 텍스트 노트 즉시 생성. AI 분석을 트리거하지 않아요. 할 일이나 이벤트가 추출되지 않아요. 할 일/이벤트 추출이 있는 전체 AI 분석을 위해서는 대신 process_note를 사용하세요.

매개변수	유형	한도	설명
title	string	200자	필수
summary	string	1000자	선택. 짧은 요약(1-3문장). 리포트 프롬프트에 포함되니 간결하게 유지하세요
transcript	string	요금제별	선택. 노트 상세에 표시되는 장문 본문. 리포트에 포함되지 않아요. 한도: Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000자
type	string	-	선택. task, idea, info(기본값), status, meeting, event, reflection
tags	string	20개 태그	쉼표로 구분, 선택

create_task (Pro와 Ultra)

새 할 일 생성.

매개변수	유형	한도	설명
title	string	200자	필수
description	string	2000자	선택
priority	string	-	low, medium(기본값), high
deadline	string	-	YYYY-MM-DD, 선택
reminder_at	string	-	ISO 8601 날짜시간(예: 2026-04-15T09:00:00Z), 선택
tags	string	20개 태그	쉼표로 구분, 선택
note_id	string	-	할 일을 부모 노트에 연결하는 UUID, 선택

create_event (Pro와 Ultra)

캘린더 이벤트 생성.

매개변수	유형	한도	설명
title	string	200자	필수
start_at	string	-	ISO 8601 날짜시간, 필수
end_at	string	-	ISO 8601 날짜시간(기본값: 시작 + 1시간)
description	string	2000자	선택
location	string	200자	선택
is_all_day	bool	-	기본값: false
tags	string	20개 태그	쉼표로 구분, 선택
reminder_minutes	string	-	이벤트 전 분, 쉼표로 구분(예: 15,60), 선택
attendees	string	-	이름이나 이메일, 쉼표로 구분, 선택
recurrence_rule	string	-	RRULE 문자열(예: FREQ=WEEKLY;BYDAY=MO,WE,FR), 선택
note_id	string	-	이벤트를 부모 노트에 연결하는 UUID, 선택

update_note (Pro와 Ultra)

기존 노트의 하나 이상의 필드 업데이트. 제공한 필드만 변경돼요.

매개변수	유형	설명
note_id	string	필수, 노트의 UUID
title	string	새 제목(최대 200자)
summary	string	새 요약(최대 1000자, 지우려면 공백 " " 전달)
transcript	string	새 전사본(요금제별 한도, 지우려면 공백 " " 전달)
type	string	task, idea, info, status, meeting, event, reflection
tags	string	쉼표로 구분된 태그(기존 태그 모두 대체, 최대 20)
priority	string	low, medium, high
status	string	active 또는 archived

주의

음성 파이프라인으로 만들어진 노트의 경우 transcript는 원본 음성 인식 출력이에요. 덮어쓰면 정본 출처가 대체돼요. 원본을 보존하고 싶다면 추가 입력을 고려하세요.

update_task (Pro와 Ultra)

기존 할 일의 하나 이상의 필드 업데이트. 제공한 필드만 변경돼요.

매개변수	유형	설명
task_id	string	필수, 할 일의 UUID
title	string	새 제목
description	string	새 설명(지우려면 공백 " " 전달)
priority	string	low, medium, high
deadline	string	YYYY-MM-DD(지우려면 공백 전달)
status	string	todo 또는 done
tags	string	쉼표로 구분된 태그(기존 태그 모두 대체, 최대 20)
reminder_at	string	ISO 8601 날짜시간(지우려면 공백 전달)

status를 done으로 설정하면 할 일이 언제 어떻게 완료되었는지도 기록돼요.

complete_task (Pro와 Ultra)

할 일을 완료로 표시하는 단축.

매개변수	유형	설명
task_id	string	필수, 할 일의 UUID

할 일이 존재하지 않거나 이미 완료된 경우 오류를 반환해요.

update_event (Pro와 Ultra)

기존 이벤트의 하나 이상의 필드 업데이트. 제공한 필드만 변경돼요.

매개변수	유형	설명
event_id	string	필수, 이벤트의 UUID
title	string	새 제목
description	string	새 설명(지우려면 공백 전달)
start_at	string	새 시작 시간(ISO 8601)
end_at	string	새 종료 시간(ISO 8601)
location	string	새 장소(지우려면 공백 전달)
status	string	confirmed, tentative, cancelled
tags	string	쉼표로 구분된 태그(기존 태그 모두 대체, 최대 20)
is_all_day	string	"true" 또는 "false"
reminder_minutes	string	이벤트 전 분, 쉼표로 구분(예: 15,60)
attendees	string	이름이나 이메일, 쉼표로 구분
recurrence_rule	string	RRULE 문자열(지우려면 공백 전달)

delete_note (Pro와 Ultra)

노트 삭제. 이 노트에서 만들어진 모든 할 일과 이벤트도 삭제돼요.

매개변수	유형	설명
note_id	string	필수, 노트의 UUID

delete_task (Pro와 Ultra)

할 일 삭제.

매개변수	유형	설명
task_id	string	필수, 할 일의 UUID

delete_event (Pro와 Ultra)

이벤트 삭제.

매개변수	유형	설명
event_id	string	필수, 이벤트의 UUID

undo_change_log_entry (Pro와 Ultra)

추적된 편집 하나를 취소해요 - AI가 (후속 녹음으로) 만든 편집이든 직접 만든 편집이든, 해당 필드를 그 편집 이전의 값으로 되돌려요.

매개변수	유형	설명
entity	string	필수, notes, tasks, 또는 events
entity_id	string	필수, 항목의 UUID
entry_id	string	필수, get_change_log에서 얻은 변경 항목의 id

반환: {"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}. 같은 항목을 두 번 취소하면 오류를 반환해요 - 이미 취소된 상태예요.

restore_entity (Pro와 Ultra)

삭제되거나 보관된 노트, 할 일, 이벤트를 되살려요.

매개변수	유형	설명
entity	string	필수, notes, tasks, 또는 events
entity_id	string	필수, 항목의 UUID

반환: 복원된 항목을 JSON으로.

create_tag (Pro와 Ultra)

새 태그를 만들거나, 기존의 자동 제안된 태그를 영구 태그로 전환해요.

매개변수	유형	설명
tag	string	필수, 1-50자(소문자로 저장)
category	string	선택

set_tag_pinned (Pro와 Ultra)

태그를 고정하거나 고정 해제해서 태그 목록 맨 위로 정렬되게 해요.

매개변수	유형	설명
tag	string	필수
pinned	bool	필수

/ 문자가 포함된 태그는 고정할 수 없어요.

delete_tag (Pro와 Ultra)

태그를 제거해요. restore_tag로 되살릴 수 있어요.

매개변수	유형	설명
tag	string	필수

restore_tag (Pro와 Ultra)

삭제된 태그를 되살려요.

매개변수	유형	설명
tag	string	필수

입력 한도

필드	최대 길이	사용처
title	200자	노트, 할 일, 이벤트 생성/업데이트
description	2,000자	할 일, 이벤트 생성/업데이트
summary	1,000자(하드)	노트 생성/업데이트. 리포트 프롬프트에 포함, 토큰 비용 제어를 위해 짧게 유지
transcript	요금제별: Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000	노트 생성/업데이트. 장문 본문, 리포트에 없음
location	200자	이벤트 생성/업데이트
tags	20개 태그	노트, 할 일, 이벤트 생성/업데이트
search query	500자	검색
audio_base64 (디코딩됨)	50 MB	process_note

한도를 초과하면 도구가 "title too long (max 200 chars, got 250)" 같은 오류 메시지를 반환해요.

오류 처리

모든 도구가 JSON을 반환해요. 오류는 다음 형식을 사용해요.

{"error": "description of what went wrong"}

일반적인 오류:

오류	발생 시점
"MCP access is read-only..."	읽기 전용 모드에서 쓰기 도구 호출
"Invalid note_id format"	UUID가 아닌 문자열을 ID로 전달
"Note not found"	ID가 존재하지 않거나 다른 사용자에게 속함
"Task not found or already completed"	존재하지 않거나 이미 완료된 할 일에 complete_task
"title too long (max 200 chars, got N)"	입력 한도 초과
"Too many tags (max 20)"	20개 이상의 태그 제공

HTTP 수준 오류:

코드	의미
401	잘못되거나 누락된 Bearer 토큰
403	MCP 비활성화 또는 요금제가 MCP를 허용하지 않음
429	속도 제한 초과(초당 5 요청, 버스트 최대 20)

사용 예시

모든 예시는 MCP JSON-RPC 프로토콜과 함께 cURL을 사용해요. YOUR_TOKEN을 연결 토큰으로 바꾸세요.

데이터 읽기

# Get your profile and stats
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_profile"}}'

# List recent notes (limit 5, from April 2026)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_notes","arguments":{"limit":5,"date_from":"2026-04-01"}}}'

# Search notes (hybrid text + semantic)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"project deadline","limit":5}}}'

데이터 쓰기 (Pro와 Ultra)

# Process a note through full AI pipeline (extracts tasks + events)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call",
       "params":{"name":"process_note","arguments":{"text":"Need to buy groceries tomorrow. Meeting with Katie at 3pm at the cafe to discuss the project."}}}'

# Create a task with deadline and reminder
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Review PR","priority":"high","deadline":"2026-04-15","reminder_at":"2026-04-15T09:00:00Z","tags":"dev"}}}'

# Create a recurring event with reminders and attendees
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":12,"method":"tools/call",
       "params":{"name":"create_event","arguments":{"title":"Team standup","start_at":"2026-04-12T10:00:00Z","reminder_minutes":"15","attendees":"Katie,John","recurrence_rule":"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR","tags":"meeting"}}}'

# Complete a task
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":13,"method":"tools/call",
       "params":{"name":"complete_task","arguments":{"task_id":"<task-uuid>"}}}'

성공 응답은 다음과 같아요.

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

노트

쓰기와 업데이트 도구는 id, title, status만 있는 최소 응답을 반환해요. 쓰기 후 전체 세부 정보(태그, 우선순위, 마감일 등)를 얻으려면 get_tasks나 get_note 같은 후속 읽기 호출을 하세요.

토큰 관리

작업	방법
토큰 보기	iPhone 설정 → 연동 → AI 에이전트(또는 웹 설정 → AI 에이전트), 눈 아이콘 누름
토큰 복사	토큰 옆의 복사 아이콘 누름
재생성	재생성을 누르고 확인. 이전 토큰이 즉시 작동을 멈추고 모든 활성 세션이 끊겨요
모드 변경	Ultra 전용 - Read-only와 Read + Write 사이 전환. Pro에서는 모드가 Read + Write로 고정
비활성화	비활성화를 누르고 확인. 토큰이 삭제되고 모든 연결이 멈춰요. 나중에 다시 활성화할 수 있어요(새 토큰이 발급돼요)

AI 에이전트에게 물어볼 수 있는 것

연결되면 AI 도구에 다음과 같은 것들을 물어볼 수 있어요.

하루 검토:

• "오늘 무엇을 작업했지?"
• "이번 주 노트 보여줘"
• "어떤 할 일이 연체됐지?"

할 일 관리:

• "할 일 만들기: 분기 보고서 검토, 높은 우선순위, 금요일 마감"
• "Figma 할 일 완료로 표시해"
• "지금 어떤 할 일을 하고 있지?"

검색과 분석:

• "마케팅 전략에 대한 모든 노트 찾아"
• "다음 주에 어떤 이벤트가 있지?"
• "지난 주의 일간 리포트 요약해 줘"

미리 계획하기:

• "이벤트 만들기: 내일 오전 10시 팀 스탠드업"
• "이번 주 캘린더에 뭐가 있지?"
• "상위 태그 보여줘 - 가장 많은 시간을 어디에 쓰지?"

AI 에이전트는 노트, 할 일, 이벤트, 리포트에 완전한 접근 권한을 가지고 있어요. 데이터를 읽고, 만들고, 업데이트하고, 삭제할 수 있고, 여러 도구의 정보를 결합해 복잡한 질문에 답할 수 있어요.

중요한 노트

• 노트를 만드는 두 가지 방법 - create_note는 일반 텍스트 노트를 즉시 만들어요(AI 분석 없음). process_note는 전체 AI 파이프라인(앱에서 녹음하는 것과 동일)을 실행해요. 텍스트를 분석하고, 할 일과 이벤트를 추출하고, 태그와 임베딩을 생성해요. TellDone이 대신 생각해주길 원할 때는 process_note를 사용하세요.
• 연동 동기화 없음 - MCP로 만들거나 업데이트된 항목은 Webhook 자동화나 연동 동기화(Todoist, Notion)를 트리거하지 않아요. 다음 동기화에 앱에 나타나요.
• 의미 검색은 도구에 따라 달라요 - process_note로 만든 노트는 임베딩을 받고 의미 검색에 나타나요. create_note로 만든 노트는 임베딩을 받지 않아 텍스트 검색에만 나타나요.
• 쓰기 응답은 최소 - 생성과 업데이트 도구는 id, title, status만 반환해요. 쓰기 후 모든 필드를 얻으려면 후속 읽기 호출을 하세요.
• 날짜 필터는 UTC 사용 - date_from/date_to 매개변수는 UTC 타임스탬프로 비교돼요. UTC가 아닌 시간대의 사용자에게는 경계 날짜가 인접 날짜의 항목을 포함하거나 제외할 수 있어요.
• 속도 제한 - 초당 5 요청, 버스트는 최대 20까지. 대량 작업의 경우 요청을 분산하세요.

보안

• 각 사용자는 고유한 384비트 연결 토큰을 받아요
• MCP를 비활성화하거나 재생성하면 토큰이 즉시 취소돼요
• 모든 데이터는 계정에 엄격히 격리돼요. 에이전트는 자체 데이터에만 접근할 수 있어요
• 모든 요청은 사용자 범위로 한정돼요. 에이전트가 다른 사용자의 데이터에 접근할 방법이 없어요
• 연결은 속도 제한(초당 5 요청, 버스트 최대 20)이 있는 HTTPS를 사용해요
• OAuth 연결은 PKCE와 일회용 인가 코드, 수명이 짧은 접근 토큰을 사용해요. 앱에서 언제든 연결을 취소할 수 있어요

기술적인 세부 사항(디스커버리 엔드포인트, 토큰 수명, 전체 OAuth 흐름)은 오픈소스 커넥터 레퍼런스 github.com/exp78/telldone-mcp를 참고하거나 https://api.telldone.app/.well-known/oauth-protected-resource를 직접 조회해 보세요.

개인정보와 데이터 흐름

데이터는 연결된 AI 도구에 명시적으로 무언가를 요청할 때만 전송돼요. 예를 들어 노트를 읽거나 수정해 달라고 할 때예요. 도구는 자신이 호출한 특정 요청의 응답만 받고, 그 범위도 승인한 권한으로 제한돼요. 통제권은 사용자에게 있어요. 요금제의 읽기/쓰기 모드를 바꾸거나, 로그인 시 승인하는 OAuth 스코프를 좁히거나, 베어러 토큰을 재생성하고 비활성화할 수 있고, 모두 설정에서 할 수 있어요. 자세한 내용은 개인정보 처리방침을 확인하거나 궁금한 점을 support@telldone.app으로 문의하세요.

문제 해결

증상	원인 / 해결
OAuth 동의 페이지에 "Wrong email or password"라고 나와요	TellDone 계정 이메일과 비밀번호(앱에 로그인할 때 쓰는 것)를 사용하세요. 계정에 Apple이나 Google 로그인만 있고 비밀번호가 없다면 대신 베어러 토큰 방식을 사용하세요.
연결은 됐는데 AI가 아무것도 만들거나 편집하지 못해요	요금제나 모드가 읽기 전용이거나, 연결에 쓰기 스코프가 부여되지 않았어요. 다시 연결해서 승인하거나 설정에서 모드를 확인하세요.
도구에서 "Insufficient scope" 오류가 나요	OAuth 연결에 해당 스코프가 부여되지 않았어요. 다시 연결해서 도구에 필요한 권한을 승인하세요.
도구가 아예 나타나지 않아요	계정에 MCP가 활성화되지 않았거나(설정 → AI 에이전트), 요금제에 MCP가 포함되지 않았어요.
클라이언트가 커넥터 목록에서만 고르게 하는데 TellDone이 없어요	TellDone은 아직 어떤 클라이언트의 커넥터 디렉터리에도 등록되지 않았어요. MCP URL로 커스텀 커넥터로 추가하거나 베어러 토큰 방식을 사용하세요.

같이 보기

• Webhook 자동화 - 외부 서비스로 데이터 자동 전송
• Todoist - 전용 양방향 할 일 동기화
• Notion - 전용 Notion 연동