[Claude] MCP 서버 구축 설치방법 - AI 에이전트와 외부 도구 연동하기

 

안녕하세요!

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

 

오늘은 AI 개발 생태계에서 가장 뜨거운 주제 중 하나인 MCP(Model Context Protocol) 서버 구축에 대해 깊이 있게 다뤄보겠습니다.

Claude를 비롯한 AI 에이전트가 외부 도구와 실시간으로 소통할 수 있게 해주는 MCP는, 단순한 프롬프트 엔지니어링을 넘어 진정한 AI 자동화의 핵심 인프라로 자리 잡고 있습니다.

 

이 글은 MCP를 처음 접하는 분부터, 이미 Claude를 사용 중이지만 외부 도구 연동을 통해 더 강력한 워크플로우를 구축하고 싶은 분 모두를 위해 작성되었습니다.

 

 

---

 

1. MCP(Model Context Protocol)란 무엇인가?

 

핵심 정의

 

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 오픈소스로 공개한 AI 모델과 외부 도구/데이터 소스 간의 표준 통신 프로토콜입니다. 쉽게 말해, Claude 같은 LLM이 파일 시스템, 데이터베이스, API, 웹 브라우저 등 외부 시스템과 구조화된 방식으로 상호작용할 수 있도록 만들어주는 브릿지 역할을 합니다.

 

USB가 다양한 주변기기를 하나의 표준으로 연결해주듯, MCP는 다양한 외부 도구를 AI 모델에 하나의 표준으로 연결해주는 "AI의 USB-C"라고 이해하면 됩니다.

 

왜 MCP가 필요한가?

 

MCP 이전에는 AI에 외부 도구를 연동하려면 각 도구마다 개별적인 통합 코드를 작성해야 했습니다. 이 방식에는 여러 문제가 있었습니다.

 

• N x M 통합 문제: AI 모델 N개 x 도구 M개 = N*M개의 개별 연동 코드가 필요했습니다. 모델이 바뀌면 모든 도구 연동을 다시 작성해야 했습니다.
• 표준 부재: OpenAI의 Function Calling, LangChain의 Tools, Google의 Extensions 등 각 플랫폼마다 도구 연동 방식이 달랐습니다.
• 재사용 불가: Slack 연동을 한번 만들어도 다른 AI 앱에서 재사용할 수 없었습니다.
• 보안 관리 어려움: 각 도구별로 인증과 권한 체계가 제각각이라 일관된 보안 정책 적용이 불가능했습니다.

 

MCP는 이 문제를 클라이언트-서버 아키텍처와 표준화된 프로토콜로 해결합니다.

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

 

 

---

 

2. MCP 아키텍처 & 핵심 개념

 

MCP 시스템은 3개의 핵심 구성 요소로 이루어집니다.

 

구성 요소	역할	예시
MCP Host	사용자가 상호작용하는 AI 애플리케이션	Claude Desktop, Claude Code, Cursor, VS Code
MCP Client	Host 내부에서 서버와 1:1 통신하는 커넥터	Host가 자동 관리 (개발자가 직접 만들 일은 드묾)
MCP Server	외부 도구/데이터를 노출하는 경량 서버	GitHub MCP, Slack MCP, DB 조회 서버 등

 

MCP 서버가 제공하는 3가지 프리미티브

 

프리미티브	설명	호출 주체	예시
Tools	AI 모델이 호출할 수 있는 함수	AI 모델 (자동)	DB 쿼리, API 호출, 파일 생성
Resources	AI 모델에 컨텍스트를 제공하는 데이터	클라이언트/사용자	파일 내용, 설정값, 스키마 정보
Prompts	재사용 가능한 프롬프트 템플릿	사용자 (수동 선택)	코드 리뷰 템플릿, 분석 지시문

 

이 중 Tools가 가장 핵심적이며, 대부분의 MCP 서버는 커스텀 Tool을 제공하는 것이 주요 목적입니다.

 

통신 방식: stdio vs HTTP

 

전송 방식	동작 방식	적합한 경우
stdio	Host가 서버 프로세스를 직접 실행, 표준 입출력으로 통신	로컬 도구 (파일 시스템, Git, 로컬 DB)
Streamable HTTP	HTTP 엔드포인트로 원격 통신, SSE로 스트리밍	원격 서비스, 팀 공유, 클라우드 배포

 

 

---

 

3. MCP 서버 구축 - TypeScript 실전 코드

 

Anthropic 공식 @modelcontextprotocol/sdk를 사용하여 실제로 동작하는 MCP 서버를 만들어 보겠습니다.

 

프로젝트 초기 설정

 

# 프로젝트 생성
mkdir my-mcp-server && cd my-mcp-server
npm init -y

# 필수 패키지 설치
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# tsconfig.json 설정
npx tsc --init --target ES2022 --module NodeNext \
  --moduleResolution NodeNext --outDir ./dist

 

기본 MCP 서버 구현

 

사내 프로젝트 현황을 조회하는 MCP 서버를 예시로 만들겠습니다.

 

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

// 예시 데이터 (실제로는 DB나 API에서 가져옴)
const projects = [
  { id: 1, name: "웹 리뉴얼", status: "진행중", progress: 65, lead: "김개발" },
  { id: 2, name: "모바일 앱 v2", status: "기획", progress: 15, lead: "박기획" },
  { id: 3, name: "데이터 파이프라인", status: "완료", progress: 100, lead: "이데이터" },
];

// MCP 서버 인스턴스 생성
const server = new McpServer({
  name: "project-tracker",
  version: "1.0.0",
  description: "사내 프로젝트 현황 조회 MCP 서버",
});

// Tool 1: 프로젝트 목록 조회
server.tool(
  "list_projects",
  "모든 프로젝트의 현황을 조회합니다",
  { status: z.enum(["전체", "진행중", "기획", "완료"]).optional() },
  async ({ status }) => {
    const filtered = status && status !== "전체"
      ? projects.filter((p) => p.status === status)
      : projects;

    const summary = filtered
      .map((p) => `[${p.status}] ${p.name} - 진행률 ${p.progress}% (담당: ${p.lead})`)
      .join("\n");

    return {
      content: [{ type: "text", text: summary || "조건에 맞는 프로젝트가 없습니다." }],
    };
  }
);

// Tool 2: 프로젝트 상세 조회
server.tool(
  "get_project",
  "프로젝트 ID로 상세 정보를 조회합니다",
  { projectId: z.number().describe("프로젝트 ID") },
  async ({ projectId }) => {
    const project = projects.find((p) => p.id === projectId);
    if (!project) {
      return { content: [{ type: "text", text: `ID ${projectId} 프로젝트를 찾을 수 없습니다.` }] };
    }
    return {
      content: [{ type: "text", text: JSON.stringify(project, null, 2) }],
    };
  }
);

// Resource: 프로젝트 요약 데이터
server.resource(
  "project-summary",
  "project://summary",
  { description: "전체 프로젝트 현황 요약", mimeType: "application/json" },
  async () => ({
    contents: [{
      uri: "project://summary",
      text: JSON.stringify({
        total: projects.length,
        byStatus: { 진행중: 1, 기획: 1, 완료: 1 },
        avgProgress: Math.round(projects.reduce((s, p) => s + p.progress, 0) / projects.length),
      }, null, 2),
    }],
  })
);

// 서버 시작 (stdio 전송)
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Project Tracker MCP Server running on stdio");

 

핵심 포인트를 정리하면 다음과 같습니다.

 

• server.tool()로 AI가 호출할 수 있는 함수를 등록합니다. Zod 스키마로 파라미터를 정의하면 AI 모델이 자동으로 올바른 인자를 넘겨줍니다.
• server.resource()로 AI에 컨텍스트 데이터를 제공합니다. 사용자가 리소스를 첨부하면 AI가 참고 자료로 활용합니다.
• StdioServerTransport는 로컬 실행용입니다. Claude Desktop이나 Claude Code가 이 서버 프로세스를 직접 실행합니다.
• console.error로 로깅합니다. stdout은 JSON-RPC 통신용이므로 절대 console.log를 사용하면 안 됩니다.

 

---

 

4. Claude Desktop & Claude Code에 연동하기

 

구축한 MCP 서버를 실제 Claude 클라이언트에 연결하는 방법입니다.

 

Claude Desktop 설정

 

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 파일을 수정합니다.

 

{
  "mcpServers": {
    "project-tracker": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-mcp-server/src/index.ts"],
      "env": {
        "DB_URL": "postgresql://localhost:5432/projects"
      }
    }
  }
}

 

Claude Code 설정

 

Claude Code에서는 CLI 명령어로 간단하게 추가할 수 있습니다.

 

# stdio 방식 (로컬 서버)
claude mcp add project-tracker -- npx tsx /path/to/src/index.ts

# HTTP 방식 (원격 서버)
claude mcp add project-tracker --transport http https://mcp.example.com/project-tracker

# 등록된 서버 확인
claude mcp list

# 서버 제거
claude mcp remove project-tracker

 

설정 후 Claude에 "진행 중인 프로젝트 현황 알려줘"라고 요청하면, Claude가 자동으로 list_projects Tool을 호출하여 실시간 데이터를 가져옵니다.

 

 

---

 

5. 실전 활용 사례 & 확장 패턴

 

MCP 서버를 실무에서 활용하는 대표적인 패턴 4가지를 소개합니다.

 

패턴 1: 데이터베이스 조회 서버

 

가장 많이 사용되는 패턴입니다. Claude가 자연어로 "이번 달 매출 상위 10개 제품 알려줘"라고 요청하면, MCP 서버가 SQL 쿼리를 실행하여 결과를 반환합니다.

 

server.tool(
  "query_sales",
  "매출 데이터를 조회합니다. 기간과 조건을 지정할 수 있습니다.",
  {
    startDate: z.string().describe("시작일 (YYYY-MM-DD)"),
    endDate: z.string().describe("종료일 (YYYY-MM-DD)"),
    limit: z.number().default(10).describe("결과 수 제한"),
  },
  async ({ startDate, endDate, limit }) => {
    // 파라미터화된 쿼리로 SQL Injection 방지
    const results = await db.query(
      `SELECT product_name, SUM(amount) as total
       FROM sales WHERE date BETWEEN $1 AND $2
       GROUP BY product_name ORDER BY total DESC LIMIT $3`,
      [startDate, endDate, limit]
    );
    return { content: [{ type: "text", text: JSON.stringify(results.rows, null, 2) }] };
  }
);

 

패턴 2: 외부 API 래퍼

 

Jira 이슈 생성, Slack 메시지 전송, GitHub PR 리뷰 요청 등 외부 서비스를 Claude가 직접 제어할 수 있게 합니다. 이미 GitHub, Slack, Linear 등 주요 서비스의 공식 MCP 서버가 공개되어 있으므로 직접 만들 필요 없이 바로 활용할 수 있습니다.

 

패턴 3: 파일 시스템 + 코드 분석

 

프로젝트 디렉토리의 파일을 읽고, 코드 구조를 분석하고, 테스트를 실행하는 개발 보조 도구입니다. Claude Code가 이미 이 기능을 내장하고 있지만, 사내 코딩 컨벤션 검사나 특정 프레임워크 분석 등 커스텀 도구를 추가할 수 있습니다.

 

패턴 4: 모니터링 & 알림

 

서버 상태, 에러 로그, 배포 이력을 조회하는 DevOps 도구입니다. "오늘 발생한 500 에러 패턴 분석해줘"라고 요청하면 Claude가 로그를 가져와 패턴을 분석하고 원인을 추론합니다.

 

---

 

6. 기존 도구 연동 방식 비교

 

MCP 이전에도 AI에 도구를 연동하는 방법이 있었습니다. 각 방식의 장단점을 비교해 보겠습니다.

 

비교 항목	MCP	OpenAI Function Calling	LangChain Tools
표준화	오픈 프로토콜 (벤더 중립)	OpenAI 전용	프레임워크 전용
재사용성	서버 1개로 모든 MCP 호환 앱에서 사용	앱마다 별도 구현 필요	LangChain 앱에서만 사용
실행 위치	로컬 또는 원격 서버	앱 내부 (직접 구현)	앱 내부 (직접 구현)
보안	프로토콜 수준 권한 제어	직접 구현	직접 구현
생태계	수천 개 커뮤니티 서버	GPT Store (OpenAI 종속)	LangChain Hub
스트리밍	SSE 기반 네이티브 지원	별도 구현 필요	Callback 기반

 

MCP의 가장 큰 차별점은 벤더 중립적인 오픈 프로토콜이라는 점입니다. Claude뿐 아니라 OpenAI, Google 등도 MCP 지원을 발표하면서 사실상 AI 도구 연동의 표준으로 자리 잡고 있습니다.

 

---

 

7. 베스트 프랙티스 & 주의사항

 

MCP 서버를 프로덕션 수준으로 운영하기 위한 핵심 원칙들입니다.

 

1. Tool 설명(description)이 곧 성능이다

 

AI 모델은 Tool의 name과 description만 보고 어떤 Tool을 호출할지 결정합니다. 모호한 설명은 잘못된 Tool 호출로 이어집니다.

 

// Bad: 모호한 설명
server.tool("get_data", "데이터를 가져옵니다", ...);

// Good: 명확한 설명
server.tool(
  "get_monthly_sales_report",
  "특정 월의 제품별 매출 합계를 조회합니다. 결과는 매출 내림차순으로 정렬됩니다.",
  ...
);

 

2. 에러 핸들링은 AI가 이해할 수 있게

 

에러 메시지를 사람이 아닌 AI가 읽는다는 점을 기억하세요. AI가 다음 행동을 결정할 수 있도록 구체적인 맥락을 제공해야 합니다.

 

// Bad
return { content: [{ type: "text", text: "Error occurred" }], isError: true };

// Good
return {
  content: [{
    type: "text",
    text: "프로젝트 ID 99를 찾을 수 없습니다. 유효한 ID 범위는 1~50입니다. list_projects Tool로 전체 목록을 먼저 확인하세요."
  }],
  isError: true,
};

 

3. 보안 체크리스트

 

• 입력 검증 필수: Zod 스키마로 모든 파라미터를 검증하세요. AI가 예상치 못한 값을 보낼 수 있습니다.
• 파라미터화된 쿼리: SQL을 사용한다면 반드시 Prepared Statement를 사용하세요. AI가 생성한 입력을 직접 쿼리에 삽입하면 SQL Injection 위험이 있습니다.
• 최소 권한 원칙: DB 접근은 READ-ONLY 계정으로, 파일 접근은 특정 디렉토리로 제한하세요.
• Rate Limiting: 외부 API를 호출하는 Tool에는 반드시 rate limit을 설정하세요.
• 민감 정보 마스킹: Tool 응답에 API 키, 비밀번호 등이 포함되지 않도록 필터링하세요.

 

4. 성능 최적화

 

• 응답 크기 제한: Tool 응답이 너무 크면 AI 모델의 컨텍스트 윈도우를 낭비합니다. 결과가 100건 이상이면 상위 N건만 반환하고 "추가 결과가 있습니다"를 명시하세요.
• 타임아웃 설정: 외부 API 호출에는 반드시 타임아웃을 설정하세요. MCP 클라이언트도 기본 타임아웃이 있으므로 이를 초과하면 연결이 끊깁니다.
• 캐싱: 자주 호출되는 데이터는 메모리 캐싱으로 응답 속도를 높이세요.

 

---

 

마무리

 

지금까지 MCP(Model Context Protocol)의 개념부터 TypeScript로 직접 서버를 구축하고 Claude에 연동하는 방법까지 살펴보았습니다.

 

핵심을 정리하면 다음과 같습니다.

 

• MCP는 AI 모델과 외부 도구를 연결하는 표준 프로토콜로, "AI의 USB-C"입니다.
• Tools, Resources, Prompts 3가지 프리미티브를 이해하면 어떤 도구든 MCP로 래핑할 수 있습니다.
• TypeScript + @modelcontextprotocol/sdk로 30분 만에 실제 동작하는 MCP 서버를 만들 수 있습니다.
• Tool 설명의 품질이 AI의 도구 활용 정확도를 직접 좌우합니다.
• OpenAI, Google까지 MCP를 채택하면서 사실상 업계 표준으로 확정되었습니다.

 

MCP는 2026년 현재 AI 개발자가 반드시 알아야 할 핵심 기술입니다.

오늘 소개한 코드를 참고하여 여러분만의 MCP 서버를 구축해 보세요!

 

궁금한 점이나 직접 만든 MCP 서버가 있다면 댓글로 공유해 주세요.

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

감사합니다!