MCPController

MCPController는 단일 관리자용 의사 관리 MCP 애플리케이션입니다. ChatGPT는 PKCE를 사용한 OAuth 2.1로 연결되며, 관리자가 로그인하여 부여할 의사 권한을 선택하면 MCP 서버가 MongoDB를 기반으로 하는 의사 도구를 노출합니다.

아키텍처

ChatGPT
  ↓
OAuth
  ↓
Admin Login
  ↓
Admin Consent
  ↓
Granted Permissions
  ↓
MCP Access Token
  ↓
MCP /mcp
  ↓
Permission Check
  ↓
Doctor Tools
  ↓
MongoDB

Related MCP server: GPT MCP Service

이 앱이 하는 일

• 한 명의 관리자가 전체 시스템을 소유합니다.

• 공개 회원가입이 없으며 다중 사용자 계정 전환도 없습니다.

• 관리자는 환경 변수의 자격 증명으로 인증합니다.

• 동의 화면에서 관리자가 doctor:read, doctor:write, doctor:delete를 승인할 수 있습니다.

• MCP 서버는 모든 도구 호출 시 승인된 범위를 다시 확인합니다.

• 의사 데이터는 간단한 Mongoose 모델을 통해 MongoDB에 저장됩니다.

인증

브라우저 세션은 MCP Bearer 토큰과 분리되어 있습니다.

• 브라우저 세션: 관리자 UI 및 동의 화면에 사용되는 HTTP-only 쿠키.

• MCP 액세스 토큰: ChatGPT가 /mcp에 대해 사용하는 Bearer 토큰.

• OAuth는 PKCE를 사용한 인가 코드 흐름을 사용합니다.

• 인가 코드는 일회용이며 수명이 짧습니다.

• 액세스 토큰과 리프레시 토큰은 저장 전에 해시됩니다.

관리자 로그인은 .env의 ADMIN_EMAIL과 ADMIN_PASSWORD를 사용합니다.

의사 관리

도메인 모델은 의도적으로 작게 유지됩니다:

• name - 필수 문자열

• specialization - 필수 문자열

• createdAt / updatedAt - Mongoose 타임스탬프로 관리

의사 CRUD는 서비스 계층에서 구현되며 REST 관리자 API와 MCP 도구 계층에서 모두 재사용됩니다.

OAuth 흐름

1. ChatGPT가 인가 엔드포인트를 엽니다.

2. 관리자가 인증되지 않은 경우 브라우저가 /login으로 이동합니다.

3. 관리자가 로그인합니다.

4. 동의 페이지에 요청된 의사 권한이 표시됩니다.

5. 관리자가 일부 권한을 승인하거나 요청을 거부합니다.

6. 인가 코드가 액세스 토큰으로 교환됩니다.

7. ChatGPT가 해당 토큰을 /mcp에서 사용합니다.

권한 흐름

요청된 범위는 다음과 같이 MCP 도구에 매핑됩니다:

• doctor:read → list_doctors, get_doctor

• doctor:write → add_doctor, update_doctor

• doctor:delete → delete_doctor

백엔드는 권한을 두 번 강제합니다:

• OAuth는 승인된 범위만 인가 코드와 토큰에 기록합니다.

• 각 MCP 도구는 MongoDB에 접근하기 전에 토큰 범위를 확인합니다.

MCP 도구

환경 변수

루트 .env 파일을 사용합니다. 애플리케이션은 프로젝트 루트에서 이 파일을 로드합니다.

로컬 npm run dev(Vite는 5173, API는 3000)에 필요한 값:

NODE_ENV=development
PORT=3000
APP_URL=http://localhost:5173
API_URL=http://localhost:3000
MONGODB_URI=mongodb://127.0.0.1:27017/mcpcontroller
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-password
JWT_SECRET=change-this-to-a-long-random-secret
MCP_SERVER_NAME=MCPController
MCP_SERVER_VERSION=1.0.0

코드는 안전한 기본값을 가진 토큰/세션 수명 변수도 지원합니다:

• JWT_EXPIRES_IN

• AUTH_CODE_TTL_SECONDS

• ACCESS_TOKEN_TTL_SECONDS

• REFRESH_TOKEN_TTL_SECONDS

Vercel에서는 APP_URL과 API_URL이 모두 공개 HTTPS 오리진이어야 합니다(아래 배포 참조).

로컬 설정

1. 의존성을 설치합니다:

npm install

2. MongoDB를 로컬에서 시작합니다.

3. 샘플 데이터를 시드합니다:

npm run seed

4. 앱을 시작합니다:

npm run dev

개발 환경에서 React 클라이언트는 Vite를 통해 실행되며 API 요청을 백엔드로 프록시합니다.

테스트

자동화된 검사를 실행합니다:

npm test

클라이언트 빌드를 실행합니다:

npm run build

현재 테스트 스위트는 다음을 포함합니다:

• 관리자 로그인

• 회원가입 비활성화

• 의사 모델 및 CRUD 서비스

• OAuth 범위 승인

• MCP 도구 권한 강제

• 토큰 폐기

ChatGPT 연결

서버가 노출하는 인가 URL을 사용합니다:

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource

• /oauth/token

• /mcp

일반적인 흐름:

1. ChatGPT가 OAuth 메타데이터를 발견합니다.

2. ChatGPT가 MCP 리소스에 대한 인가를 요청합니다.

3. 브라우저가 관리자 로그인 화면으로 리디렉션됩니다.

4. 관리자가 권한을 검토하고 Allow & Connect를 클릭합니다.

5. ChatGPT가 코드를 토큰으로 교환합니다.

6. ChatGPT가 Bearer 토큰을 사용하여 MCP 도구를 호출합니다.

배포

앱은 단일 오리진입니다: Express가 /api, /oauth, /mcp, OAuth 디스커버리, React 빌드를 제공합니다.

Vercel

이 저장소에는 이미 vercel.json과 api/index.js가 포함되어 있습니다. Vercel은 Express 앱을 하나의 서버리스 함수로 실행하고 모든 경로를 해당 함수로 재작성합니다.

1. MongoDB Atlas

1. 클러스터를 생성합니다(무료 M0이면 충분합니다).

2. 데이터베이스 사용자를 생성합니다.

3. 네트워크 액세스: Vercel이 연결할 수 있도록 0.0.0.0/0을 허용합니다(원하면 Vercel IP를 추가해도 됩니다).

4. 연결 문자열을 복사합니다. 예:

mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/mcpcontroller?retryWrites=true&w=majority

2. 프로젝트 배포

• 이 저장소를 GitHub에 푸시합니다.

• Vercel에서 저장소를 가져옵니다(Import).

• 프레임워크 프리셋: Other(그대로 둡니다). vercel.json이 설치 및 빌드를 설정합니다.

• 루트 디렉터리: 저장소 루트로 둡니다(client 또는 server로 설정하지 마세요).

• Node.js 버전: 20.x 이상.

3. Vercel 환경 변수

프로젝트 → 설정 → 환경 변수. 프로덕션용으로 설정합니다(프리뷰 URL을 사용하는 경우 프리뷰용으로도 설정).

ADMIN_PASSWORD 또는 JWT_SECRET을 React 앱에 넣지 마십시오. 클라이언트는 /api와만 통신합니다.

나중에 사용자 지정 도메인을 추가하면 APP_URL과 API_URL을 https://your-domain.com으로 변경하고 다시 배포합니다.

JWT_SECRET 생성:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

4. 첫 배포 및 시드

1. 배포합니다.

2. https://your-app.vercel.app/api/health를 엽니다 — { "ok": true, ... }가 표시되어야 합니다.

3. 로컬 머신에서 Atlas를 대상으로 MongoDB를 시드합니다(Vercel의 서버리스 함수가 아닌):

# In the project root, temporarily set MONGODB_URI to the Atlas URI in .env
npm run seed

시드는 Admin 사용자 행, 샘플 의사, 로컬 MCP Inspector 클라이언트를 생성합니다. 그런 다음 라이브 사이트에서 ADMIN_EMAIL / ADMIN_PASSWORD로 로그인합니다.

5. ChatGPT 연결

배포된 오리진을 사용합니다:

• https://your-app.vercel.app/.well-known/oauth-authorization-server

• https://your-app.vercel.app/.well-known/oauth-protected-resource

• https://your-app.vercel.app/mcp

ChatGPT(또는 MCP Inspector)에서 해당 MCP URL을 추가합니다. ChatGPT가 동일한 도메인에서 로그인 + 동의 화면을 연 다음 Bearer 토큰으로 /mcp를 호출합니다.

CLI 배포(선택 사항)

npm i -g vercel
vercel login
vercel env pull   # optional: sync env locally
vercel --prod

첫 프로덕션 배포 후 자리 표시자를 사용했다면 URL을 APP_URL과 API_URL에 복사한 다음 OAuth 메타데이터가 실제 오리진을 가리키도록 다시 배포합니다.

보안 참고 사항

• ADMIN_PASSWORD 또는 JWT_SECRET을 브라우저에 노출하지 마십시오.

• OAuth 토큰을 데이터베이스에 해시된 상태로 유지하십시오.

• 관리자가 실제로 ChatGPT에 사용하길 원하는 범위만 승인하십시오.

• 연결을 더 이상 신뢰할 수 없을 때 액세스를 폐기하십시오.

• 관리자 로그인은 ChatGPT를 인가하고 의사 데이터를 관리하기 위해서만 존재하며 공개 가입 흐름은 없습니다.

시드 데이터

시드 스크립트는 다음을 생성합니다:

• 샘플 의사

• 로컬 인스펙터 사용을 위한 샘플 OAuth 클라이언트

데모 사용자를 생성하거나 Admin 자격 증명을 하드코딩하지 않습니다.