mcp-server-patterns

---
name: mcp-server-patterns
description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
origin: ECC
---

# MCP 서버 패턴

Model Context Protocol (MCP)은 AI 어시스턴트가 서버에서 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있게 합니다. MCP 서버를 구축하거나 유지보수할 때 이 스킬을 사용하세요. SDK API는 진화합니다; 현재 메서드 이름과 시그니처는 Context7 ("MCP" 검색) 또는 공식 MCP 문서를 확인하세요.

## 사용 시점

다음과 같을 때 사용: 새 MCP 서버 구현, 도구나 리소스 추가, stdio vs HTTP 선택, SDK 업그레이드, MCP 등록 및 트랜스포트 문제 디버깅.

## 작동 방식

### 핵심 개념

- **Tools**: 모델이 호출할 수 있는 액션 (예: 검색, 명령 실행). SDK 버전에 따라 `registerTool()` 또는 `tool()`로 등록합니다.
- **Resources**: 모델이 가져올 수 있는 읽기 전용 데이터 (예: 파일 내용, API 응답). `registerResource()` 또는 `resource()`로 등록합니다. 핸들러는 일반적으로 `uri` 인자를 받습니다.
- **Prompts**: 클라이언트가 표시할 수 있는 재사용 가능한 파라미터화된 프롬프트 템플릿 (예: Claude Desktop). `registerPrompt()` 또는 동등한 것으로 등록합니다.
- **Transport**: 로컬 클라이언트 (예: Claude Desktop)에는 stdio; Streamable HTTP는 원격 (Cursor, 클라우드)에 선호됩니다. 레거시 HTTP/SSE는 하위 호환성을 위한 것입니다.

Node/TypeScript SDK는 `tool()` / `resource()` 또는 `registerTool()` / `registerResource()`를 노출할 수 있습니다; 공식 SDK는 시간이 지남에 따라 변경되었습니다. 항상 현재 [MCP 문서](https://modelcontextprotocol.io) 또는 Context7에서 확인하세요.

### stdio로 연결

로컬 클라이언트의 경우, stdio 트랜스포트를 생성하고 서버의 connect 메서드에 전달합니다. 정확한 API는 SDK 버전에 따라 다릅니다 (예: 생성자 vs 팩토리). 현재 패턴은 공식 MCP 문서를 확인하거나 Context7에서 "MCP stdio server"를 검색하세요.

서버 로직(도구 + 리소스)을 트랜스포트와 독립적으로 유지하여 진입점에서 stdio 또는 HTTP를 연결할 수 있게 하세요.

### 원격 (Streamable HTTP)

Cursor, 클라우드 또는 기타 원격 클라이언트의 경우, **Streamable HTTP** (현재 사양에 따라 단일 MCP HTTP 엔드포인트)를 사용하세요. 하위 호환성이 필요한 경우에만 레거시 HTTP/SSE를 지원하세요.

## 예시

### 설치 및 서버 설정

```bash
npm install @modelcontextprotocol/sdk zod
```

```typescript
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)` (위치 인자)를 사용하고, 다른 버전은 `server.tool({ name, description, inputSchema }, handler)` 또는 `registerTool()`을 사용합니다. 리소스도 마찬가지입니다 - API가 제공할 때 핸들러에 `uri`를 포함하세요. 복사-붙여넣기 오류를 피하기 위해 현재 `@modelcontextprotocol/sdk` 시그니처는 공식 MCP 문서 또는 Context7을 확인하세요.

입력 검증에 **Zod** (또는 SDK가 선호하는 스키마 형식)를 사용하세요.

## 모범 사례

- **스키마 우선**: 모든 도구에 입력 스키마를 정의; 매개변수와 반환 형태를 문서화.
- **에러**: 모델이 해석할 수 있는 구조화된 에러나 메시지를 반환; 원시 스택 트레이스 피하기.
- **멱등성**: 가능하면 멱등 도구를 선호하여 재시도가 안전하도록.
- **속도와 비용**: 외부 API를 호출하는 도구의 경우, 속도 제한과 비용을 고려; 도구 설명에 문서화.
- **버전 관리**: package.json에 SDK 버전 고정; 업그레이드 시 릴리스 노트 확인.

## 공식 SDK 및 문서

- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). 현재 등록 및 트랜스포트 패턴은 Context7에서 라이브러리 이름 "MCP"로 검색.
- **Go**: GitHub의 공식 Go SDK (`modelcontextprotocol/go-sdk`).
- **C#**: .NET용 공식 C# SDK.