로컬과 프로덕션 사이의 세 가지 격차

로컬 MCP Server는 단 하나의 명령만 필요합니다: python server.py.
엔터프라이즈 프로덕션(Production) 환경에서는 세 가지 필수적인 문제가 추가됩니다:

1. 인증 (Authentication): stdio 모드에는 인증이 없습니다 — 어떤 프로세스든 연결할 수 있습니다. 프로덕션에서는 명시적인 신원 확인이 필요합니다.
2. 프로세스 감독 (Process supervision): 종료된 Python 프로세스는 스스로 재시작되지 않으며 알림도 생성하지 않습니다. 프로덕션에는 감시자(Guardian)와 상태 확인(Health checks)이 필요합니다.
3. 원활한 업그레이드 (Smooth upgrades): 여러 Agent 세션이 동시에 동일한 Server에 연결될 수 있습니다. 업그레이드 시 이러한 연결을 끊어서는 안 됩니다.

인증 옵션

API Key (내부 서비스에 권장)

가장 간단한 옵션으로, 기업 네트워크 내부의 서비스 간 호출(Service-to-service calls)에 적합합니다:

import os
from mcp.server import Server

...

HTTP 전송 (HTTP transport) (non-stdio)의 경우, 미들웨어(Middleware)에서 검증합니다:

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request

...

OAuth 2.0 (조직 간 또는 사용자 수준 권한)

서로 다른 사용자가 데이터의 서로 다른 하위 집합에 접근해야 할 때(사용자마다 다른 Jira 프로젝트 등) 사용합니다:

MCP 스펙(2025)은 OAuth 통합 인터페이스를 정의합니다. 호스트(Host, Claude Desktop / Claude Code)는 사용자 로그인 중에 OAuth 토큰을 획득하고, 각 MCP 연결 시 이를 Server에 전달합니다.

mTLS (고보안 내부 통신)

엄격한 데이터 보안 요구 사항이 있는 금융, 의료 또는 정부 시나리오를 위한 상호 인증서 검증(Mutual certificate verification) 방식입니다:

import ssl

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
...

인증 선택 가이드:

내부 서비스 호출 (동일 네트워크)           → API Key + 네트워크 격리
조직 간 또는 사용자 수준 권한 필요         → OAuth 2.0
고보안 (금융, 의료, 정부)                 → mTLS

Docker 배포

최소 Dockerfile

FROM python:3.12-slim

WORKDIR /app
...

프로덕션 Docker Compose

# docker-compose.prod.yml
version: "3.9"

...

주요 설정 포인트:

• restart: unless-stopped: 충돌 시 재시작하며, 수동으로 중지했을 때만 중지 상태를 유지함
• internal: true: 외부 연결이 없는 Docker 네트워크 — 동일한 네트워크 상의 컨테이너만 Server에 접근 가능
• 리소스 제한 (Resource limits): 버그가 있는 Server가 호스트 머신의 리소스를 모두 점유하는 것을 방지
• 로그 로테이션 (Log rotation): 로그 파일이 무제한으로 커지는 것을 방지

프로세스 감독 (Process Supervision, non-Docker)

# /etc/systemd/system/jira-mcp.service
[Unit]
Description=Jira MCP Server
...

systemctl enable jira-mcp
systemctl start jira-mcp
journalctl -u jira-mcp -f    # 실시간 로그 스트림

다중 버전 공존 및 원활한 업그레이드 (Multi-Version Coexistence and Smooth Upgrades)

문제 상황

여러 Agent 세션이 MCP Server v1.2에 연결되어 있습니다. 기존 연결을 끊지 않고 새로운 도구(tool)가 추가된 v1.3을 출시해야 합니다.

전략: 병렬 버전 + 트래픽 전환 (Parallel Versions + Traffic Switch)

# docker-compose.prod.yml (병렬 버전)
services:
  jira-mcp-stable:
...

Host 설정을 먼저 카나리(canary) 버전으로 지정합니다. 모니터링을 수행한 후, stable 버전을 전환합니다:

{
  "mcpServers": {
    "jira": {
...

버전 번호 규칙 (Version Number Rules)

MAJOR.MINOR.PATCH

MAJOR: 파괴적 변경 (breaking changes)
...

Server 코드에 버전을 선언합니다:

server = Server(
    "jira-tools",
    version="1.3.0"   # initialize 응답 시 Client에 반환됨
...

지원 중단 프로세스 (Deprecation Process)

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "search_jira":   # 이전 도구 이름
...

이전 도구 이름을 90일 동안 유지하고 사용량을 로그로 기록한 뒤, MAJOR 버전에서 제거합니다.

보안 설계 체크리스트 (Security Design Checklist)

인증 및 인가 (Authentication and authorization)

• 자격 증명(Credentials)은 환경 변수를 통해 주입 — 코드나 이미지에 절대 하드코딩하지 말 것
• 내부 서비스는 API Key를 사용하고, 조직 간(cross-org) 또는 사용자 수준의 권한은 OAuth를 사용
• HTTP 전송(transport) 검증은 도구 핸들러(tool handlers)가 아닌 미들웨어 계층에서 수행

네트워크 격리 (Network isolation)

• Docker 네트워크를 internal: true로 설정 — 서버에 직접적인 외부 출력 액세스(outbound access)가 없음
• 필요한 포트만 노출 (stdio 모드는 개방된 포트가 필요 없음)
• 여러 서버를 별도의 Docker 네트워크로 격리

도구 보안 (Tool security)

• 도구 입력값에 대한 타입 검증(type validation) 및 범위 확인(range checks) 수행 (Article 04)
• 고위험 도구(쓰기 작업, 외부 API 호출)에 대한 감사 로그(audit logs) 기록
• 서버의 파일 시스템 액세스를 필요한 디렉터리로 제한

운영 (Operations)

• 로그는 stderr로 전송하며, 구조화된 형식(JSON)을 사용하고 로테이션(rotation)을 구성함
• restart: unless-stopped 또는 systemd 감독(supervision)을 통해 가용성 보장
• 리소스 제한(CPU/memory)을 통해 서버의 비정상적인 동작이 호스트에 영향을 미치는 것을 방지

요약 (Summary)

1. 시나리오에 맞는 인증 방식 선택: 내부 서비스에는 API Key, 조직 간 또는 사용자 수준의 액세스에는 OAuth, 규제 산업에는 mTLS를 사용하세요 — 과도한 엔지니어링(over-engineer)은 피해야 합니다.
2. Docker 3종 세트: restart: unless-stopped (장애 복구) + internal: true 네트워크 (격리) + 리소스 제한 (안정성)
3. 원활한 업그레이드를 위한 병렬 버전 운영: MINOR 버전은 하위 호환성(backward-compatible)이 유지되므로 직접 교체할 수 있습니다. MAJOR 버전은 구버전과 신버전을 병렬로 실행하여, 에이전트(Agent) 코드가 자체적인 속도에 맞춰 마이그레이션할 수 있도록 합니다.

참고 문헌 (References)

• MCP Transport Protocol Specification
• Docker Security Best Practices

실제 엔터프라이즈급 워크플로우에서 검증된 AI 에이전트 및 스킬의 큐레이션 마켓플레이스인 PrimeSkills를 확인해 보세요. 불필요한 내용은 빼고, 실제로 작동하는 것들만 제공합니다.

제 홈페이지에서 더 유용한 지식과 흥미로운 제품들을 찾아보세요.