agentmemory-mcp-gateway

Puerta de enlace OAuth 2.1 de un solo usuario que expone un pequeño conjunto de herramientas MCP de AgentMemory a clientes remotos.

Los clientes MCP se autentican en este servicio. Este servicio se autentica en AgentMemory. El secreto del backend de AgentMemory nunca sale de la puerta de enlace.

Qué hace

• Implementa MCP remoto sobre Streamable HTTP en /mcp

• Actúa como servidor de autorización OAuth y recurso protegido

• Permite que exactamente una persona inicializada previamente inicie sesión y otorgue consentimiento

• Reenvía el tráfico permitido de tools/list y tools/call a la API REST de AgentMemory

• Se cierra en caso de fallo cuando AgentMemory no está disponible

Clientes previstos: ChatGPT, Notion Custom Agents, Codex cloud y otros clientes MCP remotos conformes a los estándares.

Forma de la URL pública:

https://memory-mcp.example.com/mcp

Related MCP server: Remote MCP Server

Arquitectura

MCP client
  -> HTTPS gateway (this service)
    -> private AgentMemory REST API

Límites de confianza:

• Los clientes MCP solo ven el origen público HTTPS, los metadatos OAuth y los esquemas/resultados de las herramientas permitidas.

• AgentMemory permanece en la red privada de Railway. Los clientes nunca reciben AGENTMEMORY_URL ni AGENTMEMORY_SECRET.

• Las cabeceras Authorization entrantes se usan únicamente para validar el token de acceso del cliente. La puerta de enlace siempre construye una nueva cabecera Authorization: Bearer ${AGENTMEMORY_SECRET} para las llamadas upstream.

• SQLite almacena exclusivamente autenticación y estado OAuth. No es una base de datos de memoria.

Este es un servicio de Railway independiente de AgentMemory. Ejecute exactamente una réplica.

Por qué REST en lugar de @agentmemory/mcp

@agentmemory/mcp puede recurrir a una base de datos de memoria local cuando el upstream no está disponible. Eso es inaceptable para un gateway personal remoto.

Este servicio llama exclusivamente a:

• GET /agentmemory/mcp/tools

• POST /agentmemory/mcp/call con { "name": string, "arguments": object }

Si AgentMemory está caído, malformado o agota el tiempo de espera, el gateway devuelve un error MCP seguro. No crea, abre ni escribe en otro almacén de memoria.

Por qué existe SQLite

SQLite en DATABASE_PATH (por defecto /data/oauth.sqlite) contiene:

• el usuario único y su hash de contraseña

• sesiones y consentimientos

• registros de clientes OAuth

• códigos de autorización

• estado de tokens de acceso/refresco y revocación

• claves de firma / JWKS

Nunca almacena observaciones ni embeddings de AgentMemory.

El limitador de tarifa en memoria también está limitado a una sola réplica. No escale este servicio horizontalmente.

Modelo estricto de un solo usuario

• Solo correo electrónico y contraseña

• Sin GitHub, inicio de sesión social, enlaces mágicos, invitaciones ni recuperación de contraseña

• Sin registro público y sin API de gestión de usuarios

• El registro de clientes (CIMD / DCR) no es registro de personas

• Solo el ID persistente del usuario inicializado puede iniciar sesión, aprobar el consentimiento o recibir tokens MCP utilizables

• El arranque en producción falla si la tabla de usuarios no contiene exactamente una fila

Los errores de autenticación son genéricos. No revelan si un correo existe.

Entorno

PUBLIC_URL es el único emisor y el origen de /mcp. El identificados del recurso protegido es ${PUBLIC_URL}/mcp.

Copie .env.example. Contiene únicamente marcadores de posición.

Desarrollo local

nvm install
cp .env.example .env
# fill local loopback values, for example PUBLIC_URL=http://127.0.0.1:8080
npm install
npm run seed-admin
# remove ADMIN_PASSWORD from .env
npm run dev

Comprobaciones útiles:

npm run format
npm run lint
npm run typecheck
npm test
npm run build

Inicialización segura y única del administrador

railway run solo inyecta variables en un comando local. No puede escribir en el volumen de Railway. Realice la inicialización dentro del contenedor desplegado después de que /data esté montado.

Local

npm run seed-admin
# remove ADMIN_PASSWORD from .env

Imagen de producción / Railway

La imagen incluye dist/seed-admin.js y arranca con node dist/start.js.

1. Genere una contraseña aleatoria larga en 1Password. No la guarde en git, SQLite, Docker o registros.

2. Establezca ADMIN_EMAIL y ADMIN_PASSWORD temporalmente (20+ caracteres) en el servicio.

3. Implemente o reinicie para que el contenedor se ejecute con /data montado.

4. Con esas variables establecidas, node dist/start.js ejecuta node dist/seed-admin.js en el mismo proceso, imprime el ID persistente del usuario y sale con 0 sin abrir el puerto HTTP.

5. Elimine ADMIN_PASSWORD y ADMIN_EMAIL y reinicie. El proceso sirve entonces HTTP.

6. Si ambas variables siguen establecidas después de que el usuario exista, el arranque registra que deben eliminarse y sale con 0 para que Railway no entre en bucle de fallos.

7. Si solo se establece una de ADMIN_EMAIL o ADMIN_PASSWORD, el arranque falla de forma segura y no sirve HTTP.

Equivalente manual dentro del contenedor una vez que el volumen existe:

railway ssh -- node dist/seed-admin.js

No use railway run npm run seed-admin para inicializar entornos de producción. Ese comando se ejecuta en su máquina.

El proceso HTTP de producción no se iniciará hasta que exista ese usuario único y las variables de inicialización hayan desaparecido.

Docker

docker build -t agentmemory-mcp-gateway .
docker run --rm -p 8080:8080 \
  -e PUBLIC_URL=http://127.0.0.1:8080 \
  -e BETTER_AUTH_SECRET=... \
  -e DATABASE_PATH=/data/oauth.sqlite \
  -e AGENTMEMORY_URL=http://127.0.0.1:3111 \
  -e AGENTMEMORY_SECRET=... \
  -v gateway-data:/data \
  agentmemory-mcp-gateway

El entrypoint arranca como root, verifica que DATABASE_PATH sea una ruta absoluta dentro de /data (o RAILWAY_VOLUME_MOUNT_PATH), hace chown solo de ese directorio y de los archivos SQLite/WAL/SHM, y luego cambia a UID/GID 10001 antes de que se ejecute node. Nunca hace chown recursivo de / ni de otros directorios principales. Montere un volumen persistente en /data.

Railway

1. Cree un servicio nuevo desde este repositorio. No lo despliegue sobre el servicio AgentMemory.

2. Use el Dockerfile / railway.json en la raíz del repositorio.

3. Adjunte un volumen persistente montado en /data. Railway monta los volúmenes como root y reemplaza el directorio /data de la imagen.

4. Establezca RAILWAY_RUN_UID=0 para que el entrypoint pueda hacer chown de /data y luego cambie a UID 10001. Dejar el proceso como root es una solución media; esta imagen no mantiene root después del arranque.

5. Configure el número de réplicas en 1. Un único volumen SQLite no se puede compartir de forma segura.

6. Establezca las variables de entorno anteriores. Use la URL privada de AgentMemory, por ejemplo http://<agentmemory-service>.railway.internal:3111.

7. Añada el dominio personalizado público y establezca PUBLIC_URL a ese origen exacto https://.

8. Inicialice al administrador una vez con el método en el contenedor descrito arriba y luego elimine las variables temporales de la contraseña.

9. Confirme que GET /healthz devuelve {"ok":true}.

No exponga AgentMemory en esta secuencia de pasos. La puerta de enlace es el único endpoint MCP público.

Conexión con ChatGPT

1. Despliegue con un origen HTTPS estable y /mcp.

2. En ChatGPT, agregue una URL de MCP remoto / conector: https://<su-dominio>/mcp.

3. Prefiera CIMD si ChatGPT lo ofrece. DCR queda habilitado como respaldo.

4. Complete las pantallas alojadas de inicio de sesión y consentimiento como el usuario inicializado.

5. Confirme que aparecen memory_recall, memory_smart_search y memory_save.

ChatGPT detecta automáticamente /.well-known/oauth-protected-resource y los metadatos del servidor de autorización.

Conexión con Notion Custom Agents

1. Habilite servidores MCP personalizados en el área de trabajo de Notion si es necesario.

2. Agregue la URL de un servidor MCP personalizado: https://<tu-dominio>/mcp.

3. Notion usa OAuth y normalmente DCR, salvo que se haya pre-Registrado un cliente.

4. Inicie sesión como el usuario inicializado y apruebe el consentimiento.

5. Active solo las herramientas que ese agente debe usar.

Verificación básica de extremo a extremo

curl -sS https://<your-domain>/healthz
curl -sS https://<your-domain>/.well-known/oauth-authorization-server
curl -sS https://<your-domain>/.well-known/oauth-protected-resource
curl -sS -D- https://<your-domain>/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

La llamada a /mcp debe devolver 401 con un desafío WWW-Authenticate que apunte a los metadatos del recurso protegido. Después de un inicio de sesión real de cliente, tools/list debe mostrar únicamente las herramientas permitidas.

Revocación de clientes y tokens

SQLite es la fuente de verdad para los clientes OAuth, los tokens de refresco y los consentimientos.

• Elimine o rote BETTER_AUTH_SECRET solo si pretende invalidar el material de firma y volver a inicializar con cuidado.

• Quitar una fila de la tabla oauthClient, los tokens relacionados y los registros de consentimiento revoca al cliente completo.

• Reemplazar el archivo SQLite cierra la sesión de todos los clientes.

No hay API de administración. Use una sesión de sqlite3 puntual contra el volumen si necesita revocar un cliente concreto.

Copia de seguridad y recuperación

Copie /data/oauth.sqlite junto con los archivos -wal y -shm mientras el servicio esté detenido, o use sqlite3 .backup. Si un volumen se pierde, todos los clientes OAuth deben reconectarse y el administrador debe volver a inicializarse. Esta copia de seguridad es estado de autenticación, no de AgentMemory.

Limitaciones conocidas

• Solo hay una réplica. Los límites de tasa están en memoria.

• No hay recuperación de contraseña. Si se olvida, restaure SQLite desde una copia de seguridad o elimine la tabla de usuarios e inicialícelo de nuevo.

• No hay panel de control ni soporte para varios usuarios.

• El controlador MCP mantiene el soporte del protocolo del SDK oficial previo (2025) en modo sin estado para que ChatGPT y Notion no sean rechazados. La incursión de OAuth se adapta a las API MCP actuales de Better Auth, incluidos CIMD y DCR explícito.

• La autenticación de cliente mTLS anunciada por ChatGPT se termina en el borde HTTPS, no se verifica dentro del proceso.

Agentes en la nube

Cursor Cloud usa .cursor/environment.json:

• Dockerfile — Ubuntu 24.04, Node 24 (nvm), npm y agentfiles

• [Instalar] — actualiza agentfiles y ejecuta npm ci cuando existe package-lock.json

El desarrollo local usa la misma versión de Node a través de .nvmrc para la imagen de la nube; el runtime del gateway se adapta a Node 22.