MCP 서버 패턴
Model Context Protocol(MCP)을 사용하면 AI 어시스턴트가 서버의 도구를 호출하고, 리소스를 읽고, 프롬프트를 사용할 수 있습니다. MCP 서버를 구축하거나 유지 관리할 때 이 스킬을 사용하세요. SDK API는 지속적으로 발전하므로 Context7("MCP"에 대해 query-docs) 또는 공식 MCP 문서에서 최신 메서드 이름과 시그니처를 확인하세요.
기능을 규칙, 스킬, 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)가 표시할 수 있는 재사용 가능한 매개변수화된 프롬프트 템플릿.
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를 포함하세요. 복사-붙여넣기 오류를 방지하려면 공식 MCP 문서 또는 Context7에서 현재 @modelcontextprotocol/sdk 시그니처를 확인하세요.
입력 검증에는 Zod(또는 SDK가 선호하는 스키마 형식)를 사용하세요.
모범 사례
- 스키마 우선: 모든 도구에 대한 입력 스키마를 정의하고 매개변수와 반환 형태를 문서화하세요.
- 오류: 모델이 해석할 수 있는 구조화된 오류나 메시지를 반환하고, 원시 스택 추적은 피하세요.
- 멱등성: 가능하면 멱등성 도구를 선호하여 재시도가 안전하도록 하세요.
- 속도 및 비용: 외부 API를 호출하는 도구의 경우 속도 제한과 비용을 고려하고 도구 설명에 문서화하세요.
- 버전 관리: package.json에 SDK 버전을 고정하고 업그레이드 시 릴리스 노트를 확인하세요.
공식 SDK 및 문서
- JavaScript/TypeScript:
@modelcontextprotocol/sdk(npm). 최신 등록 및 전송 패턴은 라이브러리 이름 "MCP"로 Context7을 사용하세요. - Go: GitHub (
modelcontextprotocol/go-sdk)의 공식 Go SDK. - C#: .NET용 공식 C# SDK.