MCP 서버 패턴은(는) 무엇을 하나요?
Model Context Protocol(MCP)을 사용하면 AI 어시스턴트가 서버의 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있습니다. 이 스킬은 MCP 서버를 구축하거나 유지보수할 때 사용하세요. SDK API는 계속 변경되므로, 현재 메서드 이름과 시그니처는 Context7(query-docs에서 "MCP" 검색) 또는 공식 MCP 문서를 확인하세요.
기능이 규칙, 스킬, MCP, 또는 일반 CLI/API 워크플로 중 어떤 방식으로 제공되어야 하는지에 대한 더 넓은 라우팅 결정은 docs/capability-surface-selection.md를 참조하세요.
사용 시기
다음 경우에 사용합니다: 새 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 문서 또는 Context7을 확인하세요.
stdio로 연결하기
로컬 클라이언트의 경우, stdio 전송을 생성하여 서버의 connect 메서드에 전달하세요. 정확한 API는 SDK 버전에 따라 다릅니다(예: 생성자 vs 팩토리). 현재 패턴은 공식 MCP 문서를 참조하거나 Context7에서 "MCP stdio server"를 검색하세요.
서버 로직(도구 + 리소스)을 전송과 독립적으로 유지하면 진입점에서 stdio 또는 HTTP를 연결할 수 있습니다.
원격 (Streamable HTTP)
Cursor, 클라우드 또는 기타 원격 클라이언트의 경우 Streamable HTTP(현재 사양에 따른 단일 MCP 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)(위치 인자)를 사용하고, 다른 버전은 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). 현재 등록 및 전송 패턴은 라이브러리 이름을 "MCP"로 하여 Context7을 사용하세요. - Go: GitHub의 공식 Go SDK (
modelcontextprotocol/go-sdk). - C#: .NET용 공식 C# SDK.