MCP Server Base v3.0 — Scale & Enterprise (2026)

최신 스택을 사용하는 현대적인 Model Context Protocol 서버:

• MCP SDK 1.12+ — McpServer 고수준 API + StreamableHTTPServerTransport (신규) & StdioServerTransport

• TypeScript 5.7 ESM + NodeNext 모듈

• Zod 검증 → 자동 JSON Schema + 환경 검증 (src/config.ts:1)

• Express 4 + helmet + CORS 허용 목록 + 속도 제한 + health/ready + 관리자 UI

• 이중 전송: STDIO (Claude Desktop) 및 Streamable HTTP (원격, 2025-03 스펙, 무상태 + RedisEventStore를 통한 상태 저장 재개 가능)

• 구조화된 도구/리소스/프롬프트 모듈 + RAG 하이브리드 (BM25+벡터), 웹 (캐시됨), GitHub 통합

• 플러그인 SDK (src/plugin/index.ts:1) + 통합 (slack/notion/linear), 레지스트리 (smithery.yaml, mcpName), /admin의 프롬프트 플레이그라운드

• v3.0 엔터프라이즈: 멀티 테넌트 (X-Tenant-Id, 네임스페이스 스토어), SSO OIDC, 컨트롤 플레인 CRUD, 클러스터 모드, Prometheus/Grafana 스택

• OTEL 트레이싱/메트릭 (src/utils/otel.ts:1), 태스크 (실험적 + create_task), k6 부하 테스트

• tsx 감시, vitest (178개 테스트, 88% 커버리지), 정상 종료, docker-compose (redis, postgres, qdrant, otel-collector, prometheus, grafana)

🚀 빠른 시작

npm install
npm run build

# STDIO (for Claude Desktop, Cursor, opencode, etc.)
npm start

# HTTP (Streamable HTTP - latest)
npm run start:http
# → http://localhost:3000/mcp
# → health http://localhost:3000/health

개발

npm run dev          # stdio watch
npm run dev:http     # http watch (Streamable HTTP at http://localhost:3000/mcp)
npm test             # unit + e2e (InMemory + HTTP)
npm run test:coverage # coverage 80% thresholds
npm run lint         # eslint 9 flat config
npm run format:check # prettier
npm run typecheck    # tsc --noEmit
npm run build

CI

.github/workflows/ci.yml는 push/PR 시 main 브랜치에서 Node 20+22 매트릭스로 실행됩니다: lint, format:check, typecheck, test:coverage, build, docker build.

Related MCP server: TokenHub MCP

🔌 전송

Streamable HTTP는 SSE(2025년 3월 폐지)를 대체하는 새 표준입니다.

🧰 도구 (40)

📦 리소스 (6)

• config://server-info — 서버 메타데이터 (JSON, 이제 features 포함)

• greeting://{name} — 동적 인사말 템플릿

• file:///{+path} — 샌드박스 파일 (ALLOWED_ROOT), 목록 + 완성, file:///notes.txt

• memory://{key} — 메모리 KV, 목록 + 완성

• db://{table}/{id} — 데모 DB 행 (users/notes), 목록 + 완성

• docs://{id} — RAG 청크 (rag_ingest로 수집), 목록 + 완성

💬 프롬프트 (4)

• code-review — 인자: language, code

• explain-concept — 인자: concept, level

• summarize — 인자: text, length (short/medium/long), style (bullets/paragraph/tldr)

• research — 인자: topic, depth (overview/deep), audience (beginner/expert/executive)

⚙️ 클라이언트 구성

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mcp-server-base": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

HTTP 클라이언트

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp')));
const tools = await client.listTools();

Inspector

npm run inspect
# or
npx @modelcontextprotocol/inspector node dist/index.js
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

🐳 Docker

# Single container
docker build -t mcp-server-base .
docker run -p 3000:3000 --env TRANSPORT=http mcp-server-base

# Full stack (app + redis + postgres + qdrant) — see docker-compose.yml
docker compose up -d
docker compose logs -f app
# → http://localhost:3000/health, http://localhost:3000/mcp
# → redis :6379, postgres :5432, qdrant :6333

RAG 데모 (수집 → 검색 → docs://)

# via MCP tools (Inspector or Client)
# 1. ingest
rag_ingest { "text": "MCP is Model Context Protocol...", "id": "mcp-intro" }
# 2. search
rag_search { "query": "what is MCP?", "topK": 3 }
# 3. read resource
# docs://mcp-intro  → returns ingested text

📁 구조

src/
├── index.ts              # entry: stdio + http (helmet/cors/rateLimit/auth/RBAC/OTEL/metrics)
├── server.ts             # createMcpServer() factory (v2.1.0, instructions)
├── config.ts             # zod env (AUTH, CORS, rateLimit, RAG, cache, integrations, OTEL, admin, tasks)
├── types.ts              # Zod schemas
├── middleware/auth.ts    # AUTH_MODE none|apiKey|bearer
├── middleware/rateLimit.ts
├── middleware/requestId.ts
├── middleware/rbac.ts    # RBAC reader/writer/admin + mcpRbacMiddleware (v2.1)
├── observability/otel-real.ts # OTEL NodeSDK init (v2.1)
├── observability/slo.ts  # checkSlo() for /health/ready (v2.1)
├── utils/logger.ts       # stderr, JSON/text, redaction, child(requestId)
├── utils/eventStore.ts   # InMemoryEventStore
├── utils/redisEventStore.ts # RedisEventStore (scale)
├── utils/cache.ts        # MemoryCache (TTL) + defaultCache
├── utils/queue.ts        # SimpleQueue
├── utils/metrics.ts      # prom-client Registry (v2.1)
├── utils/persistence.ts  # save/load backup (v2.1)
├── utils/otel.ts         # stub OTEL spans/metrics
├── tools/                # 40 tools: echo, fs, memory, db, shell, rag (hybrid), web, github, elicitation, sampling, tasks
│   ├── filesystem.tool.ts, memory.tool.ts, database.tool.ts, shell.tool.ts
│   ├── rag.tool.ts, web.tool.ts, github.tool.ts, elicitation.tool.ts, sampling.tool.ts, tasks.tool.ts
├── plugin/index.ts       # Plugin SDK: definePlugin/registerPlugin (v2.2)
├── integrations/         # slack/notion/linear plugins (v2.2)
├── middleware/tenant.ts  # Multi-tenant X-Tenant-Id + scoped stores (v3.0)
├── routes/controlplane.ts# Tenants CRUD + key rotation (v3.0)
├── utils/cluster.ts      # Cluster mode horizontal scale (v3.0)
├── resources/            # 6 resources: config, greeting, file, memory, db, docs
├── routes/admin.ts       # Admin UI + metrics/spans/stores (v2.0) + /metrics Prometheus (v2.1)
└── prompts/              # 4 prompts: code-review, explain-concept, summarize, research

새 도구 추가: src/tools/my.tool.ts 생성 → registerMyTool(server) 내보내기 → src/tools/index.ts에 추가.

🔐 보안 (2단계)

• Helmet 헤더 (x-dns-prefetch-control, x-frame-options, x-content-type-options 등) helmet@7을 통해 (src/index.ts:1)

• CORS 허용 목록 (CORS_ORIGIN=* 또는 쉼표 목록) 및 cors 자격 증명 처리 (src/config.ts:60)

• 인증 AUTH_MODE=none|apiKey|bearer (src/middleware/auth.ts:1) — 유효한 X-API-Key 또는 Authorization: Bearer가 없으면 401 (health/ready 및 OPTIONS 제외)

• 속도 제한 /mcp에 express-rate-limit (기본 100/15분) — 429 Too Many Requests (src/middleware/rateLimit.ts:1)

• RequestId (X-Request-Id randomUUID, 에코 헤더, 하위 로거 상관관계) (src/middleware/requestId.ts:1)

• Zod 환경 검증 (src/config.ts:1) — parseEnv()가 PORT, AUTH_MODE, API_KEY를 교차 필드로 검증하고, 잘못된 환경에서 빠르게 실패

• 구조화 로거 JSON/텍스트, authorization, apiKey, token에 대해 [REDACTED] (src/utils/logger.ts:24)

• 재개 가능성 InMemoryEventStore (src/utils/eventStore.ts:1) + RESUMABILITY_ENABLED=true일 때 상태 저장 세션 맵 (Last-Event-ID로 재생, GET /mcp 스트림, DELETE 종료)

• Docker 강화 비루트 appuser + HEALTHCHECK (Dockerfile:1)

• 테스트: tests/unit/auth.test.ts, tests/unit/logger.test.ts, tests/unit/eventStore.test.ts, tests/e2e/security.test.ts (helmet/auth/rateLimit/resumability) — 67개 테스트 → 5단계 포함 총 130개, 90.89% 커버리지

🔗 통합 (4단계)

• 캐시 MemoryCache TTL (src/utils/cache.ts:1) — 웹/github용 defaultCache, SimpleQueue (src/utils/queue.ts:1)

• RAG 로컬 벡터 (해시 임베딩 128차원, 코사인, 청크 500/50) (src/tools/rag.tool.ts:1) — rag_ingest (청크 + sendResourceListChanged), rag_search (topK, threshold), rag_list, rag_clear + docs://{id} 리소스

• 웹 src/tools/web.tool.ts:1 — brave_search (BRAVE_API_KEY 없으면 모의), tavily_search (모의), web_fetch (defaultCache로 캐시, CACHE_TTL_MS)

• GitHub src/tools/github.tool.ts:1 — github_search_repos, github_get_repo, github_get_issue (캐시됨, 속도 제한용 GITHUB_TOKEN)

• 스택 docker-compose.yml:1 (app + redis:7 + postgres:16 + qdrant:v1.12.4) 헬스체크 포함

• 데모 rag_ingest → rag_search → docs:// E2E 검증 (tests/integrations.test.ts:1, 21개 테스트)

🏢 Scale & Enterprise (5단계 — v3.0) — 신규

• 멀티 테넌트 src/middleware/tenant.ts:1 — X-Tenant-Id 헤더(또는 ?tenant=), tenantMiddleware는 TENANT_REQUIRED=true이고 누락된 경우 400을 거부하며, 테넌트 범위 메모리 getTenantMemory(tid)(격리된 저장소), 네임스페이스 캐시 키 tenant:{id}:key, 레지스트리 createTenant/deleteTenant

• SSO OIDC src/middleware/auth.ts:1 — AUTH_MODE=oidc: Bearer JWT 구조 검증(3부분, exp, iss vs OIDC_ISSUER, aud vs OIDC_AUDIENCE), 클레임은 req.oidcClaims에 첨부, 프로덕션에서는 JWKS 서명 검증으로 교체

• 컨트롤 플레인 src/routes/controlplane.ts:1 — CRUD /admin/tenants (POST/GET/PATCH/DELETE + 409 중복/400 잘못된 ID), POST /admin/tenants/:id/rotate-key, GET /admin/tenants/:id/store 격리 검사, admin 토큰으로 보호

• 런타임 스케일 src/utils/cluster.ts:1 — initCluster()는 CLUSTER_WORKERS(기본 CPU-1)를 포크하고, 워커 종료 시 자동 재시작, CLUSTER_MODE=true, 무상태 + RedisEventStore로 진정한 수평 확장

• 모니터링 스택 docker-compose.override.yml:1 — Prometheus(prometheus.yml이 app:3000/metrics 스크랩) :9090 + Grafana :3001

• 테스트 tests/v3_0.test.ts:1 (15개 테스트: 테넌트 추출/격리/필수-400, OIDC 토큰 검증 + 발급자/대상 + HTTP 401/200, 컨트롤 플레인 수명주기 201/409/400/404/rotate-key/저장소 검사/비활성-404, 클러스터 no-op, compose 서비스) — 총 178

🔌 생태계 및 개발자 경험 (단계 5 — v2.2)

• 플러그인 SDK src/plugin/index.ts:1 — definePlugin({name, version, register}), registerPlugin(server, plugin) (중복 허용), getRegisteredPlugins(), 자동 sendToolListChanged 알림

• 통합 src/integrations/ — slackPlugin (list/post/search), notionPlugin (search/get/create), linearPlugin (list/create/get) — 모두 토큰 없이 모킹됨 (SLACK_TOKEN, NOTION_TOKEN); src/server.ts:1에서 자동 등록

• 레지스트리 smithery.yaml:1 — Smithery 구성 + MCP 레지스트리 이름 io.github.ahmedalbanna/mcp-server-base, package.json:1의 mcpName/files 필드

• 하이브리드 RAG src/tools/rag.tool.ts:1 — rag_search 모드 vector|bm25|hybrid (기본 hybrid, alpha 0.5), BM25 (k1=1.5, b=0.75) 정규화 + 코사인 재순위화; 평가 세트 tests/eval/rag-eval.json (20 Q/A) 및 p@5 ≥0.8이 tests/v2_2.test.ts:1에서 검증됨

• 프롬프트 플레이그라운드 src/routes/admin.ts:1 — POST /admin/prompts/:name/preview 서버 측에서 프롬프트 렌더링; 플레이그라운드 UI는 /admin 대시보드에 있음

• 테스트 tests/v2_2.test.ts:1 (16개 테스트: 플러그인 SDK 정의/등록/중복/도구 호출 가능, 레지스트리 파일, 하이브리드 모드, 평가 p@5, 플레이그라운드 미리보기/UI/카운트) — 총 163

📈 확장 및 운영성 (단계 5 — v2.0)

• 버전 관리 MCP v2.0.0 (package.json:1, config.MCP_SERVER_VERSION) 및 마이너 버전별 지침 (src/server.ts:1)

• OTEL 추적/메트릭 (src/utils/otel.ts:1) — createSpan/withSpan, incrementCounter/recordHistogram, getMetrics/getSpans, OTEL_EXPORTER_OTLP_ENDPOINT용 JSON 내보내기 스텁, OTEL_ENABLED 플래그

• RedisEventStore (src/utils/redisEventStore.ts:1) — EventStore 구현 (storeEvent/replayEventsAfter 포함), 인메모리 폴백, 수평 확장용 eventStoreFactory.create() (EVENT_STORE_TYPE=memory|redis, REDIS_URL)

• 관리 UI (src/routes/admin.ts:1) — GET /admin (HTML 대시보드), /admin/tools|resources|prompts|metrics|spans|stores|health (JSON), ADMIN_TOKEN (X-Admin-Token)으로 보호, ADMIN_ENABLED 플래그

• 작업 (src/tools/tasks.tool.ts:1) — 실험적 delay_task (SDK 작업 사용 가능한 경우) + 폴백 create_task/get_task/get_task_result (인메모리, 폴링), SimpleQueue/MemoryCache 인프라

• 벤치 k6/load.js:1 — http_req_duration p(95)<100ms, stages 10→50 VUs, checks >99%, npm run bench / bench:local

• Compose docker-compose.yml:1은 이미 확장을 위해 redis/postgres/qdrant를 포함

• 테스트: tests/scale.test.ts:1 (OTEL 스팬/메트릭, RedisEventStore 재생, 캐시 TTL, 큐, 관리 HTML/메트릭/토큰/준비, 작업 생성/폴링, 버전, k6 스크립트) — 총 130개 (v2.1 포함 현재 147개)

• 배포 Fly.io/Cloud Run 준비 (무상태 + RedisEventStore), release.yml을 통한 GHCR, npm 2.0.0

🔒 강화 및 관찰 가능성 (단계 5 — v2.1) — 신규

• OTEL Real src/observability/otel-real.ts:1 — initOtel()은 @opentelemetry/sdk-node + OTLPTraceExporter (콘솔 폴백)를 동적으로 가져오며, OTEL_ENABLED + OTEL_EXPORTER_OTLP_ENDPOINT, SIGTERM 시 정상 shutdown

• SLOs src/observability/slo.ts:1 — checkSlo() (메모리/RAG/캐시/업타임, latencyMs), GET /health → {status, checks, uptime, version, otel, eventStore} + GET /ready → ok가 아닌 경우 503, GET /metrics → prom-client를 통한 Prometheus text/plain (mcp_http_requests_total, mcp_http_request_duration_ms, mcp_sessions_active)

• RBAC src/middleware/rbac.ts:1 — reader < writer < admin (X-Role 헤더, JWT 스텁), TOOL_ROLES 맵 (31개 도구), mcpRbacMiddleware는 tools/call 본문을 검사하여 reader가 write_file/shell_execute를 시도하면 403 반환, GET /admin → admin 필요

• 백업 src/utils/persistence.ts:1 — saveBackup()/loadBackup()/scheduleSave() (500ms 디바운스)를 ALLOWED_ROOT/.backup.json로 저장 (동적 getBackupFile()), REDIS_URL 설정 시 Redis 동기화 스텁 로그, src/index.ts:1에서 시작 시 loadBackup()

• 메트릭 src/utils/metrics.ts:1 — prom-client Registry + collectDefaultMetrics, httpRequestsTotal/httpRequestDuration/mcpToolCallsTotal/mcpSessionsActive, GET /metrics 핸들러

• 테스트 tests/v2_1.test.ts:1 (13개 테스트: SLO 검사, RBAC hasRole/X-Role 403/200, SLO health/metrics 200 + Prometheus 텍스트, OTEL 스팬, 백업 저장/로드 + memory_set을 통한 scheduleSave, initOtel 비활성/활성) + tests/unit/rbac.test.ts:1 (4개 테스트) — 총 147

• 로거는 stderr 안전, 비밀을 절대 기록하지 않음 (수정)

• Zod → SDK를 통한 JSON Schema (src/types.ts:1, src/tools/*.tool.ts)

• fetch 타임아웃 (10초) + 구조화된 오류

• 정상 종료 (SIGINT/SIGTERM)

• MCP와 분리된 Health (GET /health) 및 ready (GET /ready)

• 기본 무상태 (sessionIdGenerator: undefined), RESUMABILITY_ENABLED=true일 때 상태 저장 (src/index.ts:22)

• 타입 안전, 엄격한 TS + ESLint flat + Prettier + husky + lint-staged

• 커버리지 85% 라인 / 70% 브랜치 강제 (vitest.config.ts:1), 178개 테스트: 단위 + e2e HTTP/보안/기능/통합/확장/v2.1/v2.2/v3.0

📚 문서

전체 문서는 docs/:

• 아키텍처 — 다이어그램, 모듈 맵, 요청 수명주기

• 구성 — 모든 환경 변수 + 검증 규칙

• API 참조 — 도구/리소스/프롬프트/엔드포인트

• 보안 — 인증, RBAC, OIDC, 테넌시, 강화 체크리스트

• 플러그인 — 플러그인 SDK 가이드 + 레지스트리 배포

• 배포 — Docker, 클러스터/다중 복제본 확장, 모니터링, k6

• 테스트 — 스위트 맵, 패턴, CI

🤝 기여

CONTRIBUTING.md 참조 — nvm use, npm test, 도구/리소스/프롬프트 추가, lint/typecheck/test 통과 확인. CODE_OF_CONDUCT.md 참조.

📚 MCP 문서

• 사양: https://spec.modelcontextprotocol.io

• SDK: https://github.com/modelcontextprotocol/typescript-sdk

• Inspector: https://github.com/modelcontextprotocol/inspector