Anthropic의 Claude Code, Claude Desktop, Cursor 또는 Cline을 실험해 본 적이 있다면 최근 어디서든 **Model Context Protocol (MCP)**를 보셨을 것입니다.
MCP는 LLM을 위한 USB-C 표준으로 빠르게 자리 잡고 있습니다. 이는 코딩 어시스턴트와 자율 에이전트가 로컬 도구를 안전하게 호출하고, 데이터베이스를 검사하며, 외부 API와 상호 작용할 수 있도록 하는 표준화된 오픈 프로토콜입니다.
공식 문서는 포괄적이지만, 모든 보일러플레이트(boilerplate) 때문에 처음부터 시작하는 것이 부담스러울 수 있습니다.
여기 공식 @modelcontextprotocol/sdk와 zod를 사용하여 깨끗한 TypeScript로 작성된 작동 가능한 최소 MCP 서버가 약 30줄 분량으로 소개됩니다.
Step 1: 종속성 초기화 및 설치
빈 폴더에서 프로젝트를 초기화하고 MCP SDK를 설치합니다:
mkdir minimal-mcp && cd minimal-mcp
bun init -y # 또는 npm init -y
bun add @modelcontextprotocol/sdk zod
Step 2: 서버 코드 작성 (server.ts)
server.ts라는 파일을 생성합니다:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
...
⚠️ 중요 로깅 규칙: 진단(diagnostics)은 항상 console.error()를 사용하여 기록하고, 절대 console.log()를 사용하지 마십시오. stdio 전송 방식에서 stdout은 MCP 서버와 AI 클라이언트 간의 JSON-RPC 메시지 프레이밍을 위해 엄격하게 예약되어 있습니다. 임의의 문자열을 stdout에 출력하면 JSON 스트림이 손상되고 클라이언트가 충돌합니다!
Step 3: Claude Desktop 또는 Claude Code에 연결하기
Claude Desktop에서 테스트하려면, 서버를 claude_desktop_config.json 파일에 추가해야 합니다:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"dev-metrics": {
...
Claude Desktop을 재시작하면, calculate_project_metrics가 사용 가능한 작은 망치 아이콘이 표시되는 것을 볼 수 있습니다. Claude에게 다음과 같이 질문해 보세요:
"이번 스프린트에서 42 스토리 포인트를 달성했고 버그는 3개인데, 우리의 스프린트 지표는 무엇인가요?"
Claude는 사용자의 로컬 TypeScript 핸들러를 자동으로 호출하고 응답을 해석할 것입니다.
다음 단계는 무엇인가요?
여기에서부터 서버를 확장하여 PostgreSQL 데이터베이스에 쿼리하거나, API 메트릭을 가져오거나, 로컬 git 명령어를 실행할 수 있습니다.
(팁: 외부 알림이나 트랜잭션 작업을 트리거하는 에이전트를 구축하고 있다면, 통제 불능의 토큰 비용을 방지하기 위해 키별 수신자 허용 목록(per-key recipient allowlists)과 루프 방지 회로 차단기(anti-loop circuit breakers)를 번들링한 SadaSend와 같은 호스팅된 설정을 확인해 보세요.)
워크플로우를 위해 맞춤형 MCP 서버를 구축하고 계신가요? 코딩 어시스턴트에게 어떤 도구를 제공하고 있나요? 아래에 여러분의 생각을 남겨주세요!