MCP TypeScript SDK 2.4.0 업그레이드: Skills와 스키마 검증 점검
MCP TypeScript SDK 2.4.0으로 서버를 올릴 때 Skills 확장 도입 범위와 스키마 컴파일, 헤더 검증, structuredContent 소비 경로의 변경을 점검한다.
2026-10-29
기존 도구의 계약부터 확인한다
my_tool:output을 $id나 $ref로 쓰는 도구는 업그레이드 후 스키마 컴파일에 실패할 수 있다. 자체 $defs의 객체를 참조하는 출력 스키마는 정상 처리되더라도, 2025 계열 클라이언트가 결과를 읽는 경로가 달라질 수 있다. 새 기능을 사용하지 않는 서버도 확인할 변경이다.
이 글의 기준은 **@modelcontextprotocol/server 2.4.0 (2026-10-23)**이다. 공식 릴리스노트에 따르면 SEP-2640의 Skills 확장이 추가됐고, 번들 Ajv의 URI 검증과 도구 헤더·출력 스키마 처리도 바뀌었다.
업그레이드 검증은 현재 서버가 사용하는 계약에서 시작한다. $id·$ref를 사용하는 스키마, x-mcp-header를 붙인 매개변수, structuredContent.result를 읽는 클라이언트를 찾아 각각 해당 변경과 대조한다. Skills 도입은 이 점검과 별도로 적용 범위를 정할 수 있다.
기존 도구에서 문제가 드러나는 지점을 비교하면, 스키마를 고칠 일과 클라이언트 소비 코드를 고칠 일이 구분된다.
$id와 $ref는 문자열 모양까지 검사한다
번들 Ajv는 fast-uri 3.1.0에서 3.1.8로 변경됐다. fast-uri 3.1.6부터는 $id나 $ref에서 첫 콜론 앞의 문자열이 유효한 URI 스킴이 아니거나, URN 네임스페이스가 유효하지 않으면 거부한다.
따라서 도구 이름에 출력 구분자를 붙여 만든 식별자가 점검 대상이다. 릴리스노트가 명시한 사례는 다음과 같다.
| 식별자 또는 참조 | 이번 URI 검증 변경의 영향 | 점검할 내용 |
|---|---|---|
my_tool:output |
거부되며 스키마 컴파일 실패 | 첫 콜론 앞 문자열의 URI 스킴 유효성 |
urn:my_tool:output |
거부되며 스키마 컴파일 실패 | URN 네임스페이스 유효성 |
my_tool_output |
이번 변경의 영향을 받지 않음 | 콜론 없는 밑줄 식별자인지 확인 |
#/$defs/... |
이번 변경의 영향을 받지 않음 | 문서 내부 참조인지 확인 |
#/definitions/... |
이번 변경의 영향을 받지 않음 | 문서 내부 참조인지 확인 |
문제는 밑줄 자체가 아니다. my_tool_output처럼 콜론이 없는 식별자는 영향을 받지 않는다. 반대로 콜론 앞 문자열이 URI 스킴으로 해석되는 형태에서는 유효성 검사가 적용된다. 기존 문자열 앞에 urn:만 붙이는 수정도 urn:my_tool:output 사례처럼 실패할 수 있다.
배포 전에는 실제 도구에 실리는 스키마를 대상으로 컴파일 여부를 확인한다. 해당 식별자가 들어간 스키마는 더 이상 컴파일되지 않고, 이를 가진 도구는 invalid-schema 오류로 실패한다. 식별자를 수정한다면 그 식별자를 사용하는 $ref도 함께 대조해야 한다.
x-mcp-header는 매개변수 타입과 연결 조건을 함께 본다
x-mcp-header가 붙은 매개변수의 타입이 number라면 수정 대상이다. 2026-07-28 사양에서는 이 조합을 허용하지 않으며, integer, string, boolean은 이번 변경의 영향을 받지 않는다.
릴리스노트가 제시한 적용 방향은 정수 타입을 사용하거나 주석을 제거하는 것이다. 실제로 정수인 매개변수에는 다음 표현을 사용할 수 있다.
z.int()
소수 값을 받아야 하는 매개변수라면 헤더 주석을 유지하려고 정수로 바꾸면 입력 계약이 달라진다. 이 경우에는 주석 제거를 검토한다.
호출 실패를 확인할 때는 서버의 헤더 검사와 클라이언트의 도구 노출 동작을 구분해야 한다. 서버는 2.3.0과 마찬가지로 tools/call에서 해당 도구의 Mcp-Param-* 헤더를 검사한다. 본문에 값이 있는데 대응하는 헤더가 없거나, 헤더와 본문의 값이 다르면 HTTP 400과 JSON-RPC 오류 -32020으로 응답한다.
여기에 2026-07-28 연결이면서 stdio가 아닌 경우에는 클라이언트가 이런 도구를 목록에서 제외하고 해당 Mcp-Param-* 헤더도 보내지 않는다. 선언된 매개변수 값을 담아 호출하면 같은 방식으로 거부된다. 서버는 도구 목록이 조회될 때마다 경고를 기록한다.
다음 흐름은 해당 연결 조건에서 도구 노출과 호출 거부가 어떻게 이어지는지 보여 준다.
따라서 기존 도구가 목록에서 사라졌다면 호출 코드부터 고치기보다 매개변수 타입과 주석을 먼저 확인한다. 호출까지 수행하는 검증에서는 도구 목록 경고와 -32020 응답을 함께 확인할 수 있다.
객체 참조형 출력은 클라이언트가 읽는 위치도 바뀐다
outputSchema의 루트가 자체 $defs 또는 definitions 안의 type: "object" 항목을 $ref로 가리키면, 이제 객체 스키마로 처리된다. 그런 참조들의 유니온도 대상이다. 릴리스노트는 Zod의 다음 표현이 만드는 형태를 예로 든다.
z.object({...}).meta({ id })
이는 형태를 설명하는 발췌다. 점검할 핵심은 생성된 스키마의 루트가 객체 정의를 참조하는지 여부다.
이 변경은 2025 계열 연결에서 응답 소비 경로에 영향을 준다. 해당 도구의 스키마와 structuredContent는 더 이상 { result: ... }로 감싸지지 않는다. 기존 클라이언트가 structuredContent.result를 읽었다면 이제 structuredContent를 읽어야 한다. 모든 프로토콜 계열에서 공개되는 스키마의 루트에는 type: "object"가 추가된다.
여기서 자체 정의를 가리키는 $ref는 앞 절의 URI 검증 문제와 구분한다. #/$defs/... 같은 내부 참조는 URI 검증 강화의 영향을 받지 않으면서도, 객체 루트 판정 변경의 대상이 될 수 있다.
검증할 때는 해당 도구의 공개 스키마와 실제 structuredContent를 함께 확인한다. 특히 2025 계열 클라이언트를 지원한다면 호출 성공 여부만으로 끝내지 말고, 클라이언트가 결과 객체를 읽는 위치까지 확인해야 한다.
Skills는 저장소, 서버 연결, 클라이언트 검증을 나눠 적용한다
Skills 확장은 새 ext/skills 하위 경로로 제공된다. 패키지 루트의 내보내기는 바뀌지 않는다. 도입할 때는 필요한 기능에 맞춰 경로를 선택한다.
| 경로 | 제공 기능 | 적용할 자리 |
|---|---|---|
@modelcontextprotocol/server/ext/skills |
SkillsExtension, SkillCatalog, 저장소 어댑터와 생성형 카탈로그 관련 API |
카탈로그 구성과 서버 제공 기능 |
@modelcontextprotocol/server/ext/skills/node |
loadSkills(folder), nodeSkillFiles(folder) |
폴더 기반 스킬 로딩 |
@modelcontextprotocol/client/ext/skills |
SkillsClient의 목록·조회·파일 및 디렉터리 읽기 |
클라이언트 소비와 검증 |
@modelcontextprotocol/core/ext/skills |
스키마, 타입, 상수와 SKILL_LIMITS |
공통 데이터 계약 확인 |
서버의 SkillsExtension.attach(server)는 skills/list, skills/get, resources/directory/read와 skill://{+path} 리소스 템플릿을 제공한다. 이 **연결 메서드는 @experimental**이므로 마이너 릴리스에서 서버에 확장을 연결하는 방식이 바뀔 수 있다. 나머지 Skills API는 안정된 API다. 도입 범위를 판단할 때 이 경계를 구분한다.
저장소는 SkillFiles 어댑터로 연결할 수 있고 memorySkillFiles도 제공된다. 생성형 카탈로그에는 SkillSource를 사용할 수 있다. SkillsExtension.load(files)가 반환하는 SkillCatalog에는 entries와 reload()가 있다.
잘못된 스킬을 처리하는 정책도 정해야 한다. 기본 동작은 경고와 함께 해당 스킬을 건너뛰며 onWarning으로 경고를 받을 수 있다. strict에서는 실패한다. 일부 스킬을 제외하고 제공해도 되는지, 잘못된 스킬이 있으면 로딩을 실패시켜야 하는지에 맞춰 선택한다.
파일 응답 형식은 MIME 타입만으로 판단하지 않는다. 바이트가 유효한 UTF-8이면 MIME 타입에 관계없이 text로 제공하고, 그 밖의 파일은 base64 blob으로 제공한다. 클라이언트 검증에도 이 구분을 반영해야 한다.
Skills 검증 실패와 프로토콜 차이를 확인한다
SkillsClient.list()는 잘못된 항목을 만나면 예외를 던진다. 유효한 항목을 계속 사용하려면 skipInvalid: true를 선택할 수 있다. 이 경우 유효한 항목은 유지하고 나머지는 invalid로 반환한다. 목록 전체 실패와 일부 항목 제외 중 어느 동작이 필요한지 클라이언트에서 결정한다.
파일 읽기는 별도의 검증을 수행한다. read(skill, path?)는 크기, 다이제스트, SKILL.md frontmatter를 확인한다. 불일치하면 SkillVerificationError가 발생한다. 다만 응답 캐시에서 가져온 사본이 검사를 통과하지 못하면 먼저 cacheMode: 'refresh'로 한 번 더 가져온다.
따라서 캐시 사본의 검증 실패와 최종 오류를 같은 사건으로 처리하지 않도록 확인한다. 다음 그림은 캐시 사본이 검사에 실패했을 때의 재조회 분기를 보여 준다.
프로토콜별 캐싱 필드도 구분한다. Skills 확장은 2025-11-25와 2026-07-28에서 동작한다. 서버는 2026-07-28에서만 ttlMs, cacheScope를 전송한다. 이 버전에서 SkillsClient는 두 필드를 필수로 요구하며 list(), get(), readDirectory()의 결과로 반환한다. 공통 결과 스키마도 안정 사양에 따라 두 필드를 필수로 둔다.
그러므로 공통 스키마의 필수 필드만 보고 모든 연결에서 같은 응답을 기대해서는 안 된다. 지원하는 프로토콜별로 서버 응답과 SkillsClient 반환값을 확인해야 한다.
서버가 사용하는 경로까지 검증 범위를 넓힌다
주요 스키마 변경을 확인했다면 서버가 사용하는 전송·리소스 기능에 따라 다음 항목도 검증에 포함한다.
| 사용하는 기능 | 2.4.0의 변경 | 확인할 결과 |
|---|---|---|
| 게이트웨이의 변경 알림 전달 | ServerEvent가 선택적 params를 받고 subscriptions/listen 라우터가 자체 구독 ID와 함께 전달 |
_meta와 확장 매개변수가 전달되는지 |
PerRequestHTTPServerTransport 연결 |
supportedProtocolVersions에 있고 SDK가 구현한 모던 리비전으로 분류되면 해당 리비전을 바인딩 |
해당 조건의 연결에서 -32022 대신 리비전이 바인딩되는지 |
| 리소스·리소스 템플릿의 제목 수정 | update({ title }) 변경이 목록 응답에 반영되고 다른 메타데이터와 개별 리소스 제목은 보존 |
수정한 제목과 보존할 메타데이터 |
createMcpHandler의 비 POST 요청 처리 |
기본값인 legacy: 'stateless'와 legacy: 'reject'에서 반환하는 모든 405에 Allow: POST 추가 |
상태 코드와 응답 헤더 |
업그레이드 완료 기준은 새 패키지가 실행되는 데서 끝나지 않는다. 기존 도구의 스키마가 컴파일되고, 헤더 주석이 매개변수 타입에 맞으며, 지원하는 클라이언트가 출력 객체를 올바른 위치에서 읽어야 한다. Skills를 제공한다면 잘못된 항목의 처리 정책과 파일 검증, 프로토콜별 캐싱 필드까지 관찰한 뒤 적용을 마무리한다.