Nexian MCP Hub

Nexian MCP Hub는 각 테넌트가 타사 시스템을 연결하고 단일 원격 MCP 서버를 통해 정규화된 AI 안전 도구를 노출할 수 있도록 하는 멀티 테넌트 MSP 통합 플랫폼입니다.

모노레포 레이아웃

• apps/web: Next.js 관리자 및 최종 사용자 앱

• apps/api: 인증, 테넌트 관리, 커넥터, OAuth 콜백 및 감사 API를 위한 백엔드 API

• apps/mcp: 베어러 토큰으로 보호되는 HTTP 엔드포인트가 있는 원격 MCP 서버

• packages/core: 공유 도메인 유형, 보안 기본 요소, MCP 모델, 유효성 검사 도우미

• packages/connectors: 공급자 어댑터 및 정규화된 도구 구현

• prisma: Postgres 스키마 및 시드 준비 모델

• docker: 로컬 컨테이너 자산

• docs: 아키텍처, 배포 및 보안 참고 사항

로컬 설정

1. Node.js 22+ 및 pnpm을 설치합니다.

2. .env.example을 .env로 복사하고 공급자 자격 증명을 입력합니다.

3. 인프라를 시작합니다:

docker compose up -d

4. 종속성을 설치합니다:

pnpm install

5. Prisma 클라이언트를 생성하고 마이그레이션을 실행합니다:

pnpm db:generate
pnpm db:migrate

6. 스택을 시작합니다:

pnpm dev

Vercel 배포

apps/web Next.js 앱을 Vercel 프로젝트로 배포합니다.

권장되는 Vercel 설정:

• 루트 디렉토리: apps/web

• 설치 명령: pnpm install

• 빌드 명령: pnpm build

• 출력 디렉토리: Next.js 자동 감지를 위해 비워 둡니다.

Vercel에서 설정할 환경 변수:

• NEXT_PUBLIC_API_URL

• NEXT_PUBLIC_MCP_URL

• API_URL

• APP_URL

이 저장소는 apps/api와 apps/mcp를 별도의 Node 서비스로 유지합니다. 프로덕션 환경에서는 컨테이너 호스트에 배포하고 환경 변수를 통해 Vercel 프론트엔드를 해당 서비스로 지정하십시오.

Railway 배포

백엔드 분리를 위해 Railway를 사용합니다:

• Railway에서 apps/api 실행

• Railway에서 apps/mcp 실행

• Vercel에서 apps/web 실행

실제 설정 가이드는 다음 위치에 있습니다:

• docs/railway-vercel-deploy.md

중요한 프로덕션 환경 관계:

• APP_URL은 Vercel 웹 URL이어야 합니다.

• API_URL은 Railway API URL이어야 합니다.

• MCP_URL은 Railway MCP URL이어야 합니다.

• HALOPSA_REDIRECT_URI는 Railway API 콜백 URL을 가리켜야 합니다.

• Vercel의 NEXT_PUBLIC_API_URL은 Railway API URL을 가리켜야 합니다.

• Vercel의 NEXT_PUBLIC_MCP_URL은 Railway MCP 엔드포인트 URL을 가리켜야 합니다.

• SESSION_SECRET은 API 및 MCP 서비스 간에 일치해야 합니다.

제품 아키텍처

• 웹 사용자는 플랫폼에 인증하고 테넌트 작업 공간 내에서 활동합니다.

• 연결된 계정은 테넌트 및 사용자별로 저장되며, 액세스 및 새로 고침 토큰은 저장 시 암호화됩니다.

• API는 OAuth 콜백 처리, 토큰 새로 고침, 정책 확인, 감사 로깅 및 커넥터 수명 주기를 담당합니다.

• MCP 서버는 모든 HTTP 요청에서 Authorization: Bearer <token>을 검증하고 테넌트 인식 정책을 통해 각 도구 호출을 라우팅합니다.

• 공급자별 로직은 어댑터 내부에 유지되며, 정규화된 도구만 외부로 노출됩니다.

버전 1 커넥터 범위

• HaloPSA

• Microsoft 365 / SharePoint

• CRM으로서의 HubSpot

• 문서화 / KB로서의 IT Glue

가드레일

• 읽기 중심 도구 우선

• 초안 티켓 생성 및 내부 메모와 같은 저위험 워크플로우에 대해서만 안전한 쓰기 허용

• v1에서는 파괴적인 쓰기 없음

• 모든 도구 호출은 감사 이벤트를 생성함

다음 구현 마일스톤

1. API 모듈 스켈레톤에 실제 인증 및 지속성 연결.

2. Prisma 마이그레이션 및 데이터베이스 클라이언트 부트스트래핑 추가.

3. 커넥터 자리 표시자를 라이브 공급자 SDK 또는 REST 통합으로 교체.

4. OAuth, 토큰 새로 고침 및 MCP 도구 실행에 대한 통합 테스트 추가.