라이브러리로 돌아가기
MCP

MCP 튜토리얼: 2026-07-28 사양으로 제로부터 프로덕션 서버까지

글쓴이: 최종 업데이트: 2026年8月22日

핵심 요점

  • MCP SDK 월간 다운로드 9,700만+, 그러나 OAuth 사용 서버는 8.5%에 불과 — 프로토콜 채택이 보안 태세를 앞지르고 있어, 이 튜토리얼의 프로덕션 강화 단계는 모든 B2B 배포에 필수적입니다.
  • MCP SDK v2는 패키지 크기를 83% 줄이고 속도를 25% 향상 — 2026-07-28 사양은 TypeScript, Python, Go, C#용으로 재설계된 SDK와 함께 출시되었으며, 각각에 마이그레이션 가이드가 포함되어 있습니다.
  • 2026-07-28 사양은 세션과 초기화 핸드셰이크를 제거 — 각 요청은 이제 자체 포함되며, 공유 상태 없이 일반 라운드 로빈 로드 밸런서 뒤의 모든 서버 인스턴스에 도달합니다.
  • 8월 22일 MCP 로드맵은 5개 우선 영역을 정의 — 에이전트 정체성, HTTP 전송 통일, 에이전트적 메시징 프리미티브, 개선된 도구 프리미티브, SDK 개발자 경험 — 각각이 이 튜토리얼의 프로덕션 경로에서 다뤄집니다.
  • 82%의 MCP 서버가 경로 순회에 취약 (Practical DevSecOps에 따름) — 여기의 샌드박싱 및 입력 검증 단계가 데모와 배포의 차이입니다.

Model Context Protocol은 2026년에 월간 SDK 다운로드 9,700만을 돌파했으며, TypeScript와 Python SDK는 각각 10억 이상의 총 다운로드를 기록했습니다. 2026-07-28 사양은 출시 이래 가장 큰 개정을 출시했습니다: 무상태 프로토콜 코어, 일급 확장, 배포 표면을 단순화하는 세 가지 지원 중단. 3주 후인 8월 22일, MCP 유지보수자들은 새 로드맵을 발표하며 다음 사양 주기를 위한 5개 우선 영역을 정의했습니다 — 에이전트 정체성, HTTP 전송 통일, 에이전트적 메시징 프리미티브, 개선된 도구 프리미티브, SDK 개발자 경험.

이 튜토리얼은 프로덕션 경로를 다룹니다: 무상태이고 수평적으로 확장 가능하며, 정체성 인식이고 로드맵의 엔터프라이즈 우선사항에 대비된 MCP 서버 구축. 공식 퀵스타트는 Claude Desktop에 연결된 날씨 서버를 안내합니다. 이 글은 그 퀵스타트가 끝나는 곳에서 시작합니다 — 작동하는 데모와 프로덕션의 B2B 에이전트 시스템 뒤에 배치할 서버 사이의 단계입니다.

1단계 — SDK v2로 프로젝트 설정

2026-07-28 사양은 재설계된 SDK와 함께 출시되었습니다. TypeScript SDK v2는 새로운 클라이언트-서버 분할을 통해 패키지 크기를 약 83% 줄이고 성능을 25% 향상시켰습니다. Python SDK 2.0+, Go SDK, C# SDK v2.0는 모두 출시일 기준 2026-07-28 프로토콜 버전을 지원하며, 호환성 변경에 대한 상세한 마이그레이션 노트가 있습니다.

이 튜토리얼에서는 Python 3.10+와 uv를 사용합니다:

uv init mcp-server
cd mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]"

mcp[cli] 추가 패키지는 서버를 실행하고 검사하기 위한 CLI 도구를 제공합니다. SDK는 Python 타입 힌트와 docstring을 사용하여 도구 정의를 자동 생성합니다 — 함수를 정의하고, 데코레이트하면, 프로토콜 메타데이터가 시그니처에서 파생됩니다.

2단계 — 첫 도구 정의

MCP 서버는 세 가지 능력 유형을 노출합니다: tools (모델이 호출하는 함수), resources (모델이 읽는 데이터), prompts (템플릿화된 워크플로우). B2B 서버의 경우, tools가 주요 표면입니다 — 에이전트가 카탈로그를 검색하고, 견적을 생성하며, 재고를 예약하는 방법입니다.

from mcp.server import MCPServer

mcp = MCPServer("catalog-server")

@mcp.tool()
async def search_catalog(query: str, supplier_id: str | None = None) -> str:
    """Search the supplier catalog by keyword, optionally filtered by supplier.

    Args:
        query: Search keyword (SKU, product name, or category)
        supplier_id: Optional supplier filter (e.g., "s-12")
    """
    results = await catalog.search(query=query, supplier_id=supplier_id)
    return format_results(results)

@mcp.tool()
async def get_pricing(sku: str, quantity: int) -> str:
    """Get tiered pricing for a SKU at a given quantity.

    Args:
        sku: Supplier product identifier
        quantity: Order quantity (determines pricing tier)
    """
    price = await pricing_engine.get(sku=sku, quantity=quantity)
    return f"SKU {sku}: ${price.unit_price:.2f} (tier: {price.tier_name})"

각 도구의 docstring이 모델의 도구 목록에서 보게 되는 설명이 됩니다. 타입 힌트가 입력 스키마가 됩니다. 이것이 MCP Module Code Standard 패턴입니다: 각 도구는 타입화된 스키마, 명확한 docstring, 단일 책임을 가집니다.

STDIO 로깅 함정: STDIO 기반 서버의 경우, stdout에 절대 쓰지 마세요 — JSON-RPC 메시지 스트림을 손상시킵니다. stderr에 쓰는 표준 logging 모듈을 사용하세요:

import logging
logger = logging.getLogger(__name__)
logger.info("Catalog search: query=%s", query)  # stderr, safe

3단계 — 전송: STDIO vs Streamable HTTP

2026-07-28 사양은 원격 MCP 서버를 "다른 HTTP 워크로드와 다르지 않게" 만듭니다 (사양 체인지로그). 로드맵의 두 번째 우선 영역 — HTTP 네이티브 전송 통일 — 은 이것을 stdio 상에서 Streamable HTTP를 말하는 로컬 서버로 확장하여, 하나의 전송 모델로 통일합니다.

로컬 개발과 데스크톱 클라이언트의 경우, STDIO가 기본값입니다:

if __name__ == "__main__":
    mcp.run(transport="stdio")

프로덕션 B2B 배포 — 에이전트가 데스크톱 앱이 아닌 클라우드 워크로드로 실행되는 곳 — 에서는 Streamable HTTP가 프로덕션 전송입니다. 서버는 로드 밸런서 뒤에서 실행되고, Mcp-Method와 Mcp-Name 헤더가 있는 HTTP POST 요청을 수락하며, HTTP 상에서 JSON-RPC로 응답합니다:

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8080)

헤더 기반 라우팅 기능은 게이트웨이, 속도 제한기 또는 WAF가 Mcp-Method와 Mcp-Name 헤더로 직접 라우팅하고 계량할 수 있음을 의미합니다 — 라우팅 결정을 위해 JSON 본문 파싱이 필요 없습니다. 이것이 무상태 프로토콜이 설계된 배포 형태입니다: 라운드 로빈 로드 밸런서 뒤의 무상태 서버 인스턴스 풀, 공유 세션 계층 없이.

4단계 — 상태 저장 워크플로우를 위한 명시적 핸들

무상태는 상태가 사라진다는 의미가 아닙니다. 2026-07-28 사양은 숨겨진 세션 상태를 명시적 핸들 패턴으로 대체합니다: 도구가 핸들(order_id, quote_id, basket_id)을 생성하고, 모델이 후속 호출에서 일반 인수로 다시 전달합니다. 이것은 MCP 2026-07-28: B2B 에이전트 배포에서 무상태 프로토콜의 의미에서 자세히 다뤄집니다.

5개의 도구 호출에 걸친 견적 워크플로우 — 요청 생성, 카탈로그 검색, 견적 생성, 가용성 예약, 가격 등급 적용 — 에서 핸들이 각 호출을 통해 스레딩됩니다:

@mcp.tool()
async def create_request(buyer_id: str, line_items: list[dict]) -> str:
    """Create an RFQ request and return a request_id handle."""
    request = await rfq_engine.create(buyer_id, line_items)
    return f"request_id={request.id}"

@mcp.tool()
async def generate_quote(request_id: str, supplier_ids: list[str]) -> str:
    """Generate a quote from specified suppliers. Returns quote_id."""
    quote = await rfq_engine.quote(request_id, supplier_ids)
    return f"quote_id={quote.id}"

각 호출이 필요한 핸들을 운반합니다. 호출 사이에 아무것도 기억하는 서버가 없습니다. 로드 밸런서가 호출 3과 다른 인스턴스로 호출 4를 라우팅해도 여전히 작동합니다 — 핸들이 요청에 있습니다. 감사 팀이 일주일 후에 이 워크플로우를 재구성해야 하는 경우, 요청 인수의 핸들이 전체 스토리를 전달합니다.

5단계 — 에이전트 정체성: 엔터프라이즈 격차

로드맵의 세 번째 우선 영역 — 에이전트 정체성과 엔터프라이즈급 보안 — 은 B2B 배포에 가장 중요합니다. 로드맵은 명시적입니다: MCP 인증은 오늘 "브라우저에서 접근을 승인하는 사람"을 중심으로 구축되어 있지만, "점점 더 많은 호출자가 자체 정체성을 가진 클라우드 워크로드로 실행되는 에이전트이며, 부재 중인 사용자를 대신하여 행동하거나, 하위 에이전트에 더 좁은 권한을 위임하고 있습니다."

로드맵이 정의하는 전진 경로:

  1. DPoP (RFC 9449) — Demonstrating Proof of Possession은 OAuth 토큰을 클라이언트가 보유한 키에 바인딩합니다. 도난당한 토큰만으로는 다른 프로세스에서 요청을 재생할 수 없습니다. DPoP는 에이전트가 무엇을 하도록 허용할지 결정하지 않습니다; 의도된 보유자 외부에서 자격 증명을 재사용하기 어렵게 만듭니다.
  2. Workload Identity Federation — IETF WIMSE 워킹 그룹은 다중 시스템 환경에서 워크로드 정체성을 위한 아키텍처를 개발 중입니다. 에이전트는 워크로드이므로 워크로드의 정체성을 얻습니다: SPIFFE ID로 명명, 단기 자격 증명으로 인증, 공유 API 키가 아님.
  3. Enterprise-Managed Authorization (EMA) — EMA 확장은 접근 결정을 조직의 정체성 제공자로 이동합니다. MCP 클라이언트는 사용자 정체성 어설션을 Identity Assertion JWT Authorization Grant (ID-JAG)로 교환한 다음, 해당 그랜트를 서버별 접근 토큰으로 교환합니다. 이는 중앙 할당 및 취소를 지원합니다.

이 튜토리얼의 프로덕션 서버를 위한 최소 기준선:

  • 공유 API 키 없음. 각 에이전트는 단기간, 오디언스 바인딩 토큰을 얻습니다.
  • DPoP와 함께 OAuth. Practical DevSecOps MCP Security Statistics 2026 보고서는 단 8.5%의 MCP 서버만 OAuth를 사용하는 것을 발견했습니다 — 나머지 91.5%는 API 키 또는 인증 없음에 의존합니다.
  • 모든 신뢰 경계에서 토큰 교환. CoSAI 토큰 교환 표준 (8월 18일 발행)은 에이전트적 워크플로우를 위한 기초적 제어로 토큰 교환을 확립합니다. 모든 register_tools() 진입점은 영구적 자격 증명이 아닌 작업 범위 토큰을 수락해야 합니다.

프로덕션 전에 이러한 표준을 검증하는 12개 제어에 대해서는 MCP Security Hardening Checklist를, 모듈 수준의 방어 태세에 대해서는 MCP Module Code Standard를 참조하세요.

6단계 — 점진적 도구 발견: 100개 도구 문제 해결

로드맵의 네 번째 우선 영역 — 개선된 프리미티브 — 는 구체적인 프로덕션 문제를 다룹니다: "100개의 도구를 가진 서버에 연결한다는 것은 사용자가 단 하나의 질문도 하기 전에 모델이 전체 표면에 대해 비용을 지불한다는 의미이며, 도구 선택은 목록이 길어질수록 악화되는 경향이 있습니다."

로드맵의 답은 점진적 발견입니다: 서버는 작은 진입점을 제공하고 대화가 좁아짐에 따라 카탈로그의 더 많은 부분을 공개합니다. 연결 시 100개의 도구 스키마를 모델의 컨텍스트 창에 쏟아붓는 대신, 서버는 소수의 최상위 도구를 노출하고 에이전트가 수행 중인 작업에 따라 표면을 동적으로 확장합니다.

2026-07-28 사양은 이미 빌딩 블록을 제공합니다:

  • server/discover RPC — 클라이언트는 세션 핸드셰이크 없이, 다른 작업을 하기 전에 서버의 능력을 학습할 수 있습니다.
  • ttlMs와 cacheScope가 있는 tools/list — 목록 응답은 캐시 힌트를 운반하므로, 클라이언트는 도구 카탈로그를 캐시하고 각 연결마다 재페치를 피합니다.
  • 각 요청의 _meta — 프로토콜 버전, 클라이언트 정보, 능력이 협상된 세션이 아닌 요청별로 이동합니다.

50+ 도구를 가진 서버의 경우, 점진적 발견 패턴은 다음과 같습니다:

@mcp.tool()
async def discover_tools(category: str) -> str:
    """Discover available tools in a category. Start here for a guided tour.

    Args:
        category: Tool category — 'catalog', 'pricing', 'inventory', 'orders'
    """
    available = tool_registry.by_category(category)
    return format_tool_list(available)

에이전트는 먼저 discover_tools("catalog")를 호출하고, 5-8개의 집중된 도구 세트를 얻으며, 워크플로우가 요구할 때만 다른 카테고리로 확장합니다. 이것은 컨텍스트 창을 가볍게 유지하고 도구 선택을 정확하게 만듭니다 — MCP Module Code Standard의 단일 책임 도구 설계 이면의 동일한 원칙입니다.

7단계 — 배포: 무상태, 수평, 로드 밸런서 뒤

2026-07-28 사양이 설계된 배포 형태:

                    ┌──────────────────┐
                    │  Load Balancer   │
                    │  (round-robin)   │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────┴────┐ ┌───────┴────┐ ┌───────┴────┐
     │ MCP Server  │ │ MCP Server  │ │ MCP Server  │
     │  Instance 1 │ │  Instance 2 │ │  Instance 3 │
     │ (stateless) │ │ (stateless) │ │ (stateless) │
     └─────────────┘ └─────────────┘ └─────────────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────┴─────────┐
                    │  Upstream Systems │
                    │  (NetSuite, etc.)  │
                    └──────────────────┘

공유 세션 저장소 없음. 스티키 세션 로드 밸런서 없음. 세션 재생 인프라 없음. 각 요청은 필요한 것 — 프로토콜 버전, 클라이언트 정보, 능력, 핸들 — 을 요청 본문과 헤더에 운반하며, 서버 측 상태에는 없습니다.

프로덕션 강화를 위해:

  • 각 서버 인스턴스 샌드박싱. MCP Project Sandboxing Baseline (8월 16일 발행)은 생성된 프로세스에 대한 OS 수준 샌드박싱을 요구합니다. Landlock (Linux), Seatbelt (macOS), 또는 Windows ACL을 사용하여 파일 시스템과 네트워크 접근을 제한하세요. 82% 경로 순회 취약성 비율 (Practical DevSecOps에 따름)은 입력 검증만으로는 불충분하다는 증거입니다.
  • 각 도구 속도 제한. MCP Module Code Standard는 도구별 속도 제한을 요구합니다. MCP Ruby SDK DoS 취약성 (8월 16일 공개)은 리소스 고갈 공격이 실제 공격 표면임을 확인합니다.
  • MCP 로깅 채널이 아닌 OpenTelemetry에 로깅. 2026-07-28 사양은 stderr와 OpenTelemetry를 선호하여 로깅 기능을 지원 중단했습니다. MCP 서버 로그는 사용자 정의 전송 없이 기존 관측가능성 파이프라인 (Datadog, CloudWatch, Honeycomb)과 통합됩니다.
  • WAF와 속도 제한을 위한 헤더 기반 라우팅 사용. Mcp-Method와 Mcp-Name 헤더를 통해 게이트웨이가 JSON 본문을 파싱하지 않고 라우팅하고 인증할 수 있습니다.

로드맵 전망: 5개 우선 영역

8월 22일 로드맵은 다음 사양 주기의 방향을 정의합니다. 이 튜토리얼은 프로덕션 준비 부분을 다루며, 로드맵은 다음에 올 것을 명시합니다:

우선 영역 상태 튜토리얼 커버리지
에이전트 정체성과 엔터프라이즈 보안 진행 중 (DPoP, WIMSE, EMA) 5단계 — 기준선 확립; 전체 구현은 사양 확정 대기
HTTP 네이티브 전송 통일 출시됨 (원격), 진행 중 (로컬) 3단계 — 원격 HTTP가 프로덕션; 로컬 Streamable HTTP over stdio가 로드맵 목표
에이전트적 메시징 프리미티브 확장 출시 중 (Tasks, 구독) 미커버 — 서버 시작 이벤트 (webhooks, channels)가 다음 프론티어
개선된 프리미티브 (점진적 발견) 설계 단계 6단계 — 패턴은 discover_tools로 오늘 구현 가능; 사양 수준 지원이 도래 중
개선된 SDK 개발자 경험 출시됨 (SDK v2, 적합성 테스트) 1단계 — SDK v2가 현재 프로덕션 기준선

로드맵은 방향이지 호환성 약속이 아닙니다. 7월 28일 사양은 이미 무상태 HTTP 코어와 Tasks 확장을 제공했습니다. 푸시 이벤트, 통합 발견, 위임, 크로스 SDK 적합성은 여전히 구현 작업이 필요합니다. B2B 배포의 경우, 에이전트 정체성 우선사항이 주시해야 할 것입니다 — MCP 보안 문서와 거버넌스 체크리스트가 지적해 온 정확한 격차 (API 키와 장기 토큰)를 다룹니다.

튜토리얼의 프로덕션 경로는 5단계 프로덕션 체크리스트를 다룹니다:

MCP 서버: 제로부터 프로덕션까지 SDK 설정부터 무상태 배포까지 5단계 — 엔터프라이즈 경로 1 프로젝트 설정 & SDK v2 83% 더 작은 패키지, 25% 더 빠름 uv init + mcp[cli] — Python 3.10+, TypeScript, Go, C# SDKs 모두 2026-07-28 지원 출처: blog.modelcontextprotocol.io/posts/2026-07-28 2 도구 & 전송 정의 타입화된 스키마, docstring, STDIO 또는 Streamable HTTP @mcp.tool() with type hints — 게이트웨이 라우팅용 Mcp-Method/Mcp-Name 헤더 출처: modelcontextprotocol.io/specification/2026-07-28 3 상태 저장 워크플로우를 위한 명시적 핸들 request_id → quote_id → hold_id — 무상태 프로토콜, 상태 저장 워크플로우 세션 핸드셰이크 없음 — 각 요청이 자체 포함, 감사 가능, 캐시 가능 출처: SEP-2575, SEP-2567 (무상태 MCP) 4 에이전트 정체성 & 엔터프라이즈 보안 DPoP (RFC 9449), Workload Identity Federation, EMA 확장 OAuth 사용 단 8.5% — 82% 경로 순회 취약 — 샌드박스 필수 출처: Practical DevSecOps MCP Security Statistics 2026 5 프로덕션 배포 라운드 로빈 LB 뒤의 무상태 풀 — OpenTelemetry, 샌드박싱, 속도 제한 스티키 세션 없음, 공유 상태 계층 없음 — 모든 인스턴스가 모든 요청 처리 출처: MCP Project Sandboxing Baseline (8월 16일), CoSAI token-exchange (8월 18일) 로드맵 전망 — 5개 우선 영역 (2026년 8월 22일) 에이전트 정체성 DPoP, WIMSE, EMA HTTP 전송 Streamable HTTP 통일 메시징 프리미티브 Tasks, webhooks, channels 점진적 발견 100 도구 문제 해결 SDK 경험 적합성 테스트 방향성이지 호환성 약속이 아님 — 기반은 7월 28일 출시, 확장과 정체성 작업 진행 중 출처: blog.modelcontextprotocol.io/posts/mcp-roadmap (2026년 8월 22일) SDK 설정부터 무상태 프로덕션까지 5단계 — ideabosque.com/library

관련 독서

빌드 비네트

NetSuite를 운영하는 중견 유통업체가 영업팀에 CRM을 떠나지 않고도 공급업체 카탈로그를 검색하고, 견적을 생성하며, 재고 수준을 확인할 수 있는 AI 어시스턴트를 제공하기를 원했습니다. 첫 번째 시도는 모든 에이전트 인스턴스 간에 공유되는 단일 API 키를 사용했습니다 — OAuth를 건너뛰는 91.5%의 MCP 서버. 공급업체 가격표 업데이트가 로그 파일에서 키를 노출시켰고, 팀은 15개 서비스에서 자격 증명을 교체하는 데 이틀을 보냈습니다.

재구축은 이 튜토리얼의 프로덕션 경로를 따랐습니다: 타입화된 도구 스키마가 있는 SDK v2, 라운드 로빈 로드 밸런서 뒤의 Streamable HTTP 전송, 15분 만료의 DPoP 바인딩 OAuth 토큰, 5단계 견적 워크플로우의 명시적 핸들, 각 서버 인스턴스의 OS 수준 샌드박싱. 에이전트는 코드 표준을 따르는 MCP 모듈을 통해 NetSuite에 연결되며, 점진적 발견은 먼저 8개의 카탈로그 도구를 노출하고 워크플로우가 요구할 때만 가격 및 재고로 확장합니다. 6개의 서버 인스턴스가 로드 밸런서 뒤에서 무상태로 실행됩니다. 공유 세션 저장소 없음. 스티키 세션 없음. 각 요청이 자체 핸들, 토큰, 프로토콜 버전을 운반합니다.

범위 정의 빌드 요청

1주 디스커버리. 시스템 인벤토리, 워크플로우 맵, 고정 범위를 얻습니다 — 당사와 빌드하든 아니든.

귀하의 시스템을 위해 이것을 구축하고 싶으신가요?

여기의 각 문서는 실제 프로덕션 작업에서 나왔습니다. 대상 시스템과 워크플로가 있다면, 1주 내에 빌드를 범위 정의할 수 있습니다.

범위 정의 빌드 요청

1주 발견. 시스템 인벤토리, 워크플로 맵, 고정 범위를 받습니다 — 우리와 빌드할지 여부와 관계없이.