Stateless MCP로 마이그레이션하기 전 코드베이스 감사하기

MCP 2026-07-28 버전은 프로토콜 레벨의 세션(sessions), 필수 초기화 핸드셰이크(initialization handshake), 그리고 Mcp-Session-Id를 제거합니다. 해당 코드 경로를 삭제하기 전에, 그것들이 숨기고 있던 애플리케이션 상태(application state)를 찾아내야 합니다. 이 튜토리얼에서는 의존성 스캐너(dependency scanner)를 구축하고, 각 일치 항목을 마이그레이션 위험도에 따라 분류하며, 그 결과를 단계별 출시 체크리스트(staged rollout checklist)로 변환하는 방법을 다룹니다.

이것은 정적 감사(static audit)이며, 배포가 호환된다는 증거는 아닙니다. 이는 발생 가능한 레거시 가정(legacy assumptions)을 찾아낼 뿐이며, 클라이언트, 서버, 게이트웨이 및 복제본(replicas) 전반에 걸친 런타임 테스트(runtime tests)가 여전히 필요합니다.

무엇이 바뀌었나요?

공식 MCP 2026-07-28 변경 로그는 운영 아키텍처(production architecture)에 영향을 미치는 몇 가지 변경 사항을 포함하고 있습니다:

Streamable HTTP에서 Mcp-Session-Id가 제거되었습니다.
initialize 및 notifications/initialized가 더 이상 요구되지 않습니다.
프로토콜 버전(Protocol version)과 클라이언트 기능(client capabilities)은 각 요청의 _meta에 포함되어 전달됩니다.
서버는 버전 및 기능 발견을 위해 server/discover를 구현합니다.
서버 주도 요청(server-initiated requests)이 다중 왕복 요청(Multi Round-Trip Requests)으로 대체됩니다.
Mcp-Method 및 Mcp-Name이 HTTP 라우팅(routing) 및 정책(policy)을 지원합니다.
캐시 가능한 목록/읽기 결과(Cacheable list/read results)에 ttlMs 및 cacheScope가 포함됩니다.
Roots, Sampling, Logging, HTTP+SSE, 선택된 includeContext 값, 그리고 동적 클라이언트 등록(Dynamic Client Registration)은 즉시 제거되는 대신 사용 중단(deprecated) 처리됩니다.

위험한 오해는 “무상태 프로토콜(stateless protocol)”이 “애플리케이션에 상태가 없다”는 것을 의미한다고 생각하는 것입니다. 워크스페이스(workspace), 지속 가능한 작업(durable task), OAuth 자격 증명(OAuth credential), 또는 대기 중인 승인(pending approval)은 여전히 여러 호출에 걸쳐 존재할 수 있습니다. 단지 의존성(dependency)이 명시적이어야 하며, 다음 요청을 받는 모든 호환 가능한 워커(worker)가 사용할 수 있어야 합니다.

1단계: 의존성 없는 스캐너 구축하기

다음 Node.js 스크립트는 저장소에서 오래된 MCP 가정들을 검색합니다. Node의 표준 라이브러리만을 사용하며, 읽기 가능한 보고서와 CI를 위한 선택적 JSON 보고서를 모두 생성합니다.

audit-mcp-2026.mjs를 생성하세요:

#!/usr/bin/env node

import { promises as fs } from "node:fs";
...

2단계: 감사 실행하기

이 스크립트는 Node.js 20 이상을 필요로 합니다. 어느 디렉토리에서든 실행할 수 있으며, 저장소(repository) 경로를 전달하면 됩니다:

node audit-mcp-2026.mjs /path/to/your/repository

CI 환경에서 사용하거나 마이그레이션 티켓(migration tickets)을 생성하려면 JSON 출력을 사용하세요:

node audit-mcp-2026.mjs /path/to/your/repository --json > mcp-audit.json

종료 코드(exit codes)는 다음과 같습니다:

코드	의미
`0`	고위험 정적 매치(high-risk static match)가 발견되지 않음
...

단순히 문자열이 문서나 호환성 테스트에 나타난다는 이유만으로 프로덕션 릴리스를 중단하지 마세요. 각 발견 사항을 검토 항목(review item)으로 취급하십시오. 이 스크립트는 확실성보다는 가시성(visibility)을 우선하도록 의도적으로 설계되었습니다.

3단계: 모든 매치 항목을 상태 소유권(state ownership)에 따라 분류하기

grep 결과가 곧 마이그레이션 계획은 아닙니다. 각 고위험 매치 항목에 대해 다음 사항을 기록하십시오:

어떤 상태(state)가 존재하는가? 워크스페이스(Workspace), 자격 증명(credential), 사용자 설정(user preference), 승인(approval), 작업(task), 커서(cursor) 또는 캐시 엔트리(cache entry).
누가 소유하는가? 사용자(User), 테넌트(tenant), 요청(request), 도구(tool), 서버(server) 또는 배포(deployment).
얼마나 오래 유지되어야 하는가? 한 번의 재시도(retry), 여러 번의 호출, 프로세스 재시작 또는 며칠 동안.
누가 이를 읽거나 변경할 수 있는가? 권한 경계(authorization boundary)는 설계 단계에서 결정되어야 합니다.
두 명의 워커(worker)가 이를 안전하게 처리할 수 있는가? 그렇지 않다면 마이그레이션이 완료되지 않은 것입니다.
재시도가 부수 효과(side effect)를 중복 발생시킬 수 있는가? MRTR을 활성화하기 전에 스테이징(staging)과 멱등성(idempotency)을 추가하십시오.

일반적인 대체 패턴은 명시적 핸들(explicit handles)과 공유 저장소(shared storage)입니다. 명시적 핸들은 도구 스키마(tool schema)에서 의존성을 가시적으로 만듭니다. 공유 저장소는 복제본(replicas)과 재시작 간에 상태에 접근할 수 있게 합니다. 장시간 실행되는 작업은 요청 워커(request worker)의 메모리가 아닌 내구성이 있는 작업 시스템(durable task system)에 속해야 합니다.

4단계: 새로운 실패 모델(failure model) 테스트하기

정적 스캐닝(Static scanning)으로는 재시도가 안전한지 또는 권한 경계가 올바른지 감지할 수 없습니다. 새로운 아키텍처를 의도적으로 실행하는 통합 테스트(integration tests)를 추가하십시오.

교차 복제본 상태 테스트 (Cross-replica state test)

워크스페이스(workspace) 또는 태스크(task)를 생성하는 요청을 보냅니다.
다음 요청이 다른 워커(worker)로 강제 전달되도록 합니다.
문서화된 핸들(handle)과 인증된 신원(authenticated identity)만 전달합니다.
두 번째 워커가 해당 작업을 계속 수행할 수 있는지 확인합니다.
첫 번째 워커를 재시작하고 이 과정을 반복합니다.

MRTR 재시도 테스트 (MRTR retry test)

파괴적이거나 비용이 발생하는 작업을 시작합니다.
부수 효과(side effect)가 발생하기 전 첫 번째 응답이 input_required인지 확인합니다.
requestState를 변조하거나 만료시킵니다. 두 경우 모두 실패 시 차단(fail closed)되어야 합니다.
동일한 비즈니스 멱등성 키(business idempotency key)를 사용하여 두 번 재시도합니다.
정확히 하나의 부수 효과만 발생하는지 확인합니다.

게이트웨이 불일치 테스트 (Gateway mismatch test)

Mcp-Name은 저위험 도구(low-risk tool)를 식별하지만, JSON-RPC 본문(body)은 제한된 도구(restricted tool)를 호출하는 요청을 보냅니다. 해당 요청은 거부되어야 하며, 불일치 사항이 보안 텔레메트리(security telemetry)에 나타나야 합니다.

캐시 격리 테스트 (Cache isolation test)

테넌트 A(tenant A)로서 비공개 도구 또는 리소스 목록을 가져온 다음, 테넌트 B(tenant B)로서 동일한 메서드를 요청합니다. 남은 TTL(Time To Live)에 관계없이 두 번째 테넌트는 절대로 A의 항목을 수신해서는 안 됩니다.

단계 5: 패키지만이 아니라 프로토콜을 카나리(Canary) 배포하십시오

안전한 롤아웃(rollout)은 현대적(modern) 동작과 레거시(legacy) 동작을 동시에 관찰할 수 있도록 유지하는 것입니다. 다음 조합들을 명시적으로 테스트하십시오:

현대적 클라이언트 + 현대적 서버    -> MCP 2026-07-28
현대적 클라이언트 + 레거시 서버    -> 지원되는 경우 테스트된 폴백(fallback)
레거시 클라이언트 + 듀얼 서버      -> 레거시 경로(legacy path)
...

프로토콜 버전, 디스커버리(discovery) 성공 여부, 폴백(fallback) 비율, 누락되거나 잘못된 헤더, 헤더/본문 불일치, MRTR 완료 및 타임아웃, 요청 상태(request-state) 검증, 중복 작업 방지, 범위별 캐시 히트(cache hits), OAuth 발행자(issuer) 실패, 레거시 HTTP+SSE 트래픽, 그리고 지원 중단된 메서드(deprecated-method) 트래픽을 추적하십시오.

호환성 경로를 폐기하는 기준은 달력상의 업그레이드 완료 시점이 아니라, 텔레메트리(telemetry) 상에서 사용되지 않음이 확인되었을 때여야 합니다.

모델 게이트웨이는 어디에 위치합니까?

MCP와 모델 API (model API)는 서로 다른 문제를 해결합니다. MCP는 에이전트(agent)를 도구(tools), 리소스(resources), 승인(approvals), 그리고 작업(tasks)에 연결합니다. 모델 API는 애플리케이션을 추론 제공자(inference providers), 자격 증명(credentials), 사용량(usage), 그리고 과금(billing)에 연결합니다.

지원 중단(deprecated) 예정인 샘플링(Sampling) 기능을 사용하지 않도록 마이그레이션할 때, 애플리케이션은 모델 제공자(model provider)를 직접 호출하거나 CometAPI와 같은 통합 모델 레이어(unified model layer)를 사용할 수 있습니다. 해당 모델 레이어가 MCP 권한 부여(authorization), 도구 계약(tool contracts), 애플리케이션 상태(application state), 또는 MRTR 처리를 대체하는 것은 아닙니다. 인터페이스를 분리하여 유지함으로써 프로토콜과 추론 제공자가 독립적으로 발전할 수 있게 합니다.

마이그레이션 체크리스트 (Migration checklist)

최종 요약 (Final takeaway)

MCP 2026-07-28은 프로토콜 계약(protocol contract)에서 세션을 제거하는 것이지, 모든 애플리케이션 요구 사항에서 세션을 제거하는 것이 아닙니다. 마이그레이션은 호환 가능한 모든 워커(worker)가 명시적 입력(explicit inputs)으로부터 다음 요청을 처리할 수 있고, 모든 재시도가 권한을 부여받으며 멱등성을 유지하며, 증거를 바탕으로 레거시 경로를 폐기할 수 있을 때 성공합니다.

Insights