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 (query-docs에서 "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; 원격(Cursor, 클라우드)에는 Streamable HTTP 선호. 레거시 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.