TypeScript로 MCP 서버 만들기: Node 개발자용 30분 가이드

핵심 요약: Python 편의 자매편입니다. 공식 TypeScript SDK로도 MCP 서버는 도구 함수 하나 등록하는 것이 전부이고, 스키마 정의에 zod를 쓴다는 점이 특징입니다. Node 생태계가 주력인 팀(프론트엔드, NestJS 등)이라면 사내 도구를 팀 언어로 만드는 것이 유지보수에 유리합니다. 필요한 것: Node 18+, 30분.

이 글에서 다루는 내용: SDK 설치, 최소 서버 코드, 등록과 테스트, Python 편과의 차이.

1단계: 프로젝트 준비

npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

2단계: 최소 서버 (server.ts)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "deploy-status", version: "1.0.0" });

server.tool(
  "get_deploy_status",
  "서비스의 현재 배포 상태와 버전을 조회한다",
  { service: z.string().describe("서비스 이름 (예: api, web)") },
  async ({ service }) => ({
    content: [{ type: "text", text: `${service}: v2.4.1, healthy` }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

구조는 Python 편과 동일합니다 — 이름·설명·파라미터 스키마·핸들러. zod의 .describe()가 AI가 읽는 파라미터 설명이 되므로 여기에 예시를 담는 것이 품질 포인트입니다.

3단계: 등록과 테스트

실행 명령은 `npx tsx server.ts`(개발) 또는 빌드 후 node. 등록은 Python 편과 같습니다 — Claude Code는 `claude mcp add deploy-status -- npx tsx /경로/server.ts`, Cursor는 mcp.json에 command/args로(Cursor 편, Claude Code 편). 등록 전 동작 확인은 MCP Inspector(`npx @modelcontextprotocol/inspector npx tsx server.ts`)가 편합니다.

Python 편과 뭐가 다른가

기능 차이는 없습니다. 선택 기준은 하나 — 팀의 주 언어. 사내 API가 Node 기반이면 타입 공유·배포 파이프라인 재사용 면에서 TypeScript가 자연스럽고, 데이터·백엔드가 Python이면 Python SDK가 맞습니다. npm 배포(npx로 설치 없이 실행)가 쉬운 것은 TS 쪽의 소소한 장점입니다.

실전 팁 (Python 편과 공통이지만 재강조)

읽기 도구부터 시작(쓰기·삭제는 검증 후), 에러 메시지는 에이전트 친화적으로(가능한 값 안내), 반환은 요약된 텍스트로(거대 JSON은 컨텍스트 낭비), 토큰은 환경 변수로. 그리고 보안 원칙은 MCP 보안 가이드 그대로입니다.

자주 묻는 질문 (FAQ)

Q. 팀에 배포할 때 npm 패키지로 만드는 게 좋나요?

A. 사내 npm 레지스트리가 있다면 좋은 방법입니다. 팀원은 설정 파일의 args에 npx 패키지명만 쓰면 되어 설치 마찰이 없습니다.

Q. HTTP(원격) 서버로도 만들 수 있나요?

A. 네, SDK가 HTTP 트랜스포트를 지원합니다. 여러 명이 쓰는 사내 도구라면 stdio(각자 실행)보다 원격 호스팅이 관리에 유리합니다. 단 인증 설계가 추가로 필요합니다.

Q. zod 스키마는 얼마나 자세히 써야 하나요?

A. AI가 파라미터를 채우는 데 필요한 만큼 — 타입 + describe(설명과 예시)면 충분합니다. enum이 있는 값은 z.enum으로 명시하면 잘못된 호출이 크게 줄어듭니다.

한눈에 보는 요약

npm 설치 → server.tool() 등록 → stdio 연결 → 클라이언트 등록. Python 편과 구조는 같고 언어만 다릅니다. 팀 언어로 만들고, 도구 설명에 공을 들이고, 읽기부터 시작 — MCP 서버 제작의 삼원칙은 언어 불문입니다.

함께 보면 좋은 글

Python으로 MCP 서버 직접 만들기
MCP 보안 가이드
MCP란 무엇인가?

참고 자료

MCP TypeScript SDK (GitHub)
MCP 공식 문서