에이전트 메모리를 위한 MCP 서버, Claude Code를 HotKV에 연결하기

MCP 서버는 AI 어시스턴트에 한 번의 채팅보다 오래가는 메모리를 주는 가장 간단한 방법입니다. Claude Code, Cursor 같은 클라이언트는 채팅이 끝나면 그 채팅의 컨텍스트를 잃습니다. 이를 해결하려고 원시 데이터베이스 접근 권한을 넘겨 주는 것은 위험합니다. hotkv-mcp는 HotKV용으로 저희가 만든 오픈소스 MCP 서버입니다. 어시스턴트에 메모, 대화 기록, 이벤트 로그, 프롬프트 템플릿, 문서 검색을 위한 고정된 도구 집합을 제공합니다. 그 외에는 아무것도 제공하지 않습니다.

요약. hotkv-mcp는 Claude Code, Cursor, VS Code 또는 자체 에이전트를 고정된 도구 28개를 통해 HotKV 서버에 연결하는 Apache-2.0 MCP 서버입니다. 임의의 명령을 실행하는 도구가 없으므로 어시스턴트는 데이터를 비우거나 설정을 바꿀 수 없습니다. 읽기 전용 모드는 쓰기 도구를 모두 제거하고, 네임스페이스는 에이전트를 하나의 키 접두사 안에 가둡니다. pip install hotkv-mcp로 설치하거나 uvx로 실행하십시오.

Model Context Protocol이란

Model Context Protocol(MCP)은 AI 애플리케이션을 데이터 소스, 도구, 워크플로 같은 외부 시스템에 연결하는 오픈 표준입니다. 프로젝트의 소개 글은 이를 AI 애플리케이션을 위한 USB-C 포트에 비유합니다. MCP 용어로 애플리케이션은 클라이언트이고, 연결 대상 시스템은 각각 서버로 노출됩니다.

메모리의 경우 어시스턴트가 메모를 저장하는 도구처럼 이름이 붙은 도구를 호출한다는 뜻입니다. 그 도구가 무엇을 할 수 있는지는 서버가 결정합니다. 모델은 자기만의 데이터베이스 연결을 얻지 못합니다.

HotKV MCP 서버가 노출하는 것

이 서버는 HotKV의 에이전트 메모리, 프롬프트 레지스트리, 문서 검색을 도구 28개로 감쌉니다. 각 도구는 MCP 어노테이션에서 읽기 전용인지, 쓰기인지, 삭제인지를 선언합니다. 그러면 클라이언트가 파괴적인 도구에 대해 승인을 요청할 수 있습니다.

메모리 도구는 AI 에이전트 메모리에서 설명한 저장소, 즉 대화 기록, 작업 메모, 이벤트 로그에 대응합니다. 임베딩을 이용한 시맨틱 불러오기는 노출되지 않습니다. rag_search는 키워드 관련도로 순위를 매기므로 임베딩이 필요 없습니다.

키, 해시, 리스트 도구는 어떤 HotKV 서버에서든 작동합니다. 메모리, 프롬프트, 문서 검색 도구는 HotKV의 AI 엔진을 사용하며, 이를 포함하는 라이선스가 필요합니다. 라이선스가 없으면 이 도구들은 서버에 해당 기능의 라이선스가 없다는 메시지를 반환합니다. 키 도구는 계속 작동합니다. AI 페이지에 설명되어 있듯이 HotKV Cloud의 Performance 및 Scale 인스턴스에는 AI 엔진이 포함되어 있습니다.

설치와 연결

이 서버에는 Python 3.10 이상이 필요합니다. HotKV 서버 0.3.0과 공식 hotkv-client 패키지를 기준으로 작성되었으며, 버전 1.0.0이 PyPI에 있습니다. pip로 설치하거나 uv로 설치 없이 실행하십시오.

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

명령어 하나로 추가합니다. Claude Code MCP 문서에 설명된 대로, --는 Claude Code 자체의 옵션과 서버를 시작하는 명령을 구분합니다.

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor와 Claude Desktop

mcpServers 파일을 읽는 클라이언트는 같은 서버를 JSON 항목으로 받습니다. 비밀번호는 HOTKV_URL 환경 변수나 클라이언트의 시크릿 저장소에 두십시오. 명령줄은 같은 머신의 다른 사용자에게 보입니다. TLS 연결에는 hotkvs://를 사용하십시오.

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

작동 확인

claude mcp list를 실행하여 서버가 등록되었는지 확인하십시오. 그런 다음 어시스턴트에게 server_info 도구를 호출하라고 요청하십시오. HotKV 버전과 메모리 사용량을 반환하며, 네임스페이스를 설정하지 않은 경우 키 개수도 반환합니다. 서버가 읽기 전용인지, 어떤 네임스페이스로 제한되어 있는지도 알려 줍니다. 이를 통해 안전장치가 적용되었는지 확인할 수 있습니다.

에이전트를 안전한 한도 안에 두기

도구를 호출할 수 있는 모델은 도구를 오용하도록 유도될 수도 있으므로, 기능보다 한도가 더 중요합니다.

임의의 명령 없음

원시 명령을 실행하는 도구는 없습니다. 28개 도구 중 그런 일을 하는 것이 없으므로 어시스턴트는 데이터베이스를 비우거나 서버 설정을 바꿀 수 없습니다. 도구가 닿는 키는 무엇이든 읽을 수 있으며, 그래서 아래의 네임스페이스가 중요합니다.

읽기 전용 모드

--read-only는 set, delete, hash_set, list_push, 추가하거나 비우는 메모리 도구, prompt_save, rag_create, rag_ingest를 포함해 쓰기를 하는 모든 도구를 제거합니다. 에이전트는 이 도구들을 볼 수조차 없습니다. 메모리를 참고하되 절대 바꾸지 말아야 하는 어시스턴트에 사용하십시오.

네임스페이스와 크기 상한

--namespace PREFIX는 모든 것을 그 접두사 아래에 저장합니다. 에이전트는 접두사를 보지 못하며 다른 이름에는 닿을 수 없습니다. 에이전트마다 다른 접두사의 시작 부분이 아닌 접두사를 지정하십시오. agent와 agent:b가 아니라 agent-a와 agent-b를 사용하십시오. 그렇지 않으면 짧은 쪽이 긴 쪽의 이름에 닿을 수 있습니다.

결과에도 상한이 있습니다. --max-value-bytes는 긴 값을 잘라 내고 잘렸다고 표시하며, 기본값은 65,536바이트입니다. --max-items는 한 번의 호출이 반환하는 키, 리스트 항목, 적중의 수를 제한하며 기본값은 200입니다. 따라서 거대한 값 하나가 모델의 컨텍스트를 가득 채울 수 없습니다. 해시 전체를 읽는 것은 항목 수 상한이 적용되지 않으므로, 큰 해시는 에이전트의 네임스페이스에 두지 마십시오.

HTTP 전송에는 로그인이 없음

기본 stdio 전송은 클라이언트가 하위 프로세스로 시작합니다. 공유 환경에서는 127.0.0.1:8000의 /mcp에서 수신하는 hotkv-mcp --transport streamable-http를 실행할 수 있습니다. 호출자를 인증하지 않습니다. 로컬 호스트에 두거나 인증하는 리버스 프록시 뒤에 두고, 전용 네임스페이스를 부여하십시오.

팀을 위한 구성 선택

적절한 플래그는 각 에이전트의 용도에 달려 있습니다. 아래의 모든 옵션은 명령줄 플래그입니다. --read-only와 --namespace에는 환경 변수 HOTKV_MCP_READ_ONLY와 HOTKV_MCP_NAMESPACE도 있습니다.

목적에 맞는 가장 제한적인 행에서 시작하십시오. 접근 권한을 나중에 넓히기는 쉽지만, 에이전트가 이미 써 놓은 것을 되돌리기는 어렵습니다.

첫 세션 단계별 안내

짧은 시험을 해 보면 실제 메모를 서버에 맡기기 전에 안전장치가 하는 일을 확인할 수 있습니다. 임시 네임스페이스와, AI 엔진 라이선스가 있는 로컬 HotKV 서버를 사용하십시오. 그 라이선스가 없으면 메모리 도구가 작동하지 않습니다.

1. 네임스페이스를 지정하여 연결합니다. claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial을 실행하십시오.
2. 한도를 확인합니다. 어시스턴트에게 server_info를 호출하여 네임스페이스와 읽기 전용 여부를 알려 달라고 요청하십시오. trial이며 읽기 전용이 아니라고 답해야 합니다.
3. 메모를 저장합니다. 스테이징 사이트가 특정 주소에 있다는 것을, 사이트 이름을 딴 메모로 기억해 달라고 요청하십시오. 어시스턴트가 memory_set_note를 호출하며, 세션은 처음 사용할 때 생성됩니다.
4. 새 채팅에서 다시 읽습니다. 새 대화를 시작하고 그 세션에 어떤 메모가 있는지 물어보십시오. memory_list_notes와 memory_get_note를 호출하며, 메모는 그대로 남아 있습니다.
5. 결정을 기록합니다. 이벤트 로그에 결정 하나를 기록해 달라고 요청하십시오. memory_log_event를 호출하고, 나중에 memory_query_events가 이를 다시 가져옵니다.
6. 쓰기 권한을 제거합니다. 이전 항목을 제거하고 --read-only로 다시 연결한 뒤 4단계를 반복하십시오. 읽기는 여전히 작동하고, 쓰는 도구는 더 이상 제공되지 않습니다.

6단계가 설명한 대로 작동한다면, 가장 중요한 두 가지 통제인 네임스페이스와 읽기 전용 모드를 확인한 것입니다.

어시스턴트가 저장한 내용은 다시 읽을 때 신뢰할 수 없는 텍스트로 취급하십시오. 메모리 글의 저장된 텍스트를 신뢰할 수 없는 것으로 취급하기에서 설명했듯이, 웹 페이지에서 가져와 기록한 메모에는 지시문이 들어 있을 수 있습니다.

문제 해결

• "This HotKV server is not licensed for that feature." 메모리, 프롬프트, 문서 검색 도구에는 AI 엔진을 포함하는 HotKV 라이선스가 필요합니다. 키, 해시, 리스트 도구는 라이선스 없이도 계속 작동합니다.
• 연결에 실패합니다. URL 스킴을 확인하십시오. hotkv://, hotkvs://(TLS), redis://, rediss://가 모두 작동하며, 비밀번호는 hotkv://:password@host:6379처럼 URL에 넣습니다.
• 값이 잘려서 돌아옵니다. --max-value-bytes를 넘으면 결과에 잘렸다는 표시가 붙습니다. 한도를 올리거나 더 작은 값을 저장하십시오.
• 쓰기 도구가 없습니다. 서버 인수에 --read-only가 있는지, 환경에 HOTKV_MCP_READ_ONLY가 있는지 확인하십시오.
• 어시스턴트가 앞서 저장한 이름을 찾지 못합니다. 같은 세션 또는 에이전트 이름을 사용했는지, 서버가 이전과 같은 네임스페이스로 실행 중인지 확인하십시오.
• uvx를 찾을 수 없습니다. uv를 설치하거나, pip로 패키지를 설치하고 hotkv-mcp를 직접 시작하십시오.

자주 묻는 질문