mcp-server-patterns

name	mcp-server-patterns
description	Node/TypeScript SDK로 MCP 서버를 구축합니다. 도구, 리소스, 프롬프트, Zod 검증, stdio와 Streamable HTTP 선택을 다루며 최신 API는 Context7 또는 공식 MCP 문서를 확인합니다.
origin	ECC

MCP 서버 패턴

MCP(Model Context Protocol)는 AI 어시스턴트가 서버의 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있게 해줍니다. MCP 서버를 만들거나 유지보수할 때 이 스킬을 사용합니다. SDK API는 계속 바뀌므로 현재 메서드 이름과 시그니처는 Context7이나 공식 MCP 문서로 확인합니다.

기능이 rule, skill, MCP, 일반 CLI/API 워크플로 중 어디에 속해야 하는지 더 넓은 라우팅 판단은 docs/capability-surface-selection.md를 봅니다.

사용 시점

다음 상황에서 사용합니다.

• 새 MCP 서버를 구현할 때
• 도구나 리소스를 추가할 때
• stdio와 HTTP 중 어떤 전송을 쓸지 결정할 때
• SDK를 업그레이드할 때
• MCP 등록이나 전송 문제를 디버깅할 때

동작 방식

핵심 개념

• 도구(Tools): 모델이 호출할 수 있는 동작입니다.
  • 예: 검색, 명령 실행
  • SDK 버전에 따라 registerTool() 또는 tool()로 등록합니다.
• 리소스(Resources): 모델이 가져올 수 있는 읽기 전용 데이터입니다.
  • 예: 파일 내용, API 응답
  • registerResource() 또는 resource()로 등록합니다.
  • 핸들러는 보통 uri 인자를 받습니다.
• 프롬프트(Prompts): 클라이언트가 노출할 수 있는 재사용 가능한 매개변수화 프롬프트 템플릿입니다.
  • 예: Claude Desktop 내 재사용 프롬프트
• 전송(Transport): 로컬 클라이언트에는 stdio, 원격 클라이언트에는 Streamable HTTP를 우선합니다. 기존 HTTP/SSE는 하위 호환이 필요할 때만 사용합니다.

Node/TypeScript SDK는 버전에 따라 tool() / resource() 또는 registerTool() / registerResource()를 노출할 수 있습니다. 항상 현재 SDK 문서를 확인합니다.

stdio 연결

로컬 클라이언트에서는 stdio transport를 만들고 서버의 connect 메서드에 전달합니다. 정확한 API는 SDK 버전에 따라 다릅니다. 현재 패턴은 공식 MCP 문서나 Context7의 "MCP stdio server" 질의 결과를 참고합니다.

도구와 리소스 등 서버 로직은 transport와 분리해 두어, 엔트리포인트에서 stdio와 HTTP를 바꿔 꽂을 수 있게 유지합니다.

원격 연결(Streamable HTTP)

Cursor, 클라우드, 기타 원격 클라이언트에는 Streamable HTTP를 사용합니다. 기존 HTTP/SSE는 하위 호환성이 꼭 필요할 때만 지원합니다.

예시

설치와 서버 준비

npm install @modelcontextprotocol/sdk zod

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

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

도구와 리소스 등록은 현재 SDK 버전에 맞는 API를 사용합니다. 어떤 버전은 server.tool(name, description, schema, handler)처럼 위치 인자를 쓰고, 다른 버전은 객체 인자나 registerTool()을 씁니다. 리소스도 마찬가지입니다. 현재 시그니처는 공식 MCP 문서나 Context7에서 검증합니다.

입력 검증은 Zod 또는 SDK가 권장하는 스키마 형식을 사용합니다.

모범 사례

• 스키마 우선: 모든 도구에 입력 스키마를 정의하고 파라미터와 반환 형식을 문서화합니다.
• 에러 처리: 모델이 해석할 수 있는 구조적 에러나 메시지를 반환합니다. 원시 스택 트레이스는 피합니다.
• 멱등성: 가능하면 멱등 도구를 선호해 재시도가 안전하도록 합니다.
• 요율과 비용: 외부 API를 호출하는 도구는 rate limit와 비용을 고려하고, 이를 도구 설명에 명시합니다.
• 버전 관리: package.json에서 SDK 버전을 고정하고, 업그레이드 시 릴리스 노트를 확인합니다.

공식 SDK와 문서

• JavaScript/TypeScript: npm의 @modelcontextprotocol/sdk
• Go: GitHub의 공식 modelcontextprotocol/go-sdk
• C#: .NET용 공식 C# SDK