agentmemory-mcp-gateway

단일 사용자용 OAuth 2.1 게이트웨이로, 원격 클라이언트에 소규모 AgentMemory MCP 도구 세트를 노출합니다.

MCP 클라이언트는 이 서비스에 인증합니다. 이 서비스는 AgentMemory에 인증합니다. AgentMemory 백엔드 시크릿은 게이트웨이를 절대 벗어나지 않습니다.

기능

• /mcp에서 Streamable HTTP를 통해 원격 MCP 통신을 처리합니다.

• OAuth 권한 부여 서버이자 보호 리소스로 작동합니다.

• 사전에 시드된 정확히 한 명의 사용자만 로그인하고 동의를 부여할 수 있습니다.

• 허용 목록에 등록된 tools/list 및 tools/call 트래픽을 AgentMemory REST로 전달합니다.

• AgentMemory를 사용할 수 없으면 차단(fail-closed) 방식으로 실패합니다.

대상 클라이언트: 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 메타데이터, 허용 목록에 포함된 도구 스키마/결과만 볼 수 있습니다.

• AgentMemory는 Railway 프라이빗 네트워킹에만 존재합니다. 클라이언트는 AGENTMEMORY_URL이나 AGENTMEMORY_SECRET을 절대 받을 수 없습니다.

• 수신되는 Authorization 헤더는 클라이언트 액세스 토큰을 검증하는 데만 사용됩니다. 게이트웨이는 업스트림 호출을 위해 항상 새 Authorization: Bearer ${AGENTMEMORY_SECRET} 헤더를 생성합니다.

• SQLite는 인증 및 OAuth 상태만 저장합니다. 메모리 데이터베이스가 아닙니다.

이 서비스는 AgentMemory와 분리된 별도의 Railway 서비스입니다. 정확히 하나의 레플리카로 실행하세요.

@agentmemory/mcp 대신 REST를 사용하는 이유

@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 볼륨에는 쓸 수 없습니다. /data가 마운트된 후 배포된 컨테이너 안에서 시드하세요.

로컬

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를 출력한 다음 HTTP 포트를 열지 않고 0으로 종료합니다.

5. ADMIN_PASSWORD와 ADMIN_EMAIL을 제거한 후 다시 시작합니다. 이제 프로세스는 HTTP를 제공합니다.

6. 사용자가 이미 존재하는데 두 변수가 모두 계속 설정돼 있다면, 시작 시 해당 변수들을 제거해야 한다는 로그를 남기고 0으로 종료하여 Railway가 crash-loop에 빠지지 않게 합니다.

7. ADMIN_EMAIL 또는 ADMIN_PASSWORD 중 하나만 설정된 경우, 시작은 차단(fail-closed)되며 HTTP를 제공하지 않습니다.

볼륨 생성 후 컨테이너 안에서 수동으로 동일하게 처리하는 방법:

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

프로덕션 시드에는 railway run npm run seed-admin을 사용하지 마세요. 해당 명령은 사용자 컴퓨터에서 실행됩니다.

단일 사용자가 존재하고 시드 변수가 제거되기 전에는 프로덕션 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) 아래의 절대 파일 경로인지 확인하고, 해당 디렉터리와 SQLite/WAL/SHM 파일만 chown한 후 node가 실행되기 전에 UID/GID 10001로 권한을 낮춥니다. /나 기타 상위 디렉터리를 재귀적으로 chown하지 않습니다. /data에 영구 볼륨을 마운트하세요.

Railway

1. 이 리포지토리에서 새 서비스를 만드세요. AgentMemory 서비스에 배포하지 마세요.

2. 리포지토리 루트의 Dockerfile / railway.json을 사용하세요.

3. /data에 마운트되는 영구 볼륨을 연결하세요. Railway는 볼륨을 root로 마운트하며 이미지의 /data 디렉터리를 대체합니다.

4. 엔트리포인트가 /data를 chown할 수 있도록 RAILWAY_RUN_UID=0을 설정한 뒤 UID 10001로 권한을 낮추세요. 이 이미지는 시작 후에도 요청을 계속하는 등 엔트포인트를 지원합니다.

5. 레플리카를 1로 설정하세요. 단일 SQLite 볼륨은 안전하게 공유할 수 없습니다.

6. 위 환경 변수를 설정하세요. http://<agentmemory-service>.railway.internal:3111 같은 비공개 AgentMemory URL을 사용하세요.

7. 공개 커스텀 도메인을 연결하고 그 정확한 https:// 오리진으로 PUBLIC_URL을 설정하세요.

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 Custom Agents 연결

1. 필요하면 Notion 워크스페이스에서 커스텀 MCP 서버를 활성화하세요.

2. 커스텀 MCP 서버 URL을 추가하세요: https://<your-domain>/mcp.

3. Notion은 OAuth를 사용하며, 클라이언트가 사전 등록되지 않은 경우 일반적으로 DCR을 사용합니다.

4. 시드된 사용자로 로그인하고 동의를 승인하세요.

5. 에이전트가 사용할 도구만 활성화하세요.

기본 종단 간 검증

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 호출은 보호 리소스 메타데이터를 가리키는 WWW-Authenticate 챌린지와 함께 401을 반환해야 합니다. 실제 클라이언트 로그인 후에는 tools/list가 허용 목록의 도구만 표시해야 합니다.

클라이언트 및 토큰 폐기

SQLite는 OAuth 클라이언트, 리프레시 토큰, 동의의 원본 데이터입니다.

• 서명 키 자료를 무효화하고 신중하게 다시 시드할 의도가 있을 때만 BETTER_AUTH_SECRET을 삭제하거나 회전하세요.

• oauthClient 행과 관련 토큰 및 동의 레코드를 제거하면 해당 클라이언트가 폐기됩니다.

• SQLite 파일을 교체하면 모든 클라이언트가 로그아웃됩니다.

관리자 API는 없습니다. 특정 클라이언트를 폐기해야 하는 경우 볼륨에서 일회성 sqlite3 세션을 사용하세요.

백업 및 복구

서비스가 중지된 상태에서 /data/oauth.sqlite와 -wal/-shm 파일을 함께 복사하거나 sqlite3 .backup을 사용하세요. 볼륨이 유실되면 모든 OAuth 클라이언트가 다시 연결해야 하고 관리자를 다시 시드해야 합니다. 이 백업은 인증 상태이지, AgentMemory 데이터베이스가 아닙니다.

알려진 제한 사항

• 레플리카 한 개만 지원합니다. 레이트 제한은 인메모리로만 유지됩니다.

• 비밀번호 재설정이 없습니다. 비밀번호를 잊은 경우 SQLite를 백업에서 복원하거나 사용자 테이블을 삭제한 뒤 다시 시드하세요.

• 대시보드가 없고 다중 사용자도 지원하지 않습니다.

• MCP 핸들러는 ChatGPT와 Notion이 거부되지 않도록 공식 SDK 레거시(2025) 프로토콜 지원을 stateless 모드로 유지합니다. OAuth 스택은 CIMD 및 명시적 DCR을 포함한 최신 Better Auth MCP API를 따릅니다.

• ChatGPT가 알리는 mTLS 클라이언트 인증은 HTTPS 엣지에서 종료되며 이 프로세스 내부에서 검증되지 않습니다.

클라우드 에이전트

Cursor Cloud는 .cursor/environment.json을 사용합니다.

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

• install — package-lock.json이 있으면 agentfiles를 갱신하고 npm ci를 실행합니다.

로컬 개발은 클라우드 이미지에서 .nvmrc를 통해 동일한 Node 버전을 사용합니다. 게이트웨이 런타임 자체는 Node 22를 대상으로 합니다.