agentmemory-mcp-gateway

单用户 OAuth 2.1 网关，通过远程客户端直接提供一组轻度封装的 AgentMemory MCP 工具。

MCP 客户端向此服务进行身份验证。此服务向 AgentMemory 进行身份验证。AgentMemory 后端密钥绝不会残留在这个网关之外。

功能

• 通过 Streamable HTTP 在 /mcp 上实现远程 MCP 对话

• 作为 OAuth 授权服务器和受保护资源

• 仅允许一个预先植入的用户登录并授予同意

• 将允许列表中的 tools/list 和 tools/call 流量转发给 AgentMemory REST

• 当 AgentMemory 不可用时，失败关闭

适用客户端：ChatGPT、Notion Custom Agents、Codex 云，以及其他符合标准的远程 MCP 客户端。

公共 URL 形式：

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

Related MCP server: Remote MCP Server

架构

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

信任边界：

• MCP 客户端只看到公共 HTTPS 源、OAuth 元数据以及允许列表中的工具 schema/结果。

• AgentMemory 保持通过 Railway 的私有网络。客户端永远不会得到 AGENTMEMORY_URL 或 AGENTMEMORY_SECRET。

• 传入的 Authorization 头只用于校验客户端访问令牌。网关总是为上游调用构造新的 Authorization: Bearer ${AGENTMEMORY_SECRET} 头。

• SQLite 只存储身份验证和 OAuth 状态。它不是 agent 的记忆数据库。

这是一个独立于 AgentMemory 的 Railway 服务。只运行一个副本。

为什么用 REST 而不是 @agentmemory/mcp

@agentmemory/mcp 在上游不可达时可以回退到本地记忆数据库。对于一个远程个人网关来说，这是不可接受的。

此服务只调用：

• GET /agentmemory/mcp/tools

• POST /agentmemory/mcp/call，请求体为 { "name": string, "arguments": object }

如果 AgentMemory 宕机、畸形或超时，网关返回安全的 MCP 错误。它不会创建、打开或写入任何其他记忆存储。

为什么 SQLite 存在

位于 DATABASE_PATH（默认 /data/oauth.sqlite）的 SQLite 保存着：

• 一个用户和密码哈希

• 会话和同意记录

• OAuth 客户端注册信息

• 授权码

• 访问/刷新令牌和吊销状态

• 签名密钥 / JWKS

它绝不存储 AgentMemory 的观测值或嵌入向量。

内存中的速率限制器也是单副本专用的。不要横向扩展此服务。

严格单用户模式

• 仅支持邮箱/密码

• 不支持 GitHub、社交登录、魔法链接、邀请或密码找回

• 没有公开注册，也没有用户管理 API

• 客户端注册（CIMD / DCR）不是计算机注册

• 只有种子用户的持久性 ID 才能登录、批准同意或获得可用的 MCP 令牌

• 如果用户表不包含确切的一行，则生产环境启动失败

认证错误是通用的，不会透露某个邮箱是否存在。

环境

PUBLIC_URL 是 /mcp 的唯一发行者和源。受保护资源标识符为 ${PUBLIC_URL}/mcp。

复制 .env.example。其中只包含占位符。

本地开发

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

有用的检查：

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

安全的一次性管理员种子

railway run 只会把变量注入本地命令。它不能写入 Railway volume。在 /data 挂载后，在容器内执行 seed。

本地

npm run seed-admin
# remove ADMIN_PASSWORD from .env

生产镜像 / Railway

镜像包含 dist/seed-admin.js，并使用 node dist/start.js 启动。

1. 在 1Password 中生成一个长的随机密码。不要把它存进 git、SQLite、Docker 或日志。

2. 在该服务上设置临时的 ADMIN_EMAIL 和 ADMIN_PASSWORD（20 个以上字符）。

3. 部署并重启，使容器在挂载 /data 后启动。

4. 在设置了这些变量的情况下，node dist/start.js 会以进程内方式运行 node dist/seed-admin.js，打印持久用户 ID，并启动 0，而不开放 HTTP 端口。

5. 删除 ADMIN_PASSWORD 和 ADMIN_EMAIL，然后重启。随后进程才开始提供 HTTP。

6. 如果用户存在后这两个变量仍存在，启动时会输出日志，要求移除它们并退出 0，避免 Railway 无限循环。

7. 如果 ADMIN_EMAIL 或 ADMIN_PASSWORD 只设置了一个，则启动会失败关闭，不会提供 HTTP。

卷存在后的手工容器内等效操作：

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

不要用 railway run npm run seed-admin 做生产环境 seed。该命令会在你的机器上运行。

生产环境的 HTTP 进程在系统上运行，直到存在一个用户且种子变量被清除。

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

入口点以 root 启动，验证 DATABASE_PATH 是 /data（或 RAILWAY_VOLUME_MOUNT_PATH）下的绝对文件路径，只 chown 该目录以及 SQLite/WAL/SHM 文件，然后在运行 node 之前降级到 UID/GID 10001。它绝不会递归 chown / 或其他父级。请在 /data 中挂载一个持久化 volume。

Railway

1. 为此仓库创建一个新服务。不要部署到 AgentMemory 服务上。

2. 使用模板根目录中的 Dockerfile / railway.json。

3. 挂载一个持久 volume 到 /data。Railway 会以 root 模式挂载 volume，并替换镜像中的 /data 目录。

4. 设置 RAILWAY_RUN_UID=0，这样入口点可以 chown /data，然后降级到 UID 10001。让进程以 root 运行是一种权衡；这个镜像在启动后不会再保留 root。

5. 将副本数设置为 1。单个 SQLite 卷不能安全共享。

6. 设置上述环境变量。使用私有 AgentMemory URL，例如 http://<agentmemory-service>.railway.internal:3111。

7. 挂载公共自定义域名，并将 PUBLIC_URL 设置为该 https:// 源。

8. 按照上文容器内步骤一次性种子管理员，然后删除临时密码变量。

9. 确认 GET /healthz 返回 {"ok":true}。

不要把 AgentMemory 暴露到公网。网关本身是唯一的公共 MCP 端点。

连接 ChatGPT

1. 基于一个 HTTPS 源和位置 /mcp 进行部署。

2. 在 ChatGPT 中添加远程 MCP / 连接器 URL：https://<your-domain>/mcp。

3. 如果 ChatGPT 支持 CIMD，优先使用它。DCR 仍可作为备选。

4. 以种子用户身份完成托管登录和授权流程。

5. 确认 memory_recall、memory_smart_search 和 memory_save 三个工具都有出现。

ChatGPT 会自动发现 /.well-known/oauth-protected-resource 和授权服务器元数据。

连接 Notion 自定义 Agent

1. 如果需要，先在 Notion 工作区中启用自定义 MCP 服务器。

2. 添加自定义 MCP 服务器 URL：https://<your-domain>/mcp。

3. Notion 会采用 OAuth，通常使用 DCR，除非客户端已预先注册。

4. 使用种子用户登录并批准授权。

5. 只启用该 Agent 应该使用的工具。

基本的端到端验证

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

/mcp 调用必须返回 401，并带有指向受保护资源元数据的 WWW-Authenticate 挑战。在真实客户端登录后，tools/list 必须只显示允许列表内的工具。

吊销客户端和令牌

SQLite 是 OAuth 客户端、刷新令牌和授权记录的权威来源。

• 仅在你想使签名材料失效并小心重新种子时，才删除或轮换 BETTER_AUTH_SECRET。

• 删除一个 oauthClient 行、相关的令牌和同意记录，即可吊销该客户端。

• 替换 SQLite 文件会使所有客户端都退出登录。

没有管理 API。如果需要吊销某个特定客户端，可以对 volume 执行一次性 sqlite3 命令。

备份和恢复

在服务停止后，把可以连同 /data/oauth.sqlite 和 -wal/-shm 文件一起复制，或者使用 sqlite3 .backup。丢失 volume 意味着所有 OAuth 客户端必须重新连接，管理员也需要再次种子。这个备份内容是认证状态，不是 AgentMemory。

已知限制

• 仅支持单副本。速率限制在内存中。

• 不支持密码找回。如果密码丢失，只能从备份恢复 SQLite，或者删除用户表后重新 seed。

• 没有仪表板，不支持多用户。

• MCP 处理器会保留官方 SDK 的传统 （2025） 无状态协议支持，以便 ChatGPT 和 Notion 不被拒绝。OAuth 栈遵循当前 Better Auth MCP API，包括 CIMD 和显式 DCR。

• ChatGPT 宣传的 mTLS 客户端身份验证在 HTTPS 边缘终止，不会在此内部进程内进行验证。

云 Agent

Cloud Agent 使用 .cursor/environment.json：

• Dockerfile — Ubuntu 24.04，Node 24（nvm），npm 和 agentfiles

• install — 刷新 agentfiles，并在存在 package-lock.json 时运行 npm ci

本地开发通过 .nvmrc 使用与 cloud image 相同的 Node 版。网关运行时本身目标为 Node 22。