agentmemory-mcp-gateway

Single-user OAuth 2.1 gateway that exposes a small AgentMemory MCP tool set to remote clients.

MCP clients authenticate to this service. This service authenticates to AgentMemory. The AgentMemory backend secret never leaves the gateway.

What it does

• Speaks remote MCP over Streamable HTTP at /mcp

• Acts as the OAuth authorization server and protected resource

• Allows exactly one pre-seeded human to sign in and grant consent

• Forwards allowlisted tools/list and tools/call traffic to AgentMemory REST

• Fails closed when AgentMemory is unavailable

Intended clients: ChatGPT, Notion Custom Agents, Codex cloud, and other standards-compliant remote MCP clients.

Public URL shape:

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

Related MCP server: Remote MCP Server

Architecture

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

Trust boundaries:

• MCP clients see only the public HTTPS origin, OAuth metadata, and allowlisted tool schemas/results.

• AgentMemory stays on Railway private networking. Clients never receive AGENTMEMORY_URL or AGENTMEMORY_SECRET.

• Incoming Authorization headers are used only to validate the client access token. The gateway always builds a new Authorization: Bearer ${AGENTMEMORY_SECRET} header for upstream calls.

• SQLite stores authentication and OAuth state only. It is not a memory database.

This is a separate Railway service from AgentMemory. Run exactly one replica.

Why REST instead of @agentmemory/mcp

@agentmemory/mcp can fall back to a local memory database when upstream is unreachable. That is unacceptable for a remote personal gateway.

This service calls only:

• GET /agentmemory/mcp/tools

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

If AgentMemory is down, malformed, or times out, the gateway returns a safe MCP error. It does not create, open, or write another memory store.

Why SQLite exists

SQLite at DATABASE_PATH (default /data/oauth.sqlite) holds:

• the one user and password hash

• sessions and consent

• OAuth client registrations

• authorization codes

• access/refresh-token and revocation state

• signing keys / JWKS

It never stores AgentMemory observations or embeddings.

The in-memory rate limiter is also single-replica only. Do not scale this service horizontally.

Strict single-user model

• Email/password only

• No GitHub, social login, magic links, invitations, or password recovery

• No public signup and no user-management API

• Client registration (CIMD / DCR) is not human registration

• Only the seeded user's durable ID may sign in, approve consent, or receive usable MCP tokens

• Production startup fails if the user table does not contain exactly one row

Authentication errors are generic. They do not disclose whether an email exists.

Hosted consent CSRF

GET /consent requires an authenticated session and renders a short-lived HMAC token into both the Allow and Deny forms. The token is bound to the session ID, the exact raw signed OAuth query, an expiry, and a consent-CSRF domain marker.

POST /consent accepts nothing else as proof. A missing, malformed, expired, forged, wrong-session, or wrong-query token returns 403 {"error":"Request denied"} and logs only a coarse reason such as csrf_expired. Browser Origin, Referer, and Fetch Metadata headers are neither trusted nor required, because hosted authentication windows (Safari in particular) send Origin: null and cross-site Fetch Metadata for a legitimate same-page form post.

After the token verifies, the gateway forwards the submission to Better Auth's /oauth2/consent with Origin pinned to PUBLIC_URL. Better Auth's own origin, CSRF, and signed-OAuth-query checks stay enabled, so a direct call to /oauth2/consent is still rejected.

Environment

PUBLIC_URL is the single issuer and the origin for /mcp. The protected resource identifier is ${PUBLIC_URL}/mcp.

Copy .env.example. It contains placeholders only.

Local development

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

Useful checks:

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

Secure one-time administrator seeding

railway run only injects variables into a local command. It cannot write to the Railway volume. Seed inside the deployed container after /data is mounted.

Local

npm run seed-admin
# remove ADMIN_PASSWORD from .env

Production image / Railway

The image includes dist/seed-admin.js and starts with node dist/start.js.

1. Generate a long random password in 1Password. Do not store it in git, SQLite, Docker, or logs.

2. Set temporary ADMIN_EMAIL and ADMIN_PASSWORD (20+ characters) on the service.

3. Deploy or restart so the container runs with /data mounted.

4. With those variables set, node dist/start.js runs node dist/seed-admin.js in-process, prints the durable user ID, and exits 0 without opening the HTTP port.

5. Remove ADMIN_PASSWORD and ADMIN_EMAIL, then restart. The process then serves HTTP.

6. If both variables are still set after a user exists, startup logs that they must be removed and exits 0 so Railway does not crash-loop.

7. If only one of ADMIN_EMAIL or ADMIN_PASSWORD is set, startup fails closed and does not serve HTTP.

Manual in-container equivalent after the volume exists:

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

Do not use railway run npm run seed-admin for production seeding. That command runs on your machine.

The production HTTP process will not start until that one user exists and the seed variables are gone.

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

The entrypoint starts as root, verifies DATABASE_PATH is an absolute file under /data (or RAILWAY_VOLUME_MOUNT_PATH), chowns only that directory plus the SQLite/WAL/SHM files, then drops to UID/GID 10001 before node runs. It never recursively chowns / or other parents. Mount a persistent volume at /data.

Railway

1. Create a new service from this repository. Do not deploy onto the AgentMemory service.

2. Use the Dockerfile / railway.json in the repo root.

3. Attach a persistent volume mounted at /data. Railway mounts volumes as root and replaces the image /data directory.

4. Set RAILWAY_RUN_UID=0 so the entrypoint can chown /data, then drop to UID 10001. Leaving the process as root is a tradeoff; this image does not keep root after startup.

5. Set replicas to 1. A single SQLite volume cannot be shared safely.

6. Set the environment variables above. Use the private AgentMemory URL, such as http://<agentmemory-service>.railway.internal:3111.

7. Attach the public custom domain and set PUBLIC_URL to that exact https:// origin.

8. Seed the administrator once with the in-container path above, then delete the temporary password variables.

9. Confirm GET /healthz returns {"ok":true}.

Do not put AgentMemory on the public internet for this flow. The gateway is the only public MCP endpoint.

Connecting ChatGPT

1. Deploy with a stable HTTPS origin and /mcp.

2. In ChatGPT, add a remote MCP / connector URL: https://<your-domain>/mcp.

3. Prefer CIMD if ChatGPT offers it. DCR remains enabled as a fallback.

4. Complete the hosted sign-in and consent screens as the seeded user.

5. Confirm memory_recall, memory_smart_search, and memory_save appear.

ChatGPT discovers /.well-known/oauth-protected-resource and the authorization-server metadata automatically.

Connecting Notion Custom Agents

1. Enable custom MCP servers in the Notion workspace if required.

2. Add a custom MCP server URL: https://<your-domain>/mcp.

3. Notion uses OAuth and typically DCR unless a client is preregistered.

4. Sign in as the seeded user and approve consent.

5. Enable only the tools that agent should use.

Basic end-to-end verification

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

The /mcp call must return 401 with a WWW-Authenticate challenge that points at protected-resource metadata. After a real client login, tools/list must show only the allowlisted tools.

MCP diagnostic logs

Railway shows HTTP status codes only, and MCP answers most protocol failures with HTTP 200 and a JSON-RPC error inside the body. Every /mcp exchange therefore writes one-line JSON to stdout, or stderr when it failed:

{"log":"mcp","ts":"...","event":"mcp.request","httpMethod":"POST","userAgent":"openai-mcp/1.0.0","envelope":"request","mcpMethod":"tools/list","rpcId":"2"}
{"log":"mcp","ts":"...","event":"agentmemory.list_tools.succeeded","upstreamStatus":200,"durationMs":2,"toolCount":3,"toolNames":["memory_recall","memory_smart_search","memory_save"]}
{"log":"mcp","ts":"...","event":"mcp.response","httpMethod":"POST","userAgent":"openai-mcp/1.0.0","envelope":"request","mcpMethod":"tools/list","rpcId":"2","httpStatus":200,"durationMs":4,"toolCount":3,"toolNames":["memory_recall","memory_smart_search","memory_save"]}

Filter Railway logs on "log":"mcp". Useful events:

mcp.response adds the negotiated protocolVersion and advertised capabilities for initialize, toolCount plus toolNames for tools/list, and rpcErrorCode plus rpcErrorMessage whenever the body carries a JSON-RPC error. A -32601 Method not found line names the exact MCP method a client wanted but this gateway does not implement.

src/mcp-log.ts is the only writer. It accepts strings, numbers, booleans, and string arrays; anything else logs as [unsupported]. Field names that could carry a credential log as [redacted], values are run through the same redaction as safeLog, and long values are truncated. Authorization headers, tokens, cookies, OAuth codes, tool arguments, tool results, memory contents, and request or response bodies are never logged.

Revoking clients and tokens

SQLite is the source of truth for OAuth clients, refresh tokens, and consent.

• Delete or rotate BETTER_AUTH_SECRET only if you intend to invalidate signing material and re-seed carefully.

• Removing an oauthClient row, related tokens, and consent records revokes that client.

• Replacing the SQLite file logs every client out.

There is no admin API. Use a one-off sqlite3 session against the volume if you need to revoke a specific client.

Backup and recovery

Copy /data/oauth.sqlite and the -wal/-shm files together while the service is stopped, or use sqlite3 .backup. A lost volume means every OAuth client must reconnect and the administrator must be seeded again. This backup is authentication state, not AgentMemory.

Known limitations

• One replica only. Rate limits are in-memory.

• No password reset. If the password is lost, restore SQLite from backup or delete the user table and seed again.

• No dashboard and no multi-user support.

• The MCP handler keeps official SDK legacy (2025) protocol support in stateless mode so ChatGPT and Notion are not rejected. The OAuth stack follows current Better Auth MCP APIs, including CIMD plus explicit DCR.

• mTLS client authentication advertised by ChatGPT is terminated at the HTTPS edge, not verified inside this process.

Cloud agents

Cursor Cloud uses .cursor/environment.json:

• Dockerfile — Ubuntu 24.04, Node 24 (nvm) with npm 11, and agentfiles

• install — refreshes agentfiles and runs npm ci when package-lock.json exists

Local development, CI, Docker, and the gateway runtime all use Node 24 and npm 11. .nvmrc is 24.