[MCP 서버 직접 만들기 TypeScript 커스텀 도구 구축] 실전 튜토리얼 — 처음부터 배포까지

 

안녕하세요!

재아군의 관찰인생입니다.

 

최근 AI 개발 생태계에서 가장 뜨거운 키워드 중 하나가 바로 MCP(Model Context Protocol)입니다.

Claude, GPT 등 대형 언어 모델이 외부 도구와 데이터를 연결하는 표준 프로토콜로 자리잡으면서, 이제 개발자가 직접 MCP 서버를 만들어 자신만의 커스텀 도구를 구축하는 시대가 열렸습니다.

오늘은 MCP 서버 직접 만들기 TypeScript 커스텀 도구 구축의 모든 것을 처음부터 배포까지 실전 튜토리얼 형태로 다뤄보겠습니다.

 

 

---

 

1. MCP 서버 직접 만들기 TypeScript 커스텀 도구 구축이란 무엇인가?

 

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 프로토콜로, AI 모델이 외부 시스템의 도구(Tool), 리소스(Resource), 프롬프트(Prompt)에 접근할 수 있도록 표준화된 통신 규격을 제공합니다.

쉽게 말해, AI 모델과 외부 세계를 잇는 USB-C 포트와 같은 역할을 합니다.

 

MCP 서버를 TypeScript로 직접 구축한다는 것은, 이 프로토콜 규격에 맞춰 자신만의 도구를 정의하고, AI 클라이언트(Claude Desktop, VS Code 등)가 해당 도구를 호출할 수 있도록 서버를 개발하는 것을 의미합니다.

 

등장 배경

 

기존 AI 도구 통합 방식에는 여러 문제가 있었습니다.

 

1. 파편화된 통합 방식 — 각 AI 플랫폼마다 Function Calling, Plugin, Action 등 서로 다른 API 규격을 사용했습니다. OpenAI의 Function Calling, ChatGPT Plugin, GPT Actions가 모두 미묘하게 다른 스펙을 요구하면서 개발자는 동일한 기능을 여러 번 구현해야 했습니다.
2. 양방향 통신의 부재 — 기존 REST API 기반 통합은 단방향 요청-응답 패턴에 갇혀 있었습니다. AI가 작업 중간에 추가 정보를 요청하거나, 실시간으로 진행 상황을 스트리밍하는 것이 구조적으로 어려웠습니다.
3. 보안 모델의 미흡 — API 키를 환경 변수로 전달하는 단순한 인증 방식만 존재했고, 도구별 세분화된 권한 제어(어떤 도구는 읽기만 허용, 어떤 도구는 쓰기까지 허용)가 불가능했습니다.
4. 컨텍스트 공유의 한계 — AI 모델이 파일 시스템, 데이터베이스, 외부 API의 데이터를 통합적으로 활용하려면 각각에 대해 별도의 연결 로직을 작성해야 했고, 도구 간 컨텍스트를 공유하는 표준이 없었습니다.

 

MCP는 이 네 가지 문제를 단일 프로토콜로 해결합니다.

JSON-RPC 2.0 기반의 표준 메시지 형식, stdio/SSE/Streamable HTTP 세 가지 전송 방식, 그리고 도구·리소스·프롬프트라는 세 가지 프리미티브를 통해 일관된 통합 경험을 제공합니다.

 

 

---

 

2. 핵심 특징 & 기능 분석

 

MCP 서버의 핵심 특징 5가지를 상세히 살펴보겠습니다.

 

2-1. Zod 기반 스키마 정의로 타입 안전성 확보

 

MCP TypeScript SDK는 도구의 입력 파라미터를 Zod 스키마로 정의합니다.

이를 통해 런타임 유효성 검사와 컴파일 타임 타입 추론이 동시에 이뤄집니다.

AI 모델이 잘못된 형식의 인자를 전달하면 서버 단에서 즉시 에러를 반환하므로, 예측 불가능한 동작을 사전에 차단할 수 있습니다.

 

2-2. 세 가지 프리미티브 — Tool, Resource, Prompt

 

• Tool: AI 모델이 호출할 수 있는 함수입니다. 데이터베이스 쿼리, API 호출, 파일 조작 등 부수 효과가 있는 작업을 수행합니다.
• Resource: AI 모델이 읽을 수 있는 데이터 소스입니다. resource:// URI 스킴을 통해 파일, 데이터베이스 레코드, 설정값 등을 노출합니다.
• Prompt: 미리 정의된 프롬프트 템플릿으로, 사용자가 슬래시 커맨드처럼 활용할 수 있습니다.

 

2-3. 다중 전송 방식 지원

 

MCP는 세 가지 전송(Transport) 방식을 지원합니다.

stdio는 로컬 프로세스 간 통신에 최적화되어 있고, SSE(Server-Sent Events)는 HTTP 기반 단방향 스트리밍을 제공하며, Streamable HTTP는 2025년 3월에 추가된 최신 전송 방식으로 상태 유지/비유지를 모두 지원합니다.

용도에 따라 적절한 전송 방식을 선택할 수 있습니다.

 

2-4. 클라이언트 생태계와의 즉시 호환

 

MCP 서버를 한 번 만들면 Claude Desktop, Claude Code, VS Code(GitHub Copilot), Cursor, Windsurf, Zed 등 MCP를 지원하는 모든 클라이언트에서 즉시 사용할 수 있습니다.

클라이언트별로 별도 어댑터를 작성할 필요가 없습니다.

 

2-5. 프로그레시브 기능 확장

 

최소한의 도구 하나로 시작해서, 필요에 따라 리소스, 프롬프트, 알림(Notification), 샘플링(Sampling) 등의 기능을 점진적으로 추가할 수 있습니다.

서버의 capabilities 선언을 통해 클라이언트는 해당 서버가 어떤 기능을 지원하는지 자동으로 파악합니다.

 

 

---

 

3. 기술 아키텍처 & 동작 원리

 

구성 요소

 

구성 요소	역할	주요 클래스/함수
MCP Client	AI 호스트 앱에서 서버와 통신	Client
MCP Server	도구/리소스/프롬프트 제공	McpServer
Transport	클라이언트-서버 간 메시지 전달	StdioServerTransport, StreamableHTTPServerTransport
Tool Handler	개별 도구의 비즈니스 로직	server.tool() 콜백
Zod Schema	도구 입력 파라미터 검증	z.object()
JSON-RPC 2.0	메시지 프레이밍 프로토콜	내부 처리

 

동작 흐름

 

[AI 클라이언트 (Claude Desktop)]
        │
        │ 1. initialize 요청 (JSON-RPC)
        ▼
[MCP Server]
        │
        │ 2. capabilities 응답 (지원 도구 목록)
        ▼
[AI 클라이언트]
        │
        │ 3. tools/list 요청
        ▼
[MCP Server]
        │
        │ 4. 도구 스키마 목록 응답
        ▼
[AI 모델이 도구 호출 결정]
        │
        │ 5. tools/call 요청 (도구명 + 인자)
        ▼
[MCP Server → Tool Handler]
        │
        │ 6. Zod 스키마 검증 → 비즈니스 로직 실행
        ▼
[MCP Server]
        │
        │ 7. 결과 응답 (content 배열)
        ▼
[AI 클라이언트 → 사용자에게 결과 표시]

 

설계 원칙 4가지

 

1. 단일 책임 원칙 — 하나의 MCP 서버는 하나의 도메인(예: GitHub, Slack, DB)만 담당합니다. 여러 도메인을 하나의 서버에 넣으면 복잡도가 급격히 증가합니다.
2. 명시적 스키마 우선 — 도구의 입력과 출력을 Zod로 명확히 정의하면, AI 모델이 도구를 더 정확하게 호출합니다. 모호한 any 타입은 AI의 오용을 초래합니다.
3. 멱등성 보장 — 같은 인자로 같은 도구를 여러 번 호출해도 동일한 결과를 반환하도록 설계합니다. AI 모델은 네트워크 오류 시 재시도할 수 있기 때문입니다.
4. 최소 권한 원칙 — 도구가 필요한 최소한의 권한만 요청합니다. 파일 읽기 도구에 쓰기 권한을 부여하지 않고, 데이터베이스 조회 도구에 삭제 권한을 부여하지 않습니다.

 

---

 

4. 실무 활용 가이드

 

프로젝트 초기화부터 첫 번째 도구까지

 

아래 코드는 GitHub 리포지토리의 이슈 목록을 조회하는 MCP 서버를 TypeScript로 구축하는 완전한 예시입니다.

 

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 1. MCP 서버 인스턴스 생성
const server = new McpServer({
  name: "github-issues",
  version: "1.0.0",
  description: "GitHub 이슈를 조회하고 관리하는 MCP 서버",
});

// 2. 도구 정의 — 이슈 목록 조회
server.tool(
  "list_issues",
  "지정한 GitHub 리포지토리의 이슈 목록을 조회합니다",
  {
    owner: z.string().describe("리포지토리 소유자 (예: facebook)"),
    repo: z.string().describe("리포지토리 이름 (예: react)"),
    state: z.enum(["open", "closed", "all"]).default("open")
      .describe("이슈 상태 필터"),
    limit: z.number().min(1).max(100).default(10)
      .describe("가져올 이슈 수"),
  },
  async ({ owner, repo, state, limit }) => {
    const response = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues?state=${state}&per_page=${limit}`,
      {
        headers: {
          "Accept": "application/vnd.github.v3+json",
          "User-Agent": "mcp-github-issues",
          // 인증이 필요한 경우:
          // "Authorization": `Bearer ${process.env.GITHUB_TOKEN}`,
        },
      }
    );

    if (!response.ok) {
      return {
        content: [{
          type: "text" as const,
          text: `GitHub API 오류: ${response.status} ${response.statusText}`,
        }],
        isError: true,
      };
    }

    const issues = await response.json() as Array<{
      number: number;
      title: string;
      state: string;
      created_at: string;
      user: { login: string };
      labels: Array<{ name: string }>;
    }>;

    const formatted = issues.map((issue) =>
      `#${issue.number} [${issue.state}] ${issue.title}\n` +
      `  작성자: ${issue.user.login} | 생성일: ${issue.created_at.split("T")[0]}\n` +
      `  라벨: ${issue.labels.map((l) => l.name).join(", ") || "없음"}`
    ).join("\n\n");

    return {
      content: [{
        type: "text" as const,
        text: `## ${owner}/${repo} 이슈 목록 (${state})\n\n${formatted}`,
      }],
    };
  }
);

// 3. 도구 정의 — 이슈 상세 조회
server.tool(
  "get_issue",
  "특정 이슈의 상세 정보와 댓글을 조회합니다",
  {
    owner: z.string().describe("리포지토리 소유자"),
    repo: z.string().describe("리포지토리 이름"),
    issue_number: z.number().describe("이슈 번호"),
  },
  async ({ owner, repo, issue_number }) => {
    const [issueRes, commentsRes] = await Promise.all([
      fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${issue_number}`, {
        headers: { "Accept": "application/vnd.github.v3+json", "User-Agent": "mcp-github-issues" },
      }),
      fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${issue_number}/comments`, {
        headers: { "Accept": "application/vnd.github.v3+json", "User-Agent": "mcp-github-issues" },
      }),
    ]);

    const issue = await issueRes.json() as {
      number: number; title: string; state: string; body: string;
      user: { login: string }; created_at: string;
    };
    const comments = await commentsRes.json() as Array<{
      user: { login: string }; created_at: string; body: string;
    }>;

    const commentText = comments.map((c) =>
      `💬 ${c.user.login} (${c.created_at.split("T")[0]}):\n${c.body}`
    ).join("\n---\n");

    return {
      content: [{
        type: "text" as const,
        text: `# #${issue.number} ${issue.title}\n` +
          `상태: ${issue.state} | 작성자: ${issue.user.login}\n\n` +
          `${issue.body || "(본문 없음)"}\n\n` +
          `## 댓글 (${comments.length}개)\n\n${commentText || "댓글이 없습니다."}`,
      }],
    };
  }
);

// 4. stdio 전송으로 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("GitHub Issues MCP 서버가 시작되었습니다.");

 

기존 환경 도입 4단계

 

단계	작업	명령어 / 설정
1단계: 프로젝트 초기화	npm 프로젝트 생성 + SDK 설치	npm init -y && npm install @modelcontextprotocol/sdk zod
2단계: tsconfig 설정	ESM 모듈 + Node 타입 설정	"module": "NodeNext", "moduleResolution": "NodeNext"
3단계: 서버 코드 작성	도구 정의 + 핸들러 구현	src/index.ts에 McpServer 인스턴스 생성
4단계: 클라이언트 등록	Claude Desktop 또는 VS Code에 서버 경로 등록	claude_desktop_config.json에 mcpServers 항목 추가

 

팀 활용 팁

 

• 공용 MCP 서버 리포지토리를 만들어 팀 내 도구를 중앙 관리하세요. 각 도구는 독립 패키지로 분리하면 버전 관리가 쉬워집니다.
• description 필드를 정성스럽게 작성하세요. AI 모델은 이 설명을 보고 도구 호출 여부를 판단합니다. "데이터를 가져옵니다"보다 "JIRA 프로젝트의 미완료 스프린트 이슈를 우선순위 순으로 조회합니다"가 훨씬 효과적입니다.
• 사내 API에 대한 MCP 서버를 만들면, 신규 팀원이 API 문서를 읽지 않아도 AI를 통해 자연어로 기능을 탐색할 수 있습니다.

 

---

 

5. 경쟁 기술 비교 분석

 

비교 항목	MCP (Model Context Protocol)	OpenAI Function Calling	LangChain Tools	ChatGPT Plugins (deprecated)
프로토콜 표준	JSON-RPC 2.0 기반 오픈 표준	OpenAI 전용 API 스펙	Python/JS 라이브러리 내부 규약	OpenAPI 3.0 기반
모델 종속성	모델 무관 (어떤 LLM이든 가능)	OpenAI 모델 전용	프레임워크 종속	OpenAI ChatGPT 전용
전송 방식	stdio, SSE, Streamable HTTP	HTTP REST	인메모리 함수 호출	HTTP REST
양방향 통신	지원 (알림, 샘플링)	미지원	부분 지원 (콜백)	미지원
리소스 노출	URI 기반 리소스 시스템	미지원	Document Loader로 대체	미지원
타입 안전성	Zod 스키마 + TypeScript	JSON Schema	Pydantic/Zod	JSON Schema
클라이언트 생태계	Claude, VS Code, Cursor 등 다수	OpenAI 플랫폼 내	LangChain/LangGraph 내	ChatGPT 웹 UI
현재 상태	활발히 발전 중 (2025 표준화)	안정적 운영	활발히 발전 중	2024년 GPTs로 대체, 사실상 폐기

 

선택 가이드

 

• MCP를 선택하세요 — 여러 AI 클라이언트에서 동일한 도구를 재사용해야 하거나, 복잡한 양방향 워크플로우가 필요하거나, 팀 내 표준화된 도구 생태계를 구축하려는 경우에 적합합니다.
• OpenAI Function Calling을 선택하세요 — OpenAI 모델만 사용하고, 빠른 프로토타이핑이 목적이며, 이미 OpenAI API에 익숙한 경우에 적합합니다.
• LangChain Tools를 선택하세요 — 복잡한 에이전트 파이프라인을 구성하고, 여러 LLM 프로바이더를 전환하며, RAG 등 고급 패턴이 필요한 경우에 적합합니다. 다만 LangChain도 MCP 클라이언트를 내장하기 시작했으므로, 장기적으로는 MCP와 함께 사용하는 것이 유리합니다.

 

---

 

6. 도입 시 베스트 프랙티스

 

5가지 핵심 원칙

 

1. 도구 이름은 동사_명사 패턴으로 작성하세요. list_issues, create_ticket, search_documents처럼 AI 모델이 기능을 즉시 파악할 수 있는 명명 규칙을 사용합니다.
2. 에러 응답에는 isError: true를 반드시 포함하세요. 이렇게 해야 AI 모델이 에러를 인지하고, 사용자에게 적절한 안내 메시지를 생성하거나 대안을 시도할 수 있습니다.
3. 민감한 정보는 환경 변수로 주입하세요. API 키, 데이터베이스 비밀번호 등을 코드에 하드코딩하면 AI 모델이 해당 정보를 컨텍스트에 포함시킬 위험이 있습니다.
4. 도구 응답은 구조화된 텍스트로 반환하세요. 마크다운 테이블, 번호 목록 등 정형화된 형식을 사용하면 AI 모델이 결과를 더 정확하게 해석하고 사용자에게 전달합니다.
5. 하나의 서버에 도구 10개 이하를 유지하세요. 도구가 너무 많으면 AI 모델의 도구 선택 정확도가 떨어집니다. 도메인별로 서버를 분리하는 것이 좋습니다.

 

흔한 실수와 해결 방법

 

실수	증상	해결 방법
description을 비워두거나 모호하게 작성	AI가 도구를 선택하지 않거나 엉뚱한 도구를 호출	도구와 파라미터 모두에 구체적인 설명을 작성
console.log()를 stdout에 출력	stdio 전송에서 JSON-RPC 메시지가 깨짐	디버그 로그는 반드시 console.error()(stderr)로 출력
동기 작업으로 이벤트 루프 블로킹	서버가 응답하지 않아 클라이언트에서 타임아웃 발생	모든 I/O 작업을 async/await로 처리
package.json에 "type": "module" 누락	ESM import 구문에서 SyntaxError 발생	"type": "module" 추가 또는 .mts 확장자 사용
Zod 스키마 없이 도구 등록	AI 모델이 임의의 인자를 전달하여 런타임 에러	모든 도구에 Zod 스키마를 필수로 정의

 

---

 

7. 향후 전망 & 발전 방향

 

발전 방향 4가지

 

1. OAuth 2.1 기반 원격 인증 표준화 — 2025년 3월 MCP 스펙 업데이트로 Streamable HTTP 전송과 함께 OAuth 2.1 인증 프레임워크가 도입되었습니다. 향후에는 로컬 stdio 방식뿐 아니라, 클라우드에 배포된 MCP 서버에 안전하게 원격 접속하는 것이 표준 워크플로우가 될 것입니다.
2. MCP 서버 마켓플레이스 활성화 — npm 레지스트리와 GitHub에 이미 수천 개의 MCP 서버가 공개되어 있습니다. 향후 Claude Desktop이나 VS Code 내에서 원클릭으로 MCP 서버를 검색·설치·활성화할 수 있는 통합 마켓플레이스가 등장할 것으로 예상됩니다.
3. 에이전트 간 MCP 통신 — 현재는 사람이 AI에게 도구를 제공하는 패턴이 주류이지만, 향후에는 AI 에이전트가 다른 AI 에이전트의 MCP 서버를 호출하는 에이전트-투-에이전트(A2A) 패턴이 보편화될 것입니다. Google의 A2A 프로토콜과의 상호운용도 논의되고 있습니다.
4. 엘리시테이션(Elicitation) 패턴 확산 — MCP의 양방향 통신을 활용해, 도구 실행 중간에 AI가 사용자에게 추가 정보를 요청하는 패턴이 늘어날 것입니다. 예를 들어, 배포 도구가 "프로덕션에 배포할까요?"라고 확인을 요청하는 인터랙티브 워크플로우가 가능해집니다.

 

개발자 시사점

 

• 지금 MCP 서버 개발 경험을 쌓아두면 AI 도구 생태계의 초기 기여자가 될 수 있습니다.
• 사내 시스템(CI/CD, 모니터링, 티켓 시스템)에 대한 MCP 서버는 팀 생산성을 극적으로 향상시키는 "숨은 인프라"가 됩니다.
• TypeScript는 MCP 서버 개발에서 가장 성숙한 SDK를 보유하고 있어, 첫 MCP 서버 언어로 가장 적합합니다.

 

---

 

마무리

 

오늘 다룬 내용을 정리하겠습니다.

 

• MCP는 AI 모델과 외부 도구를 잇는 오픈 표준 프로토콜로, 한 번 만들면 여러 AI 클라이언트에서 재사용할 수 있습니다.
• TypeScript + Zod 조합으로 타입 안전하고 검증 가능한 도구를 빠르게 구축할 수 있습니다.
• 도구 설명의 품질이 AI의 도구 활용 정확도를 결정하므로, description 작성에 가장 많은 시간을 투자하세요.
• MCP 서버 직접 만들기 TypeScript 커스텀 도구 구축은 어렵지 않습니다. SDK 설치부터 첫 도구 등록까지 30분이면 충분합니다.

 

아래에 클라이언트(Claude Desktop)에 서버를 등록하는 설정 예시도 첨부합니다.

 

{
  "mcpServers": {
    "github-issues": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

 

이 파일을 Claude Desktop의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json에, Claude Code의 경우 프로젝트 루트의 .mcp.json(혹은 claude mcp add 명령)에 설정하면 됩니다.

 

MCP 서버 개발에 관심이 생기셨다면, 공식 MCP 문서와 TypeScript SDK 리포지토리를 참고해보세요.

질문이나 의견이 있으시면 댓글로 남겨주세요.

이 글이 도움이 되셨다면 공유도 부탁드립니다!

 

다음 글에서는 실제 프로덕션 환경에 MCP 서버를 Docker로 배포하고, Streamable HTTP 전송으로 원격 접속하는 방법을 다루겠습니다.

그때까지 즐거운 코딩 되세요! 🚀