agentmemory-mcp-gateway

Einzelbenutzer-OAuth-2.1-Gateway, das einen kleinen Satz AgentMemory-MCP-Tools für entfernte Clients bereitstellt.

MCP-Clients authentifizieren sich bei diesem Dienst. Dieser Dienst authentifiziert sich bei AgentMemory. Das AgentMemory-Backend-Geheimnis verlässt das Gateway nie.

Funktionen

• Spricht Remote-MCP über Streamable HTTP unter /mcp

• Fungiert als OAuth-Autorisierungsserver und geschützte Ressource

• Erlaubt genau einem vorab eingerichteten Benutzer, sich anzumelden und eine Einwilligung zu erteilen

• Leitet freigegebenen tools/list- und tools/call-Verkehr per Allowlist an die AgentMemory-REST-API weiter

• Schlägt bei nicht verfügbarem AgentMemory (fail closed) sicher fehl

Vorgesehene Clients: ChatGPT, Notion Custom Agents, Codex Cloud und andere standardkonforme Remote-MCP-Clients.

Form der öffentlichen URL:

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

Related MCP server: Remote MCP Server

Architektur

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

Vertrauensgrenzen:

• MCP-Clients sehen nur die öffentliche HTTPS-Origin, die OAuth-Metadaten und die freigegebenen Tool-Schemas/-Ergebnisse.

• AgentMemory bleibt im privaten Railway-Netzwerk. Clients erhalten niemals AGENTMEMORY_URL oder AGENTMEMORY_SECRET.

• Eingehende Authorization-Header werden nur zur Validierung des Client-Zugriffstokens verwendet. Das Gateway erstellt für Upstream-Aufrufe immer einen neuen Authorization: Bearer ${AGENTMEMORY_SECRET}-Header.

• SQLite speichert nur Authentifizierungs- und OAuth-Zustand. Es ist keine Speicherdatenbank.

Dies ist ein von AgentMemory getrennte Railway-Dienst. Betreiben Sie genau eine Replica (Replikat).

Warum REST anstelle von @agentmemory/mcp

@agentmemory/mcp kann auf eine lokale Speicherdatenbank zurückgreifen, wenn das entfernte System nicht erreichbar ist. Das ist für ein entferntes persönliches Gateway nicht akzeptabel.

Dieser Dienst ruft nur Folgendes auf:

• GET /agentmemory/mcp/tools

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

Wenn AgentMemory nicht verfügbar ist, fehlerhaft antwortet oder einen Timeout aufweist, gibt das Gateway einen sicheren MCP-Fehler zurück. Es erstellt, öffnet oder schreibt keine anderen Speicherdatenbank.

Warum SQLite existiert

SQLite unter DATABASE_PATH (Standard /data/oauth.sqlite) enthält Folgendes:

• den einzelnen Benutzer und -Hash (Benutzerkennwort)

• Sitzungen und Einwilligungen

• OAuth-Client-Registrierungen

• Autorisierungscodes

• Zugriffs-/Aktualisierungs-Token und Entzugszustand

• Signaturschlüssel / JWKS

Es speichert niemals AgentMemory-Beobachtungen oder -Embeddings.

Auch der In-Memory-Tarifbegrenzer ist nur für eine einzelne Instanz konzipiert. Skalieren Sie diesen Dienst nicht horizontal.

Strenges Einzelbenutzer-Modell

• Nur E-Mail/Passwort

• Kein GitHub, Social-Login, Magic-Links, Einladungen und keine Passwortwiederherstellung

• Keine öffentliche Registrierung und keine Benutzerverwaltungs-API

• Client-Registrierung (CIMD / DCR) ist keine menschliche Registrierung

• Nur die dauerhafte ID des zuvor eingerichteten Benutzers kann sich anmelden, Einwilligungen erteilen oder nutzbare MCP-Tokens erhalten

• Der Produktionsstart schlägt fehl, wenn die Benutzer- kinds existieren

Authentifizierungsfehler sind generisch. Sie geben nicht preis, ob eine E-Mail-Adresse existiert.

Umgebung

PUBLIC_URL ist die einzige Aussteller und die Origin für /mcp. Die Ressourcen-ID der geschützten Ressource ist ${PUBLIC_URL}/mcp.

Kopieren Sie .env.example. Es enthält nur Platzhalter.

Lokale Entwicklung

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

Nützliche Prüfungen:

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

Sicheres einmaliges Administrator-Seeding

railway run injiziert Variablen nur in einen lokalen Befehl. Es kann nichts in dasRailway-Volume schreiben. Führen Sie das Seeding in dem bereitgestellten Container (deployed Container) durch, nachdem /data gemountet ist.

Lokal

npm run seed-admin
# remove ADMIN_PASSWORD from .env

Produktionsimage / Docker

Das Image enthält dist/seed-admin.js undstartet mit node dist/start.js.

1. Generieren Sie ein langes Zufallspasswort in 1Password. Speichern Sie es nicht in Git, SQLite, im Docker-Image oder in Logs.

2. zusätzlichen ADMIN_EMAIL und ADMIN_PASSWORD (20+ Zeichen) für den Dienst.

3. Erstellen Sie bereits Bereitstellung oder starten Sie neu, sodass der Container mit gemountetem /data läuft.

4. Mit diesen gesetzten Variablen führt node dist/start.js node dist/seed-admin.js prozessintern aus, gibt die dauerhafte Benutzer-ID aus und wird mit 0 beendet, ohne denHTTP-Port zu öffnen.

5. Entfernen Sie ADMIN_PASSWORD und ADMIN_EMAIL und starten Sie dann neu. Anschließend bedient der Prozess HTTP.

6. Wenn beide Variablen nach bestehenden Benutzer weiterhin sind, protokolliert der Start, dass sie entfernt werden müssen, und beendet mit 0, damit Railway nicht Absturz-Loop gerät.

7. Wenn nur eine von ADMIN_EMAIL oder ADMIN_PASSWORD gesetzt ist, schlägt der Start fehl und wart nie HTTP.

Manuelles Äquivalent im Container, nachdem das Volume unter:

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

Verwenden Sie railway run npm run seed-admin für das Produktions-Seeding. Dieses/in diesem CI läuft auf Ihrem Rechner.

Der Produktions-HTTP-Prozess startet erst, wenn dieser eine Benutzer existiert und die Seed-Variablen entfernt sind.

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

Der Entrypoint startet als Shell, prüft, ob DATABASE_PATH eine absolute Datei unter /data oder RAILWAY_VOLUME_MOUNT_PATH ist, führt chown nur für dieses Verzeichnis sowie für die SQLite/WAL/SHM-Dateien aus und wechselt dann vor der Ausführung von node zu UID/GID 10001. Er Ruft niemals rekursives chown für / oder andere übergeordnete Verzeichnisse auf. Binden Sie ein persistentes Volume unter /data ein.

Railway

1. Erstellen Sie einen neuen Dienst aus diesem Repository. Den Sie Dienst nicht auf dem AgentMemory-Dienst bereitgestellt (deploy).

2. Verwenden Sie die Dockerfile/railway.json im Repo-Root.

3. Binden Sie persistentes Volume unter /data ein. Railway mounted als Superuser und ersetzt das Imageverzeichnis /data.

4. Setzen Sie RAILWAY_RUN_UID=0, damit der Entrypoint /kädig chown ausführen kann, und wechseln Sie dann zuUID 10001. Den Prozess als Root zu lassen ist eine Kompromiss; dieses Image behält Root nach dem Start nicht.

5. Setzen Sie die Replikas auf 1. Ein einzelnes SQLite-Volume kann nicht sicher geteilt werden.

6. Setzen Sie die oben genannten Umgebungsvariablen. Verwenden Sie die private URL storageMemory, z.B. https://URLMemory.service.railway.internal:3111.

7. Binden Sie die Bundesoftware Custom Domain an und setzen Sie PUBLIC_URL auf genau diese https://-Origin.

8. Sep Sie den Administrator einmal mit dem oben beschriebenen In-Container-Pfad und löschen Sie dann die temporären Passwortvariablen.

9. Bestätigen Sie, dass GET /healthz {"ok":true} zurückgibt.

Setzen Sie AgentMemory für diesen Ablauf nicht in das öffentliche Internet. Das Gateway ist die einzige öffentliche MCP-Endpunkt.

ChatGPT anbinden

1. Stuntehen Sie mit stabiler HTTPS-Origin und /mcp.

2. Fügen Sie in ChatGPT eine Remote-/Connector-URL hinzu: https://<your-domain>/mcp.

3. Bevorzugen Sie CIMD, wenn ChatGPT diese bietet. DCR bleibt als Fallback aktiviert.

4. Schließen Sie die gehostetenI- und Einwilligungsseite als den angelegten Benutzer ab.

5. Bestätigen Sie, dass memory_recall, memory_smart_search und memory_saveerscheinen.

ChatGPT ermittelt /.well-known/oauth-supplied-resource und die Metadaten des Autorisierungsservers automatisch.

Notion Custom Agents anbinden

1. Aktivieren Sie bei Bedarf CG benutzerdefinierte MCP-Server im Hub.

2. Fügen Sie eine benutzerdefinierte Server-URL hinzu: https://<your-domain>/mcp.

3. Notion verwendet OAuth und in der Regel DCR, es sei denn ist ein Client vorab registriert.

4. Melden Sie sich als das/einen Benutzer an und stimmen Sie denEinwilligung zu.

5. Aktivieren Sie nur die Tools, die dieser Agentone verwenden soll.

Einfache End-zu-Ende-Überprüfung

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":{}}'

Der /mcp-Aufruf muss 401 mit einer WWW-Authenticate-Challenge zurückgeben, die auf die Metadaten der zum Ressourcen zeigt. Nach einem echten Client-Login sollte tools/list nur die freigegebenen Tools anzeigen.

Clients und Tokens widerrufen

SQLite ist die Quelle der Wahrheit mit OAuth-Clients, Refresh-Tokens und Einwilligungen.

• Löschen oder drehen Sie BETTER_AUTH_SECRET nur, wenn Sie das Signaturmaterial aktivieren und sorgfältig neu seeden möchten.

• Das Entfernen einer oauthClient-Zeile, zugehöriger Tokens und Einwillig/Datensätze wird diese Client widerrufen.

• Das Ersetzen der SQLite-Datei meldet alle Clients ab.

Es gibt keine Admin-API. Verwenden Sie eine einmalige sqlite3-Sitzung gegen das Volume, wenn Sie einen bestimmten Client widerrufen müssen.

Sichern kurz und Wiederherstellen

Kopieren Sie /data/oauth.sqlite und die -wal/-shm-Dateien gemeinsam, während der Dienst gestoppt ist, oder verwenden Sie sqlite3 .backup. Ein verlorenes Volume bedeutet, dass sich alle OAuth-Clients und neue Verbindung aufbauen müssen und der Administrator neu geseedet werden muss. Diese Sicherung ist Authentifizierungszustand, kein AgentMemory.

Bekannte Einschränkungen

• Nur eine Replica. Rate-Limits sind im Speicher (im Speicher).

• Keine Passwort-Zurücksetzung. Wenn das Kennwort verloren geht, SQLite aus Sicherung wiederhergestellt oder die Benutzertabelle wird gelöscht und der Administrator neu geseedet.

• Kein Dashboard und keine Mehrbenutzerunterstützung.

• Der MCP-Handler behält den alten (2025)-Legacy-Protokoll des offiziellen SDKs im zustandslosen Modus bei, sodass ChatGPT und Notion nicht abgewiesen werden. Der OAuth-Stack folgt den aktuellen Better-Auth-MCP-APIs, einschließlich CIMD plus explizitem DCR.

• Die von ChatGPT angebundene mTLS-Client-Authentifizierung wird am HTTPS-Endpunkt beendet und nicht in diesem Prozess überprüft.

Cloud-Agenten

Cursor 要用 .cursor/environment.json:

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

• install — aktualisiert agentfiles und führt npm ci aus, wenn package-lock.json liegt

Die lokale Entwicklung verwendet über .nvmrc dieselbe Node-Version für das Cloud-Image. Die Gateway-Laufzeit selbst zielt auf Node 22.