메모리에 MCP 클라이언트 연결

개요

Claude Code 또는 Codex와 같은 모든 MCP(Model Context Protocol) 클라이언트 Agentic-platform-memory SDK를 사용하지 않고도 메모리에 직접 연결할 수 있습니다. SDK에 대해 Python 코드를 직접 작성하는 대신 이 MCP 연결을 사용하여 해당 클라이언트 메모리를 제공합니다. 이 가이드 에서는 MCP 클라이언트 메모리에 연결하고 대화 차례를 기록 및 호출하는 방법을 학습 수 있습니다.

MCP 서버 세 가지 도구를 노출합니다.

• record_turn: 단기 대화 차례를 한 번 기록합니다. 이는 세 가지 도구 중 유일한 쓰기 (write) 작업입니다.

• build_context: 쿼리 와 관련된 메모리를 검색하고 컨텍스트로 형식을 지정합니다.

• search_memories: 장기기억을 유형별로 검색합니다.

배경 프로세스 기록된 회전 순서에서 장기 기억을 비동기적으로 추출합니다. 추출을 기다리지 않고 직접 장기 메모리를 생성하려면 독립형 메모리 서비스 사용에 설명된 agentic-platform-memory SDK를 사용하세요.

전제 조건

시작하기 전에 다음 전제 조건이 있는지 확인하세요.

• Atlas Agent Engine의 프로젝트 . 프로젝트 ID 찾으려면 프로젝트 보기를 참조하세요.

• 해당 프로젝트 에서 활성화된 메모리에는 다음 구성 요소가 필요합니다.

  • 프로젝트 시크릿으로 업로드된 MONGODB_URI, VOYAGE_API_KEY 및 LLM API 키(예: ANTHROPIC_API_KEY)입니다.

  • 실행 메모리 런타임입니다. 런타임이 없는 경우 agentengine memory apply --wait 명령을 실행 런타임을 프로비저닝합니다. 계속하기 전에 런타임이 준비된 것으로 보고할 때까지 기다립니다.

  이러한 필수 구성 요소를 구성하는 방법을 학습 메모리 구성을 참조하세요.

• PROJECT_OWNER 역할 있는 프로젝트 서비스 계정입니다. 다음 명령을 실행하여 계정을 생성하고 <name>을 서비스 계정의 이름으로 바꿉니다.

  agentengine service-account create <name> --role PROJECT_OWNER

  중요

  명령이 반환하는 클라이언트 ID 와 클라이언트 시크릿을 저장합니다. Atlas Agent Engine은 클라이언트 시크릿을 한 번만 표시합니다.

액세스 토큰 받기

액세스 토큰을 얻으려면 다음 명령을 실행 <client-id>을(를) 서비스 계정의 클라이언트 ID 로 바꿉니다.

read -r -p "Client ID: " CLIENT_ID
curl --fail-with-body --silent --show-error --user "$CLIENT_ID" \
  --data grant_type=client_credentials \
  https://agentengine.mongodb.com/api/v1/oauth/token

curl 터미널에 에코하지 않고 클라이언트 시크릿을 입력하라는 메시지를 표시합니다. 다음 섹션에서 사용할 수 있도록 반환된 JSON 객체 에서 access_token 필드 값을 복사합니다.

MCP 클라이언트 연결

Streamable HTTP 전송을 지원하는 모든 MCP 클라이언트 다음 URL 사용하여 메모리에 연결할 수 있습니다. <project_id>를 프로젝트 ID 로 바꿉니다.

https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp

이전 섹션의 액세스 토큰을 Authorization: Bearer <access-token> 헤더로 전송합니다.

서버 추가 시 액세스 토큰을 전송하는 예시 보려면 MCP 클라이언트 에 해당하는 탭 선택하세요.

claude mcp add --scope user --transport http project-memory \
  https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp \
  --header "Authorization: Bearer <access-token>"

{
  "mcpServers": {
    "project-memory": {
      "type": "http",
      "url": "https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp",
      "headers": {
        "Authorization": "Bearer <access-token>"
      }
    }
  }
}

export AGENTIC_MEMORY_TOKEN=<access-token>
codex mcp add project-memory \
  --url https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp \
  --bearer-token-env-var AGENTIC_MEMORY_TOKEN

[mcp_servers.project-memory]
url = "https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp"
bearer_token_env_var = "AGENTIC_MEMORY_TOKEN"

연결 확인

MCP 서버 추가한 후 MCP 클라이언트 다시 시작하고 세 가지 메모리 도구가 나열되고 기록된 턴이 검색 가능한지 확인합니다.

record_turn(user_id="user_1", session_id="session_1", role="user", content="I always fly out of Boston.")
record_turn(user_id="user_1", session_id="session_1", role="assistant", content="Got it, Boston is saved as your home airport.")

build_context(user_id="user_1", session_id="session_1", query="Where should the flight book from?")

search_memories(user_id="user_1", query="home airport", type="semantic")