Conecte um cliente MCP à memória

Visão geral

Qualquer cliente de Protocolo de Contexto de Modelo (MCP), como Classe Code ou Codex, pode se conectar diretamente à memória sem usar o SDK da Agentic-platform-memory. Use essa conexão MCP para fornecer memória a esse cliente , em vez de você mesmo escrever código Python no SDK. Neste guia, você pode aprender a conectar um cliente MCP à memória e gravar e recuperar voltas de conversa.

Dica

Para saber mais sobre memória, consulte Como funciona a memória no guia Adicionar memória ao seu agente.

O servidor MCP expõe três ferramentas:

record_turn: registra uma conversa de curto prazo. Esta é a única operação de gravação entre as três ferramentas.
build_context: Recupera a memória relevante para uma consulta e a formata como contexto.
search_memories: pesquisa a memória de longo prazo por tipo.

Um processo background extrai memória de longo prazo de voltas registradas de forma assíncrona. Para criar uma memória de longo prazo diretamente em vez de aguardar a extração, use o SDK agentic-platform-memory descrito em Usar o serviço de memória independente.

Pré-requisitos

Certifique-se de ter os seguintes pré-requisitos antes de começar:

Um projeto no Atlas Agent Engine. Para encontrar o ID do projeto, consulte Visualizar projetos.
Memória habilitada para o projeto, que requer os seguintes componentes:
- O MONGODB_URI, VOYAGE_API_KEY e uma chave de API LLM (como ANTHROPIC_API_KEY) carregados como segredos de projeto .
- Um tempo de execução de memória em execução. Se você não tiver um tempo de execução, execute o comando agentengine memory apply --wait para provisionar o tempo de execução. Aguarde até que o tempo de execução reporte como pronto antes de continuar.
Para saber como configurar esses pré-requisitos, consulte Configurar memória.
Uma conta de serviço de projeto com o role PROJECT_OWNER. Execute o seguinte comando para criar uma, substituindo <name> por um nome para a conta de serviço:
agentengine service-account create <name> --role PROJECT_OWNER
Importante
Salve o ID do cliente e o segredo do cliente que o comando retorna. O Atlas Agent Engine mostra o segredo do cliente apenas uma vez.

Obter um token de acesso

Para obter um token de acesso, execute o seguinte comando, substituindo <client-id> pelo ID do cliente da sua conta de serviço:

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 solicita o segredo do cliente sem repeti-lo ao terminal. Copie o valor do campo access_token do objeto JSON retornado para uso na próxima seção.

Importante

O token de acesso expira após uma hora. Se você codificar o token na configuração do cliente MCP, a conexão deixará de funcionar após a expiração. Para restaurar a conexão, execute novamente o comando anterior para obter um novo token e atualize a configuração.

Conecte seu cliente MCP

Qualquer cliente MCP que ofereça suporte ao transporte Streamable HTTP pode se conectar à memória usando a seguinte URL. Substitua <project_id> pelo ID do projeto.

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

Envie o token de acesso da seção anterior como um cabeçalho Authorization: Bearer <access-token>.

Selecione a guia correspondente ao seu cliente MCP para obter um exemplo de envio do token de acesso ao adicionar o servidor:

Execute o seguinte comando para adicionar memória como um servidor MCP, substituindo <project_id> e <access-token> pelo ID do projeto e token de acesso. O sinalizador --scope user torna o servidor disponível em cada projeto.

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

Como alternativa, adicione a seguinte configuração a ~/.claude.json, que a CLI do Class e a extensão do Code VS Code compartilham:

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

O Codex envia o token do portador de uma variável de ambiente em vez de um cabeçalho no comando add. Exporte o token de acesso no ambiente que inicia o Codex e, em seguida, execute o seguinte comando para adicionar memória como um servidor MCP. Substitua <project_id> pelo ID do projeto.

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

Como alternativa, adicione a seguinte tabela ao ~/.codex/config.toml, substituindo <project_id> pelo seu ID do projeto:

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

Verificar a conexão

Depois de adicionar o servidor MCP, reinicie seu cliente MCP e confirme que ele lista as três ferramentas de memória e que uma vez registrada se torna pesquisável.

Confirme que o cliente lista as ferramentas de memória.

Abra seu cliente MCP e confirme que ele lista exatamente três ferramentas do servidorproject-memory : record_turn, build_context e search_memories.

Grave uma conversa.

Chame record_turn duas vezes com um fato distinto, um user_id e um session_id. Registre uma rotação de papel user seguida por uma rotação de papel assistant. O exemplo a seguir registra um fato sobre um aeroporto de origem:

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.")

Recupere a volta registrada como contexto.

Chame build_context com o mesmo user_id e session_id que você usou na etapa anterior e uma query que corresponda ao fato registrado. A conversão registrada aparece imediatamente, pois build_context inclui conversões recentes de curto prazo:

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

Pesquise na memória de longo prazo o fato extraído.

Aguarde alguns minutos para que o processo de extração do background una a mudança registrada em uma memória de longo prazo. Em seguida, chame search_memories com o mesmo user_id, uma query correspondente e um tipo de memória:

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

Se o fato não aparecer, aguarde mais e pesquise novamente. A extração é executada de forma assíncrona e pode não terminar imediatamente após você registrar uma mudança.

Voltar

Usar o SDK de memória standalone

Comunicação entre agentes