TypeScript로 SDK v2를 사용하여 MCP 서버 구축하기 (2026-07-28 스펙 지원)

만약 'MCP TypeScript'를 검색한다면, 주로 2025년 코드들을 발견하게 될 것입니다. 이 코드는 단일 패키지인 @modelcontextprotocol/sdk를 사용하며, 그 메서드인 server.tool(), server.resource() 및 server.prompt()는 v2에서는 존재하지 않습니다. MCP 2026-07-28 사양을 지원하는 새로운 서버의 경우, 분리된 패키지로 제공되는 공식 SDK v2가 필요합니다.

이 글은 더 긴 가이드의 일부입니다. 저희는 Nortia Logística(DesarrolloMCP 과정의 가상 회사)의 주문을 조회하는 서버인 nortia-pedidos를 구축하고, 이를 stdio와 상태 비저장형 HTTP 스트림으로 서비스합니다. 모든 코드는 @modelcontextprotocol/server 2.3.0, zod 4.6.5 및 Node 24.12로 실행되었습니다.

알려지지 않은 사실: v2를 설치하는 것만으로는 충분하지 않다

SDK의 공식 가이드는 다음과 같이 말합니다: 'v2에서는 기본적으로 2026-07-28 바이트가 전송되지 않습니다(Nothing in v2 puts a 2026-07-28 byte on the wire by default)'. 프로토콜 버전은 설치하는 패키지가 아니라 서버를 서비스하는 **진입점(entry point)**에 의해 결정됩니다. 이것이 바로 서버가 함수 내부에서, 즉 McpServer를 반환하는 팩토리(factory) 내부에 구축되는 이유입니다. 2026-07-28을 지원하는 진입점들은 인스턴스가 아닌 팩토리를 받으며, HTTP의 경우 요청마다 이를 실행합니다.

프로젝트

mkdir nortia-pedidos && cd nortia-pedidos
npm init -y && npm pkg set type=module
npm i @modelcontextprotocol/server @modelcontextprotocol/client \
...

crearServidor() 팩토리는 도구(buscar_pedido, Zod 4로 입력 및 출력 검증), 고정 리소스, 템플릿이 있는 다른 리소스(pedidos://pedido/{pedidoId}), 그리고 프롬프트를 등록합니다. 전체 가이드에는 이 모든 것이 상세하고 결정별로 설명되어 있습니다: 왜 존재하지 않는 주문은 예외(exception)가 아니라 isError: true를 가진 결과인지, 그리고 outputSchema를 선언했더라도 출력 필드를 필터링해야 하는지 등이요.

stdio로 서비스하기

import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { dependencias } from './entorno.js';
import { crearServidor } from './servidor.js';
...

serveStdio(fábrica)는 서버가 2026-07-28을 지원하게 하는 부분이며, 기본적으로 핸드셰이크(handshake)를 사용하는 버전의 클라이언트도 처리합니다. 모든 것이 console.error로 작성된다는 점에 주목하세요: stdio에서는 MCP 유효 메시지가 아닌 것은 stdout에 쓸 수 없습니다.

Streamable HTTP로 서비스하기, 상태 비저장 (Stateless)

import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';
...

createMcpHandler는 표준 웹 핸들러를 반환하고 toNodeHandler가 이를 Express에 맞게 조정합니다. 세션이나 Mcp-Session-Id 헤더가 없습니다: 모든 POST 요청은 전송된 내용으로 해결됩니다. 팩토리(fábrica)가 각 요청마다 실행되므로, 비용이 많이 드는 부분(데이터베이스 풀, 캐시, 다른 API 클라이언트)은 모듈 수준에서 외부로 존재해야 합니다.

속임수 없이 테스트하기

MCP Inspector는 기본적으로 핸드셰이크를 사용하는 버전을 사용합니다. 만약 --protocol-era modern을 요청하거나(또는 설정 파일의 서버 입력 내 `

스페인어로 MCP를 배우고 있다면, MCP 개발 과정에서 무료 기본 레벨(14개 강의, 카드 없음)을 제공하며, 2026-07-28 사양에 맞춰 업데이트되었고 모든 코드가 테스트되었습니다.