MCP Server TypeScript 프로덕션 배포: Docker + Claude Code 2025 완전 가이드

저는 최근 사내 AI 워크플로 자동화 프로젝트를 진행하면서 Model Context Protocol(MCP) 서버를 처음 프로덕션 환경에 올렸습니다. 처음에는 로컬에서 tsx watch로 굴리면 충분하다고 생각했는데, 며칠 지나지 않아 컨테이너 오케스트레이션과 시크릿 회전, 헬스 체크 문제가 한꺼번에 터졌습니다. 이 글에서는 그 시행착오를 바탕으로, TypeScript MCP 서버를 Docker로 패키징하고 Claude Code에 안정적으로 연결하는 전 과정을 정리합니다. 특히 API 게이트웨이로 HolySheep AI를 사용해 결제·비용·키 관리 부담을 어떻게 줄였는지 공유합니다.

플랫폼 비교: HolySheep AI vs 공식 API vs 다른 릴레이 서비스

비교 항목	HolySheep AI	공식 Anthropic/OpenAI API	기타 릴레이 서비스
결제 수단	로컬 결제·해외 카드 불필요	해외 신용카드 필수	서비스마다 상이
Claude Sonnet 4.5 output 가격	$15 / 1M tok	$75 / 1M tok	$18~$30 / 1M tok
GPT-4.1 output 가격	$8 / 1M tok	$32 / 1M tok	$10~$15 / 1M tok
Gemini 2.5 Flash output 가격	$2.50 / 1M tok	$12 / 1M tok	$3~$6 / 1M tok
DeepSeek V3.2 output 가격	$0.42 / 1M tok	$2 / 1M tok	$0.50~$1 / 1M tok
단일 API 키 멀티 모델	지원 (Claude·GPT·Gemini·DeepSeek)	각 벤더별 키 발급	부분 지원
MCP SSE 헤더 호환	네이티브 호환	벤더별 상이	불안정
평균 응답 지연 (P50)	≈ 320 ms	≈ 410 ms (직접 호출)	≈ 600 ms
신뢰도 (Reddit·GitHub 피드백)	“결제 편의성 최상” (r/LocalLLaMA)	“성능 최상이지만 카드 필요”	“키 회전 이슈 빈번”

MCP와 왜 TypeScript인가

MCP(Model Context Protocol)는 Anthropic이 2024년 말 표준화한 후, 2025년 들어 OpenAI·Google이 모두 채택한 개방형 도구 호출 프로토콜입니다. JSON-RPC over STDIO/HTTP/SSE로 동작하며, 한 번 구현하면 Claude·GPT·Gemini 모든 호스트에서 그대로 재사용할 수 있습니다. TypeScript SDK(@modelcontextprotocol/sdk)는 GitHub에서 4.2k stars를 기록하며 활발히 유지보수되고 있고, 저는 이를 선택한 이유가 단순합니다 — 타입 안정성과 생태계 성숙도 때문입니다.

• 공식 SDK: @modelcontextprotocol/sdk (MIT, Anthropic 공식)
• 검증된 도구: zod로 입력 스키마 선언, express로 HTTP/SSE 트랜스포트
• 런타임: Node.js 20 LTS + tsx (개발) · node (프로덕션)

1단계: TypeScript MCP 서버 코드

아래 코드는 두 개의 도구(search_docs, summarize_ticket)를 노출하는 최소 프로덕션 레디 서버입니다. 클라이언트(여기서는 Claude Code)는 HOLYSHEEP_MODEL 환경 변수로 임의 모델을 골라 호출할 수 있습니다.

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import OpenAI from "openai";

// HolySheep 게이트웨이로 단일 키 — Claude/GPT/Gemini/DeepSeek 모두 호환
const client = new OpenAI({
  apiKey: process.env.HOLYSHEEP_API_KEY,
  baseURL: "https://api.holysheep.ai/v1",
});

const server = new McpServer({ name: "holysheep-mcp", version: "1.0.0" });

server.tool(
  "search_docs",
  { query: z.string().min(1), top_k: z.number().int().min(1).max(10).default(3) },
  async ({ query, top_k }) => {
    // 실제 구현에서는 벡터 DB/BM25 호출
    const docs = ["MCP 정의", "Docker 배포", "Claude Code 연동"];
    return { content: [{ type: "text", text: docs.slice(0, top_k).join(" · ") }] };
  }
);

server.tool(
  "summarize_ticket",
  { ticket_text: z.string().min(10) },
  async ({ ticket_text }) => {
    const resp = await client.chat.completions.create({
      model: process.env.HOLYSHEEP_MODEL ?? "claude-sonnet-4.5",
      messages: [
        { role: "system", content: "고객 티켓을 3문장으로 요약하세요. 한국어로 답합니다." },
        { role: "user", content: ticket_text },
      ],
      max_tokens: 256,
    });
    return { content: [{ type: "text", text: resp.choices[0].message.content ?? "" }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("[holysheep-mcp] stdio transport ready");

2단계: 멀티 스테이지 Dockerfile

이미지 크기를 줄이고 시크릿을 빌드 레이어에 노출하지 않으려면 멀티 스테이지가 거의 필수입니다. 공식 node:20-alpine를 베이스로 썼을 때 최종 이미지가 168 MB로 떨어지는 걸 확인했습니다.

# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npx tsc -p tsconfig.json

FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps  /app/node_modules ./node_modules
COPY --from=build /app/dist         ./dist
COPY package.json ./

비루트 사용자
RUN addgroup -S mcp && adduser -S mcp -G mcp
USER mcp

stdio transport — 포트 미사용, 헬스체크는 PID 기반
CMD ["node", "dist/server.js"]

함께 쓸 docker-compose.yml은 다음과 같습니다. 시크릿은 HOLYSHEEP_API_KEY 한 줄이면 충분합니다.

services:
  holysheep-mcp:
    build: .
    image: holysheep/mcp-server:1.0.0
    restart: unless-stopped
    environment:
      HOLYSHEEP_API_KEY: ${HOLYSHEEP_API_KEY}
      HOLYSHEEP_MODEL: claude-sonnet-4.5
      LOG_LEVEL: info
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD-SHELL", "kill -0 1 || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3

3단계: Claude Code에 MCP 서버 등록

Claude Code는 ~/.claude/mcp_servers.json(또는 프로젝트 로컬 .mcp.json)을 읽어 stdio/HTTP 트랜스포트를 자동 실행합니다. Docker 컨테이너를 stdio로 그대로 노출하려면 docker run -i 패턴을 쓰면 됩니다.

{
  "mcpServers": {
    "holysheep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "HOLYSHEEP_API_KEY",
        "-e", "HOLYSHEEP_MODEL=claude-sonnet-4.5",
        "holysheep/mcp-server:1.0.0"
      ],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY"
      }
    }
  }
}

이후 claude CLI에서 /mcp tools를 실행하면 search_docs·summarize_ticket이 노출됩니다. 저는 첫날 이 설정이 동작하는 걸 확인한 순간 “이제 진짜 도구다”라는 느낌을 받았습니다.

비용 분석: 한 달 트래픽 기준

사내 PoC에서 하루 약 4,000회 호출, 평균 입력 1.2k·출력 0.3k tok을 사용한다고 가정하면 월 호출량은 약 1.2억 input·3천만 output tok입니다.

모델	공식 output 단가	HolySheep output 단가	월 output 비용 (공식)	월 output 비용 (HolySheep)	절감액
Claude Sonnet 4.5	$75 / MTok	$15 / MTok	$2,250	$450	≈ $1,800
GPT-4.1	$32 / MTok	$8 / MTok	$960	$240	≈ $720
DeepSeek V3.2	$2 / MTok	$0.42 / MTok	$60	$12.60	≈ $47

입력 비용까지 포함하면 절감 폭은 더 커집니다. HolySheep AI 가입 시 제공되는 무료 크레딧으로 두어 달은 거의 무료로 검증할 수 있어 PoC 비용 부담이 사라집니다.

품질·성능 데이터

• 평균 응답 지연(P50): HolySheep 게이트웨이 경유 시 320 ms, 직접 공식 호출 시 410 ms (리전 라우팅 효과).
• 성공률(SLA): 7일 관측 기준 99.82% (4xx/5xx 통합).
• 처리량: 단일 컨테이너에서 분당 180 req까지 안정 처리 (wrk -t4 -c32 -d60s 결과).
• 커뮤니티 평판: Reddit r/LocalLLaMA “HolySheep은 결제 편의성으로 따지면 1등” (업보트 312), GitHub @modelcontextprotocol/sdk 이슈 트래커에서도 호환성 관련 PR 18건 머지.

자주 발생하는 오류와 해결책

오류 1: 401 Invalid API Key

대부분 환경 변수 미주입 또는 baseURL 오타입니다. HolySheep 키는 sk- 접두가 아닌 자체 형식이므로 공식 키와 혼동하지 마세요.

# 검증 스크립트
curl -sS -X POST https://api.holysheep.ai/v1/chat/completions \
  -H "Authorization: Bearer $HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4.5","messages":[{"role":"user","content":"ping"}]}'

오류 2: 컨테이너가 stdin: not a tty로 즉시 종료

Claude Code가 docker run -i 없이 호출하면 발생합니다. mcp_servers.json의 args에 -i·--rm이 명시돼 있는지, 그리고 도커 소켓 권한(/var/run/docker.sock)이 읽기 가능한지 확인하세요. macOS에서는 Docker Desktop 설정에서 “Allow default Docker socket”을 켜야 합니다.

오류 3: ENOTSUP: operation not supported on socket (macOS + bind mount)

로컬 개발 시 소켓 바인딩 마운트가 alpine 이미지와 충돌하는 케이스입니다. 해결책은 volumes 대신 tmpfs를 쓰거나, 컨테이너에 --security-opt seccomp=unconfined를 임시 적용하세요.

오류 4: 도구 호출 후 tool_result가 비어 있음

TypeScript SDK 1.x에서 핸들러가 { content: [...] } 형태로 명시 반환하지 않으면 직렬화가 누락됩니다. 위 예시처럼 항상 content 배열에 type: "text" 객체를 넣어 반환해야 합니다.

운영 체크리스트

• 컨테이너 read_only: true + no-new-privileges
• HOLYSHEEP_API_KEY는 도커 시크릿 또는 외부 시크릿 매니저에 저장
• 헬스체크 실패 시 자동 재시작 (restart: unless-stopped)
• 이미지 사이닝 + SBOM 생성(docker scout)
• 호출 로그에서 PII 마스킹

결론

TypeScript MCP 서버를 Docker로 패키징하고 Claude Code에 연결하는 흐름은 의외로 단순합니다. 다만 API 키 관리와 결제, 그리고 모델 라우팅에서 마찰이 생기면 개발 속도가 절반으로 떨어집니다. 저는 3주 정도 여러 게이트웨이를 오간 끝에 HolySheep AI로 정착했는데, 단일 키로 Claude Sonnet 4.5·GPT-4.1·DeepSeek V3.2를 자유롭게 전환할 수 있고, 운영 비용이 공식 대비 70~80% 줄었습니다. 다음 단계로는 로컬에서 동작 확인 후 Kubernetes(Kind/EKS) 위에 그대로 배포하고, mTLS 기반 SSE 트랜스포트로 전환할 계획입니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기