Claude Code

Claude Code의 claude mcp add CLI는 설정 편집을 대신 처리하고, 등록 범위를 프로젝트별 또는 사용자별로 유지해 줍니다. OAuth는 Engram 도구를 처음 호출할 때 브라우저에서 실행됩니다. 프로토콜 배경은 MCP를 참고하세요.

사전 준비

시작하기 전에 다음을 확인하세요.

app.engram.page에 Engram 계정이 있습니다.
보관함이 하나 이상 동기화되어 있습니다. Obsidian 플러그인이나 웹 앱을 열어 최근 하루 안에 노트가 동기화되었는지 확인하세요.
브라우저로 로그인할 수 있습니다. MCP 인증 흐름은 브라우저 창을 엽니다.
OAuth 대신 API 키를 쓸 계획이라면 API 키에는 Pro가 필요합니다. OAuth 로그인은 무료를 포함한 모든 요금제에서 동작하며 권장 방식입니다. 무료와 Starter에서는 API 키를 만들거나 사용할 수 없습니다.

엔드포인트

https://mcp.engram.page

설정

1. Claude Code CLI로 Engram 등록.

claude mcp add --transport http --scope user engram https://mcp.engram.page

--scope user는 모든 프로젝트에서 Engram을 쓸 수 있게 합니다. 현재 저장소의 .mcp.json에서만 쓰려면 --scope project를 대신 쓰세요.

직접 편집하고 싶다면 아래 블록을 ~/.claude.json(사용자 범위) 또는 프로젝트 루트의 .mcp.json에 추가하세요.

{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.engram.page"
    }
  }
}

2. 다시 불러오기. 현재 Claude Code 세션을 종료하고 claude를 다시 실행하세요. claude mcp list를 실행해 Engram이 등록되었는지 확인합니다. 상태는 △ needs authentication으로 표시됩니다.

첫 실행 인증

Claude Code는 OAuth를 자동으로 묻지 않습니다. 새 세션에서 /mcp를 실행하고 engram을 선택한 뒤 Authenticate를 고르세요. 브라우저가 열려 Engram에 로그인하고 연결을 승인합니다. Claude Code는 토큰을 저장하고 이후로 계속 재사용합니다. 허용 범위는 전체 mcp 스코프입니다. 동작별 세분화 스코프는 로드맵에 있습니다.

Claude에게 사용법 알려 주기

아래 스니펫을 Claude Code의 사용자 수준 지침 파일인 ~/.claude/CLAUDE.md에 덧붙이세요. 모든 프로젝트에 적용됩니다. 저장소별 재정의는 저장소 루트의 프로젝트 수준 CLAUDE.md에 넣습니다.

Engram holds my personal notes — treat it as your long-term memory of me. Search it when a question depends on context I might have shared before. Before saving or updating a note, ask first.

사용해 보기

등록과 인증이 끝나면 Claude에게 이렇게 물어보세요.

내 보관함에서 엔지니어 면접 과정에 관한 노트를 검색해서 상위 세 개를 요약해 줘.
지난달에 임베딩에 대해 쓴 내용이 있으면 전부 찾아줘.

Claude가 Engram의 search(또는 get_note, write_note 등) 도구를 호출해 결과를 가져오고 그 맥락에서 답합니다. 도구가 실행되면 설정이 끝난 것입니다.

OAuth 대신 API 키

헤드리스 서버, CI, 공유 보관함이라면 OAuth를 건너뛰고 연결을 Engram API 키에 고정하세요. app.engram.page/settings/api-keys에서 키를 만들어 Bearer 헤더로 보내면 됩니다.

간단한 방법은 키를 설정 파일에 바로 기록하는 것입니다.

claude mcp add --transport http --scope user engram https://mcp.engram.page \
  --header "Authorization: Bearer engram_YOUR_KEY_HERE"

--scope user라면 괜찮습니다(~/.claude.json은 당신의 컴퓨터에만 있습니다). --scope project에서는 안 됩니다. .mcp.json은 커밋하는 파일이기 때문입니다. 키는 환경 변수에서 불러오세요.

환경 변수에서 키 불러오기

Claude Code는 .mcp.json을 읽을 때 ${VAR}와 ${VAR:-default}를 확장합니다. HTTP 서버에서는 url과 headers 필드가 확장 대상이며, API 키가 들어가는 곳이 바로 여기입니다. 다음을 커밋하세요.

{
  "mcpServers": {
    "engram": {
      "type": "http",
      "url": "https://mcp.engram.page",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_KEY}"
      }
    }
  }
}

저장소에는 변수 이름만 들어 있습니다. 기여자마다 자기 키를 쓰고 Engram은 각 키를 해당 계정으로 한정하므로, 공유된 .mcp.json이 보관함 공유를 뜻하지는 않습니다.

Claude Code는 실행된 환경을 읽으므로 claude를 시작하기 전에 키를 내보내(export) 두세요.

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

저장소별 키가 필요하다면 direnv를 쓰고 값은 gitignore된 .envrc에 두세요.

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

direnv allow를 한 번 실행한 뒤 그 디렉터리에서 claude를 시작하세요.

변수가 설정되어 있지 않아도 설정은 로드되고, Claude Code는 문자열 Bearer ${ENGRAM_API_KEY}를 그대로 보내며 Engram은 이를 401로 거부합니다. claude mcp list가 이를 표시합니다.

[Warning] [engram] mcpServers.engram: Missing environment variables: ENGRAM_API_KEY

키를 쓰는 설정이 연결되지 않으면 이 줄부터 확인하세요.

키를 쓰기 시작하면 두 가지가 달라집니다. 처음 연결할 때 브라우저가 열리지 않고, /mcp에 더 이상 Authenticate가 나타나지 않습니다. Authorization 헤더를 설정하면 OAuth 대체 경로가 완전히 꺼지기 때문입니다. 키가 포괄하는 범위와 교체 방법은 MCP Config → API 키 인증을 참고하세요.

문제 해결 (Claude Code 전용)

claude mcp list에 engram이 없음. 명령이 예상과 다른 범위에서 실행되었습니다. ~/.claude.json(사용자)과 .mcp.json(프로젝트) 모두에서 항목을 확인한 뒤, 알맞은 --scope 플래그로 claude mcp add를 다시 실행하세요.
/mcp 선택 목록에 engram이 없음. claude mcp add 뒤에 CLI를 종료했다가 다시 실행하지 않았습니다. claude를 재시작하세요.
Authenticate를 눌러도 반응이 없거나 브라우저가 열리지 않음. 헤드리스나 원격 세션은 브라우저를 열 수 없습니다. 데스크톱 브라우저가 있는 호스트에서 Claude Code를 실행하거나, 대신 API 키를 쓰세요.

클라이언트와 상관없는 문제는 문제 해결을 참고하세요.

연결 해제

**Claude Code**와 Engram의 연결을 해제하려면 다음과 같이 하세요.

Claude Code에서 커넥터 또는 MCP 서버 항목을 찾아 제거합니다.
Engram에서 계정 → API Keys & Sessions를 열어 해당 세션을 해제(revoke)합니다.
OAuth 토큰은 서버에서 무효화됩니다. 다시 연결하려면 Claude Code에서 다시 인증해야 합니다.

claude mcp remove engram으로 로컬 등록을 지울 수도 있습니다. 설정 항목은 제거되지만, Engram에서 해제하기 전까지 서버 측 토큰은 유효합니다.

다음 단계

MCP프로토콜 개요.

스코프허용 범위가 포함하는 것.

모든 연동다른 클라이언트 고르기.