연결연결Claude (claude.ai)

MCP Client

Claude (claude.ai)

claude.ai의 Claude를 사용자 지정 커넥터로 OAuth와 memory:read 및 memory:write 범위를 사용해 호스팅된 Streamable HTTP MCP 엔드포인트에 연결합니다.

사전 요구 사항

사용자 지정 커넥터를 지원하는 Claude와 유효한 XMemo 계정을 사용합니다. 연결 정보:

  • 인터페이스: 웹용 Claude(claude.ai), 사용자 지정 커넥터로 연결.
  • 연결 URL: https://xmemo.dev/mcp.
  • 전송 방식: Streamable HTTP (streamable-http).
  • 인증 모드: PKCE와 Dynamic Client Registration(동적 클라이언트 등록)을 사용하는 OAuth 2.0 인증 코드 흐름.
  • 범위: memory:read 및 memory:write.
  • 계정: https://xmemo.dev 의 유효한 XMemo 계정.

XMemo를 사용자 지정 커넥터로 추가

Claude에서 호스팅된 MCP 서버를 추가합니다. 서버 설정은 연결 URL 하나뿐입니다:

  • 1. Claude에서 Customize > Connectors를 열고 Add custom connector를 선택합니다. 바로가기 링크: https://claude.ai/customize/connectors?modal=add-custom-connector.
  • 2. 이름: XMemo.
  • 3. 원격 MCP 서버 URL: https://xmemo.dev/mcp.
  • 4. 커넥터를 추가한 다음 Connect를 클릭해 OAuth를 시작합니다.

OAuth로 액세스 승인

Claude는 Dynamic Client Registration을 통해 자신을 OAuth 클라이언트로 등록하고 브라우저에서 XMemo 인증 페이지를 엽니다. 로그인한 뒤 동의 화면에서 memory:read와 memory:write를 승인하세요. Claude는 이 OAuth 권한 부여에서 자격 증명을 받습니다.

베어러 토큰을 추가하지 마세요

사용자 지정 커넥터에는 API key가 필요하지 않습니다. XMemo API key, XMEMO_KEY 또는 베어러 토큰을 커넥터에 넣지 마세요. 자격 증명과 그 범위는 OAuth 권한 부여가 제공합니다.

대화에서 XMemo 사용 설정

Claude로 돌아가 대화에서 XMemo를 사용 설정합니다. 그러면 Claude가 제목과 안전 주석이 포함된 XMemo 도구를 검색합니다.

실제 recall 호출로 테스트

첫 번째 호출은 읽기 전용으로 하세요. 이는 상태 확인용 자리표시자가 아닌 실제 recall 호출이며 메모리에 쓰지 않습니다.

recall({ query: "connection check", limit: 1 })

예상 응답(리터럴 형태)

호출이 성공하면 아래의 공개 순위 텍스트 형태가 반환됩니다. 참조와 콘텐츠는 승인된 메모리 공간의 실제 값입니다.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

Claude에서 사용할 수 있는 도구

claude-public 프로필에서 Claude는 27개의 도구를 봅니다. 아래에서는 안전 주석별로 분류합니다. 읽기 도구는 데이터를 변경하지 않고, 쓰기 도구는 레코드를 추가, 완료 또는 복원하며, 파괴적 도구는 기존 레코드를 덮어쓰거나 변경하거나 삭제할 수 있습니다. 전용 참조 페이지가 있는 도구에는 링크가 있으며, 나머지 도구는 이 페이지에서만 설명합니다.

읽기 도구

읽기 전용이며 멱등적입니다. 이 도구들은 저장된 데이터를 변경하지 않습니다:

  • get_mcp_identity (Check XMemo connection): 인증된 커넥터 ID와 부여된 메모리 범위를 반환합니다.
  • [search_memory](/docs/tools/search) (Search XMemo memories): 볼 수 있는 범위 지정 메모리 또는 팀 메모리 레코드를 검색합니다.
  • [recall](/docs/tools/recall) (Recall XMemo memory): 가장 관련성 높은 볼 수 있는 메모리를 가져옵니다.
  • [recall_context](/docs/tools/recall-context) (Build XMemo context): 볼 수 있는 메모리로 범위가 제한된 컨텍스트 팩을 만듭니다.
  • memory_overview (Show XMemo memory overview): 볼 수 있는 메모리와 최근 활동을 요약합니다.
  • memory_stats (Show XMemo memory statistics): 볼 수 있는 메모리에 대한 집계 통계를 반환합니다.
  • memory_activity (Show XMemo memory activity): 원시 감사 로그를 노출하지 않고 내 메모리 변경의 안전한 타임라인을 보여 줍니다.
  • analyze_memory_text (Analyze XMemo memory text): 볼 수 있는 메모리 전체에서 단어나 정확한 구문의 출현 횟수를 셉니다.
  • explain_memory (Explain XMemo memory): 볼 수 있는 메모리가 존재하는 이유나 쿼리와 일치한 이유를 설명합니다.
  • list_memory_todos (List XMemo memory TODOs): 메모리 기반 TODO와 작업 항목을 나열합니다. Claude는 이 도구로 TODO를 읽습니다.
  • list_ledger_transactions (List XMemo Ledger transactions): 볼 수 있는 Ledger 레코드를 나열합니다.
  • get_monthly_ledger_summary (Summarize XMemo Ledger by month): 볼 수 있는 Ledger 레코드를 월별로 요약합니다.
  • read_memory (Read Memory): recall 또는 검색이 반환한 참조로 정확한 메모리 하나 또는 승인된 Document의 제한된 페이지를 읽습니다.
  • get_project_context (Get project context): 내가 소유하거나 액세스할 수 있는 프로젝트 하나의 승인된 컨텍스트를 읽습니다.

쓰기 도구

이 도구들은 레코드를 추가, 완료 또는 복원하며 파괴적으로 표시되지 않습니다:

  • add_expense (Record an XMemo Ledger transaction): 구조화된 Ledger 레코드 하나를 만듭니다.
  • complete_memory_todo (Complete XMemo memory TODO): 기존 메모리 기반 TODO 또는 작업 항목을 완료로 표시합니다.
  • create_memory_todo (Create XMemo memory TODO): 메모리 기반 TODO 또는 작업 항목을 만듭니다.
  • [remember](/docs/tools/remember) (Remember in XMemo): 범위가 지정된 메모리를 만들거나 중복을 제거합니다.
  • restore_memory (Restore XMemo memory): forget의 기본 소프트 삭제 모드로 제거된 레코드를 복원합니다.
  • record_event (Record a milestone): 마일스톤 또는 인계 이벤트 하나를 추가하며, 기존 레코드를 편집하거나 삭제하지 않습니다.
  • create_pending_decision (Save a pending decision): 해결되지 않은 결정 하나를 컨텍스트와 선택지와 함께 나중에 검토하도록 저장합니다.
  • resolve_decision (Resolve a pending decision): 정확한 보류 중 결정에 대해 선택된 결과를 기록하고 기록을 유지한 채 결정을 종료합니다.

파괴적 도구

이 도구들은 기존 레코드를 덮어쓰거나 변경하거나 삭제할 수 있으므로 파괴적으로 표시됩니다:

  • [forget](/docs/tools/forget) (Forget XMemo memory, TODO, or Ledger transaction): 선택한 메모리, TODO 또는 Ledger 레코드 하나를 삭제합니다. 아래의 '삭제 및 복구'를 참조하세요.
  • update_memory (Update XMemo memory): 정확한 참조로 선택한 메모리 하나의 필드를 덮어씁니다.
  • update_state (Save working state): 이름이 지정된 작업 상태 체크포인트 하나를 저장하거나 교체하여 이후 대화에서 재개할 수 있게 합니다.
  • [todo](/docs/tools/todos) (Manage XMemo TODOs): 내 TODO를 만들거나 업데이트하거나 완료합니다. 아래의 'Claude의 TODO'를 참조하세요.
  • project (Manage XMemo project): 프로젝트를 만들거나, 승인된 프로젝트의 메모리, 결정, 문서 및 대화 링크 또는 설정을 변경합니다.

삭제 및 복구

명시적으로 영구 삭제를 요청하지 않는 한 forget을 통한 삭제는 복구할 수 있습니다:

  • 기본값: forget은 복구 가능한 소프트 삭제를 수행합니다.
  • 실행 취소: restore_memory는 소프트 삭제된 레코드를 복원합니다.
  • 영구 삭제: mode='hard'를 지정한 forget은 영구적이며 복구할 수 없습니다. 사용자의 명시적인 확인이 필요하며, 하드 삭제된 레코드는 복원할 수 없습니다.

Claude의 TODO

Claude에서 todo 도구는 TODO를 만들고, 업데이트하고, 완료하는 데만 사용됩니다. Claude는 list_memory_todos로 TODO를 읽습니다. todo 참조 페이지는 전체 디스패처를 설명하지만, Claude에서는 이 세 가지 작업에만 사용하세요.

Claude Desktop

Claude Desktop에서도 같은 사용자 지정 커넥터와 OAuth 흐름으로 시작하세요. API key를 사용하는 로컬 구성은 대안으로 남아 있습니다:

  • 권장: XMemo를 https://xmemo.dev/mcp 사용자 지정 커넥터로 추가하고 OAuth를 완료합니다. API key가 필요하지 않습니다.
  • 대안: claude_desktop_config.json에서 퍼스트 파티 xmemo-mcp stdio 프록시 또는 mcp-remote를 XMemo API key와 함께 구성합니다. stdio 프록시 구성은 [MCP 개요](/docs/mcp/overview)를 참조하세요.

Claude Code

Claude Code는 별도의 설정을 사용합니다. 독립형 Skill과 직접 MCP 구성은 [Claude Code](/docs/mcp/claude-code)를 참조하세요.

일반적인 오류

OAuth 실패는 실제 토큰 엔드포인트 응답에 대응합니다:

  • invalid_grant — 인증 코드가 유효하지 않거나 만료되었거나 이미 사용되었습니다: Claude에서 XMemo를 다시 연결하고 다시 승인하세요.
  • invalid_target — OAuth 리소스가 이 MCP 서버와 일치하지 않습니다: 커넥터를 제거하고 https://xmemo.dev/mcp 로 다시 추가하세요.
  • 403 insufficient_scope — 권한 부여에 memory:read 또는 memory:write가 포함되어 있지 않습니다: 두 범위를 모두 승인하고 다시 연결하세요.

업데이트 및 제거

Claude 커넥터 유지 관리 절차:

  • 다시 연결: Claude에 XMemo 인증 또는 다시 연결 메시지가 표시되면 커넥터를 다시 연결하고 OAuth를 다시 완료하세요.
  • 제거: Claude의 커넥터 설정에서 XMemo 사용자 지정 커넥터를 제거합니다.

출처: 클라이언트 기능 매트릭스