Claude MCP 서버 설정 가이드: Claude Code와 Desktop을 위한 커스텀 도구 통합
MCP란 무엇이며 왜 중요한가
Model Context Protocol(MCP)은 Anthropic이 개발한 개방형 표준 프로토콜로, AI 모델이 외부 데이터 소스와 도구에 안전하게 접근할 수 있도록 설계되었다. 기존에 Claude를 사용할 때 가장 큰 제약은 모델이 학습 데이터 이외의 실시간 정보에 접근하지 못한다는 점이었다. MCP는 이 한계를 근본적으로 해결한다.
MCP를 활용하면 Claude가 데이터베이스에 직접 쿼리를 실행하거나, 외부 API를 호출하거나, 로컬 파일 시스템을 탐색하는 등의 작업을 수행할 수 있다. 개발자가 MCP 서버를 한 번 구축해두면 Claude Code, Claude Desktop, 그리고 MCP를 지원하는 모든 클라이언트에서 동일한 도구를 재사용할 수 있다. 이는 각 플랫폼마다 별도의 통합 코드를 작성해야 했던 기존 방식에 비해 획기적인 개선이다.
특히 개발 워크플로우에서 MCP의 가치는 두드러진다. 예를 들어 Claude Code에서 코드를 작성하면서 동시에 프로덕션 데이터베이스의 스키마를 조회하거나, Jira 티켓을 확인하거나, Slack 채널에 알림을 보내는 것이 모두 하나의 대화 안에서 가능해진다.
MCP 아키텍처: 구성요소와 연결 방식
MCP는 클라이언트-서버 아키텍처를 따른다. 전체 구조를 이해하면 커스텀 서버를 설계할 때 올바른 판단을 내릴 수 있다.
핵심 구성요소
MCP 호스트(Host): Claude Code, Claude Desktop 같은 애플리케이션이다. 사용자와 직접 상호작용하며, MCP 클라이언트를 내장하고 있다.
MCP 클라이언트(Client): 호스트 내부에서 동작하며, MCP 서버와 1:1 연결을 유지한다. 프로토콜 협상, 메시지 라우팅, 기능 교환을 담당한다.
MCP 서버(Server): 개발자가 구축하는 경량 프로그램이다. 특정 기능을 도구(Tools), 리소스(Resources), 프롬프트(Prompts)의 형태로 노출한다.
전송 유형(Transport Types)
MCP는 두 가지 전송 방식을 지원한다.
stdio(표준 입출력): 서버가 로컬 프로세스로 실행되며, 표준 입력과 출력을 통해 통신한다. 로컬 개발 환경에서 가장 일반적으로 사용되는 방식이다. Claude Code는 기본적으로 stdio 전송을 사용한다.
SSE(Server-Sent Events): HTTP 기반 전송으로, 서버가 원격에서 실행될 때 사용한다. 팀 공유 서버나 클라우드 배포 시나리오에 적합하다.
프로토콜 기능
MCP 서버가 제공할 수 있는 세 가지 주요 기능이 있다.
- 도구(Tools): Claude가 호출할 수 있는 함수. 데이터베이스 쿼리, API 호출, 파일 조작 등의 액션을 수행한다.
- 리소스(Resources): Claude가 읽을 수 있는 데이터. 파일 내용, 데이터베이스 스키마, 설정 정보 등을 제공한다.
- 프롬프트(Prompts): 미리 정의된 템플릿. 특정 작업에 최적화된 프롬프트를 서버에서 관리한다.
이 가이드에서는 가장 활용도가 높은 도구(Tools) 구현에 집중한다.
첫 번째 MCP 서버 설정: TypeScript 5단계
TypeScript는 MCP 서버 개발에 가장 널리 사용되는 언어다. 타입 안전성과 풍부한 SDK 지원 덕분에 안정적인 서버를 빠르게 구축할 수 있다.
1단계: 프로젝트 초기화 및 SDK 설치
mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --inittsconfig.json에서 다음 설정을 확인한다.
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"rootDir": "./src",
"strict": true
}
}package.json에 다음을 추가한다.
{
"type": "module",
"bin": {
"my-mcp-server": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
}
}2단계: 서버 인스턴스 생성
src/index.ts 파일을 생성한다.
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "my-mcp-server",
version: "1.0.0",
capabilities: {
tools: {},
},
});3단계: 도구 정의
도구는 이름, 설명, 입력 스키마, 핸들러 함수로 구성된다. Zod를 사용해 입력 스키마를 정의하면 자동으로 JSON Schema가 생성된다.
server.tool(
"get-weather",
"지정한 도시의 현재 날씨 정보를 조회합니다",
{
city: z.string().describe("도시 이름 (예: Seoul, Tokyo)"),
units: z.enum(["metric", "imperial"]).default("metric").describe("온도 단위"),
},
async ({ city, units }) => {
const apiKey = process.env.WEATHER_API_KEY;
if (!apiKey) {
return {
content: [{ type: "text", text: "WEATHER_API_KEY 환경 변수가 설정되지 않았습니다." }],
isError: true,
};
}
const url = `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&units=${units}&appid=${apiKey}`;
const response = await fetch(url);
const data = await response.json();
if (!response.ok) {
return {
content: [{ type: "text", text: `API 오류: ${data.message}` }],
isError: true,
};
}
const unitLabel = units === "metric" ? "C" : "F";
const result = `${city}: ${data.main.temp} ${unitLabel}, ${data.weather[0].description}`;
return {
content: [{ type: "text", text: result }],
};
}
);4단계: 전송 연결 및 서버 시작
파일 하단에 전송 연결 코드를 추가한다.
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCP 서버가 시작되었습니다.");
}
main().catch((error) => {
console.error("서버 시작 실패:", error);
process.exit(1);
});console.error를 사용하는 이유는 stdout이 MCP 프로토콜 통신에 사용되기 때문이다. 로그는 반드시 stderr로 출력해야 한다.
5단계: 빌드 및 Claude Code에 등록
npm run build프로젝트 루트의 .claude/mcp.json 파일에 서버를 등록한다.
{
"mcpServers": {
"my-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"],
"env": {
"WEATHER_API_KEY": "your-api-key-here"
}
}
}
}또는 Claude Code CLI에서 직접 등록할 수도 있다.
claude mcp add my-mcp-server node /absolute/path/to/my-mcp-server/dist/index.jsClaude Code를 재시작하면 새 도구가 자동으로 인식된다. /mcp 명령으로 연결 상태를 확인할 수 있다.
MCP 서버 설정: Python 3단계
Python 개발자라면 Python SDK를 사용해 동일한 기능의 MCP 서버를 구축할 수 있다.
1단계: 환경 설정 및 SDK 설치
mkdir my-mcp-server-py
cd my-mcp-server-py
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install mcp[cli]2단계: 서버 및 도구 구현
server.py 파일을 생성한다.
import os
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-mcp-server")
@mcp.tool()
async def get_weather(city: str, units: str = "metric") -> str:
"""지정한 도시의 현재 날씨 정보를 조회합니다.
Args:
city: 도시 이름 (예: Seoul, Tokyo)
units: 온도 단위 (metric 또는 imperial)
"""
api_key = os.environ.get("WEATHER_API_KEY")
if not api_key:
return "오류: WEATHER_API_KEY 환경 변수가 설정되지 않았습니다."
url = "https://api.openweathermap.org/data/2.5/weather"
params = {"q": city, "units": units, "appid": api_key}
async with httpx.AsyncClient() as client:
response = await client.get(url, params=params)
data = response.json()
if response.status_code != 200:
return f"API 오류: {data.get('message', '알 수 없는 오류')}"
unit_label = "C" if units == "metric" else "F"
return f"{city}: {data['main']['temp']}{unit_label}, {data['weather'][0]['description']}"
@mcp.tool()
async def query_database(sql: str) -> str:
"""읽기 전용 SQL 쿼리를 실행합니다.
Args:
sql: 실행할 SELECT 쿼리문
"""
if not sql.strip().upper().startswith("SELECT"):
return "오류: SELECT 쿼리만 허용됩니다."
# 실제 구현에서는 데이터베이스 연결 사용
return f"쿼리 결과: (예시 데이터)"3단계: 서버 실행 및 Claude Code 등록
개발 중에는 MCP Inspector로 테스트할 수 있다.
mcp dev server.pyClaude Code에 등록할 때는 다음과 같이 설정한다.
{
"mcpServers": {
"my-python-server": {
"command": "python",
"args": ["/absolute/path/to/server.py"],
"env": {
"WEATHER_API_KEY": "your-api-key-here"
}
}
}
}Python의 FastMCP는 데코레이터 기반으로 도구를 정의하므로 보일러플레이트 코드가 적다. docstring이 자동으로 도구 설명이 되고, 타입 힌트가 입력 스키마로 변환된다.
자주 사용하는 MCP 서버 패턴
실무에서 반복적으로 등장하는 MCP 서버 패턴 세 가지를 살펴본다.
데이터베이스 쿼리 서버
가장 흔한 패턴이다. Claude가 데이터베이스에 직접 쿼리를 실행할 수 있게 해준다.
import Database from "better-sqlite3";
server.tool(
"query-db",
"SQLite 데이터베이스에 읽기 전용 쿼리를 실행합니다",
{
sql: z.string().describe("실행할 SQL SELECT 쿼리"),
},
async ({ sql }) => {
const normalized = sql.trim().toUpperCase();
if (!normalized.startsWith("SELECT")) {
return {
content: [{ type: "text", text: "오류: SELECT 문만 허용됩니다." }],
isError: true,
};
}
const db = new Database(process.env.DB_PATH!, { readonly: true });
try {
const rows = db.prepare(sql).all();
return {
content: [{ type: "text", text: JSON.stringify(rows, null, 2) }],
};
} catch (error) {
return {
content: [{ type: "text", text: `쿼리 실행 오류: ${error}` }],
isError: true,
};
} finally {
db.close();
}
}
);핵심은 읽기 전용 모드로 데이터베이스를 열고, SELECT 이외의 쿼리를 차단하는 것이다.
REST API 통합 서버
외부 API를 Claude의 도구로 감싸는 패턴이다.
server.tool(
"search-issues",
"GitHub 저장소에서 이슈를 검색합니다",
{
repo: z.string().describe("owner/repo 형식의 저장소 이름"),
query: z.string().describe("검색 키워드"),
state: z.enum(["open", "closed", "all"]).default("open"),
},
async ({ repo, query, state }) => {
const token = process.env.GITHUB_TOKEN;
const url = `https://api.github.com/search/issues?q=${encodeURIComponent(query)}+repo:${repo}+state:${state}`;
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/vnd.github.v3+json",
},
});
const data = await response.json();
const issues = data.items.slice(0, 10).map((issue: any) => ({
number: issue.number,
title: issue.title,
state: issue.state,
url: issue.html_url,
}));
return {
content: [{ type: "text", text: JSON.stringify(issues, null, 2) }],
};
}
);파일시스템 접근 서버
특정 디렉토리 내의 파일을 안전하게 읽고 검색하는 패턴이다.
import { readFile, readdir } from "fs/promises";
import path from "path";
const ALLOWED_DIR = process.env.DOCS_DIR || "/docs";
server.tool(
"read-doc",
"허용된 디렉토리에서 문서 파일을 읽습니다",
{
filePath: z.string().describe("읽을 파일의 상대 경로"),
},
async ({ filePath }) => {
const resolved = path.resolve(ALLOWED_DIR, filePath);
if (!resolved.startsWith(path.resolve(ALLOWED_DIR))) {
return {
content: [{ type: "text", text: "오류: 허용된 디렉토리 외부 접근이 차단되었습니다." }],
isError: true,
};
}
try {
const content = await readFile(resolved, "utf-8");
return {
content: [{ type: "text", text: content }],
};
} catch (error) {
return {
content: [{ type: "text", text: `파일 읽기 오류: ${error}` }],
isError: true,
};
}
}
);경로 순회(Path Traversal) 공격을 방지하기 위해 path.resolve 후 허용된 디렉토리 내부인지 반드시 검증해야 한다.
Claude Desktop 설정
Claude Desktop에서 MCP 서버를 사용하려면 설정 파일을 수정해야 한다.
macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json 파일을 편집한다.
{
"mcpServers": {
"my-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {
"WEATHER_API_KEY": "your-api-key-here"
}
},
"my-python-server": {
"command": "python",
"args": ["/absolute/path/to/server.py"],
"env": {
"DB_PATH": "/path/to/database.sqlite"
}
}
}
}설정을 저장한 후 Claude Desktop을 재시작한다. 대화 입력 창 근처에 도구 아이콘이 표시되면 MCP 서버가 정상적으로 연결된 것이다. 도구 아이콘을 클릭하면 사용 가능한 도구 목록을 확인할 수 있다.
npx로 설치 없이 바로 실행할 수 있는 서버도 있다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
}
}
}보안 베스트 프랙티스
MCP 서버는 Claude에게 시스템 자원에 대한 접근 권한을 부여하므로 보안에 각별히 신경 써야 한다.
입력 검증
모든 도구 입력은 반드시 검증해야 한다. Zod 스키마가 기본적인 타입 검증을 해주지만, 비즈니스 로직 수준의 검증은 핸들러에서 직접 수행해야 한다.
server.tool(
"query-users",
"사용자 정보를 조회합니다",
{
userId: z.number().int().positive().describe("사용자 ID"),
fields: z.array(z.enum(["name", "email", "role"])).describe("조회할 필드"),
},
async ({ userId, fields }) => {
// 허용된 필드만 SELECT 절에 포함
const safeFields = fields.join(", ");
const query = `SELECT ${safeFields} FROM users WHERE id = ?`;
// 파라미터 바인딩으로 SQL 인젝션 방지
// ...
}
);SQL을 직접 입력받는 도구는 반드시 읽기 전용으로 제한하고, 가능하면 파라미터화된 쿼리를 사용해야 한다.
최소 권한 원칙
MCP 서버에는 필요한 최소한의 권한만 부여한다.
- 데이터베이스 서버: 읽기 전용 계정 사용
- API 통합 서버: 필요한 스코프만 가진 토큰 사용
- 파일시스템 서버: 특정 디렉토리로 접근 범위 제한
환경 변수 관리
API 키, 데이터베이스 비밀번호 등 민감한 정보는 절대 코드에 하드코딩하지 않는다.
// 올바른 방법
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error("API_KEY 환경 변수가 필요합니다.");
}
// 잘못된 방법
const apiKey = "sk-1234567890abcdef";MCP 설정 파일의 env 필드를 활용하면 서버별로 환경 변수를 격리할 수 있다. .env 파일을 사용하는 경우 반드시 .gitignore에 추가한다.
타임아웃과 레이트 리미팅
외부 API를 호출하는 도구에는 타임아웃을 설정하고, 과도한 호출을 방지하는 레이트 리미팅을 적용한다.
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);
try {
const response = await fetch(url, { signal: controller.signal });
// ...
} finally {
clearTimeout(timeout);
}MCP 서버 디버깅
MCP 서버 개발 중 문제가 발생하면 체계적으로 디버깅해야 한다.
MCP Inspector 활용
MCP Inspector는 서버를 독립적으로 테스트할 수 있는 공식 도구다.
# TypeScript 서버 테스트
npx @modelcontextprotocol/inspector node dist/index.js
# Python 서버 테스트
npx @modelcontextprotocol/inspector python server.pyInspector가 브라우저에서 열리면 각 도구를 개별적으로 호출하고 응답을 확인할 수 있다.
일반적인 문제와 해결 방법
서버가 연결되지 않는 경우: 가장 흔한 원인은 경로 문제다. mcp.json에 절대 경로를 사용하고 있는지, 해당 경로에 실행 파일이 존재하는지 확인한다.
도구가 목록에 나타나지 않는 경우: 서버가 capabilities에 tools: {}를 선언했는지 확인한다. TypeScript SDK의 McpServer는 도구가 하나라도 등록되면 자동으로 선언하지만, 저수준 Server 클래스를 사용하는 경우 수동으로 선언해야 한다.
stdout 오염 문제: MCP는 stdout을 프로토콜 통신에 사용한다. console.log 대신 반드시 console.error를 사용해야 한다. 타사 라이브러리가 stdout에 출력하는 경우에도 주의가 필요하다.
환경 변수 미전달: mcp.json의 env 필드에 설정한 환경 변수가 서버 프로세스에 전달되지 않는 경우, Claude Code를 완전히 종료하고 재시작해본다.
로깅 구현
프로덕션 수준의 MCP 서버에는 구조화된 로깅이 필수다.
function log(level: string, message: string, data?: Record<string, unknown>) {
const entry = {
timestamp: new Date().toISOString(),
level,
message,
...data,
};
console.error(JSON.stringify(entry));
}
// 사용 예시
log("info", "도구 호출", { tool: "get-weather", args: { city: "Seoul" } });
log("error", "API 요청 실패", { status: 500, url: "https://api.example.com" });Claude Code에서 /mcp 명령으로 서버 상태를 확인하고, 서버 로그를 stderr에서 모니터링하면 대부분의 문제를 진단할 수 있다.
팀에 MCP 서버 배포하기
개인 프로젝트에서 검증된 MCP 서버를 팀 전체가 사용할 수 있도록 배포하는 방법이다.
npm 패키지 배포
가장 간단한 배포 방법은 npm 패키지로 퍼블리시하는 것이다.
{
"name": "@myorg/mcp-server-internal",
"version": "1.0.0",
"bin": {
"mcp-server-internal": "./dist/index.js"
},
"files": ["dist"]
}npm publish --access restricted팀원들은 npx로 바로 사용할 수 있다.
{
"mcpServers": {
"internal-tools": {
"command": "npx",
"args": ["-y", "@myorg/mcp-server-internal"],
"env": {
"DB_HOST": "db.internal.company.com"
}
}
}
}Docker 배포
서버가 특정 런타임이나 시스템 의존성을 필요로 하는 경우 Docker가 적합하다.
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
ENTRYPOINT ["node", "dist/index.js"]docker build -t mcp-server-internal .
docker push registry.company.com/mcp-server-internal:latestDocker 기반 MCP 서버는 SSE 전송을 사용하는 것이 일반적이다. stdio 대신 HTTP 엔드포인트를 노출하고, Claude 측에서 SSE URL로 연결하도록 설정한다.
프로젝트 설정 공유
팀 프로젝트에서는 .claude/mcp.json을 Git 저장소에 포함시키되, 민감한 정보는 환경 변수로 분리한다.
{
"mcpServers": {
"project-db": {
"command": "npx",
"args": ["-y", "@myorg/mcp-db-server"],
"env": {
"DB_CONNECTION_STRING": "${DB_CONNECTION_STRING}"
}
}
}
}팀원들은 각자의 로컬 환경에서 DB_CONNECTION_STRING 환경 변수를 설정하면 된다. 이렇게 하면 설정 파일은 공유하면서도 자격 증명은 각자가 관리할 수 있다.
전역 설정과 프로젝트 설정
Claude Code에서 MCP 서버는 두 가지 범위로 등록할 수 있다.
- 프로젝트 범위:
.claude/mcp.json에 등록. 해당 프로젝트 디렉토리에서 Claude Code를 실행할 때만 활성화된다. - 전역 범위:
~/.claude/mcp.json에 등록. 모든 프로젝트에서 사용할 수 있다.
프로젝트에 특화된 도구는 프로젝트 범위에, 범용 도구(날씨 조회, 번역 등)는 전역 범위에 등록하는 것을 권장한다.
자주 묻는 질문
MCP 서버를 만들려면 어떤 언어를 사용해야 하나요?
공식 SDK가 제공되는 TypeScript와 Python이 가장 권장된다. TypeScript SDK(@modelcontextprotocol/sdk)는 가장 성숙하고 사용 사례가 많다. Python SDK(mcp)는 FastMCP라는 고수준 API를 제공하여 빠른 프로토타이핑에 유리하다. Go, Rust, Java 등 다른 언어용 커뮤니티 SDK도 존재한다.
MCP 서버 하나에 도구를 몇 개까지 등록할 수 있나요?
기술적 제한은 없지만, 관련된 도구를 하나의 서버에 묶고, 서로 다른 도메인의 도구는 별도 서버로 분리하는 것이 좋다. 예를 들어 데이터베이스 관련 도구는 하나의 서버에, GitHub 관련 도구는 별도 서버에 두는 방식이다. 도구가 너무 많으면 Claude가 적절한 도구를 선택하는 데 혼란을 겪을 수 있다.
MCP 서버가 원격에서 실행될 수 있나요?
가능하다. SSE 전송을 사용하면 MCP 서버를 원격 서버나 클라우드에 배포할 수 있다. 이 경우 인증과 네트워크 보안에 추가적인 주의가 필요하다. Streamable HTTP 전송도 최신 사양에 추가되어 더 유연한 원격 배포가 가능해졌다.
기존 REST API를 MCP 서버로 감싸는 것이 의미가 있나요?
매우 유용하다. Claude가 직접 HTTP 요청을 보낼 수는 없으므로, MCP 서버가 중간 계층 역할을 한다. 인증 처리, 응답 포맷팅, 오류 처리를 MCP 서버에서 담당하면 Claude가 깔끔한 인터페이스로 API를 활용할 수 있다.
Claude Code와 Claude Desktop에서 같은 MCP 서버를 사용할 수 있나요?
가능하다. MCP 서버는 프로토콜 수준에서 표준화되어 있으므로 동일한 서버 바이너리를 양쪽에서 사용할 수 있다. 다만 설정 파일의 위치와 형식이 다르므로 각 클라이언트에 맞게 설정을 작성해야 한다.
MCP 서버의 도구 호출 시 사용자 승인이 필요한가요?
Claude Code에서는 기본적으로 MCP 도구 호출 전에 사용자 확인을 요청한다. 특정 도구를 자동 승인하려면 설정에서 allowedTools 목록에 추가하면 된다. Claude Desktop에서도 첫 호출 시 승인 팝업이 표시되며, 세션 동안 기억하도록 설정할 수 있다.
MCP 서버에서 상태를 유지할 수 있나요?
MCP 서버는 프로세스가 살아 있는 동안 메모리에 상태를 유지할 수 있다. 데이터베이스 커넥션 풀, 캐시, 세션 정보 등을 서버 인스턴스 수준에서 관리할 수 있다. 다만 서버가 재시작되면 상태가 초기화되므로, 영속적인 상태는 외부 저장소에 보관해야 한다.
프로덕션 환경에서 MCP 서버의 안정성을 어떻게 보장하나요?
에러 핸들링을 철저히 구현하고, 모든 외부 호출에 타임아웃을 설정한다. 구조화된 로깅을 통해 문제를 빠르게 진단할 수 있도록 한다. 도구 핸들러에서 예외가 발생하더라도 서버 프로세스 자체가 종료되지 않도록 try-catch로 감싸는 것이 중요하다. MCP SDK가 프로토콜 수준의 에러 처리를 담당하므로, 개발자는 비즈니스 로직의 에러 처리에 집중하면 된다.