Conectar un cliente MCP a la memoria

Overview

Cualquier cliente del Protocolo de Contexto de Modelo (MCP), como Claude Code o Codex, puede conectarse directamente a la memoria sin necesidad del SDK agentic-platform-memory. Utilice esta conexión MCP para proporcionar memoria al cliente, en lugar de escribir código Python para el SDK. En esta guía, aprenderá a conectar un cliente MCP a la memoria y a grabar y recuperar turnos de conversación.

Tip

Para obtener más información sobre la memoria, consulte la sección "Cómo funciona la memoria" en la guía "Agregar memoria a su agente".

El servidor MCP expone tres herramientas:

record_turn: Registra un breve turno de conversación. Esta es la única operación de escritura entre las tres herramientas.
build_context: Recupera la memoria relevante para una consulta y la formatea como contexto.
search_memories: Busca en la memoria a largo plazo por tipo.

Un proceso en segundo plano extrae de forma asíncrona los recuerdos a largo plazo de los turnos grabados. Para crear un recuerdo a largo plazo directamente, en lugar de esperar a que se extraiga, utilice el SDK agentic-platform-memory descrito en la sección «Usar el servicio de memoria independiente».

Requisitos previos

Asegúrese de cumplir con los siguientes requisitos previos antes de comenzar:

Un proyecto en Atlas Agent Engine. Para encontrar el ID de tu proyecto, consulta Ver proyectos.
Memoria habilitada en ese proyecto, que requiere los siguientes componentes:
- Los archivos MONGODB_URI, VOYAGE_API_KEY y una clave API de LLM (como ANTHROPIC_API_KEY) cargados como secretos del proyecto.
- Un entorno de ejecución en memoria. Si no dispone de un entorno de ejecución, ejecute el comando agentengine memory apply --wait para configurarlo. Espere hasta que el entorno de ejecución indique que está listo antes de continuar.
Para obtener información sobre cómo configurar estos requisitos previos, consulte Configurar la memoria.
Una cuenta de servicio de proyecto con el rol PROJECT_OWNER. Ejecute el siguiente comando para crear una, reemplazando <name> por un nombre para la cuenta de servicio:
agentengine service-account create <name> --role PROJECT_OWNER
Importante
Guarda el ID de cliente y el secreto de cliente que devuelve el comando. El motor del agente Atlas muestra el secreto de cliente solo una vez.

Get an Access Token

Para obtener un token de acceso, ejecute el siguiente comando, reemplazando <client-id> con el ID de cliente de su cuenta de servicio:

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 la clave secreta del cliente sin mostrarla en la terminal. Copie el valor del campo access_token del objeto JSON devuelto para usarlo en la siguiente sección.

Importante

El token de acceso caduca después de una hora. Si incluyes el token directamente en la configuración de tu cliente MCP, la conexión dejará de funcionar tras su caducidad. Para restablecer la conexión, vuelve a ejecutar el comando anterior para obtener un nuevo token y, a continuación, actualiza la configuración.

Conecte su cliente MCP

Cualquier cliente MCP que admita el transporte HTTP Streamable puede conectarse a la memoria mediante la siguiente URL. Reemplace <project_id> con el ID de su proyecto.

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

Envía el token de acceso de la sección anterior como un encabezado Authorization: Bearer <access-token>.

Seleccione la pestaña que corresponda a su cliente MCP para ver un ejemplo de cómo enviar el token de acceso al agregar el servidor:

Ejecute el siguiente comando para agregar memoria como servidor MCP, reemplazando <project_id> y <access-token> con su ID de proyecto y token de acceso. El indicador --scope user habilita el servidor en todos los proyectos.

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, agregue la siguiente configuración a ~/.claude.json, que comparten la CLI de Claude Code y la extensión de Claude Code para VS Code:

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

Codex envía el token de portador desde una variable de entorno en lugar de una cabecera en el comando add. Exporta el token de acceso en el entorno que inicia Codex y, a continuación, ejecuta el siguiente comando para añadir memoria como servidor MCP. Sustituye <project_id> por el ID de tu proyecto.

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, agregue la siguiente tabla a ~/.codex/config.toml, reemplazando <project_id> con el ID de su proyecto:

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

Verificar la conexión

Después de agregar el servidor MCP, reinicie su cliente MCP y confirme que aparecen las tres herramientas de memoria y que se puede buscar en un turno grabado.

Confirme que el cliente muestra las herramientas de memoria.

Abra su cliente MCP y confirme que enumera exactamente tres herramientas del servidor project-memory: record_turn, build_context y search_memories.

Graba un turno de conversación.

Llama a record_turn dos veces con un dato distintivo, un user_id y un session_id. Registra un cambio de rol user seguido de un cambio de rol assistant. El siguiente ejemplo registra un dato sobre un aeropuerto local:

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

Recuperar el turno grabado como contexto.

Llama a build_context con los mismos user_id y session_id que usaste en el paso anterior, y una consulta que coincida con el hecho registrado. El turno registrado aparece inmediatamente, porque build_context incluye turnos recientes a corto plazo:

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

Buscar en la memoria a largo plazo el dato extraído.

Espere unos minutos para que el proceso de extracción en segundo plano consolide el turno grabado en una memoria a largo plazo. Luego, llame a search_memories con el mismo user_id, una consulta coincidente y un tipo de memoria:

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

Si el dato no aparece, espere un poco más y vuelva a buscar. La extracción se realiza de forma asíncrona y puede que no finalice inmediatamente después de registrar un turno.

Volver

Utilice el SDK de memoria independiente

Comunicación entre agentes