Model Context Protocol의 개념을 이해하고, Claude Code에 MCP 서버를 연결하여 데이터베이스, API, 외부 서비스를 통합하는 방법을 다룹니다.
MCP(Model Context Protocol)는 Anthropic이 개발한 AI 모델과 외부 도구 간의 연결 표준입니다. AI 모델이 데이터베이스, API, 파일 시스템, 클라우드 서비스 등 다양한 외부 시스템과 상호작용할 수 있도록 하는 개방형 프로토콜입니다.
Claude Code가 기본적으로 제공하는 도구(파일 읽기/쓰기, 셸 실행, 웹 검색 등)만으로도 많은 작업을 수행할 수 있습니다. 하지만 프로젝트의 Jira 이슈를 가져와 구현하거나, 모니터링 대시보드의 에러를 분석하거나, 데이터베이스 스키마를 직접 조회하는 것은 기본 도구만으로는 비효율적입니다. MCP 서버를 연결하면 이러한 작업을 자연어 명령 하나로 처리할 수 있습니다.
MCP는 클라이언트-서버 아키텍처로 동작합니다. Claude Code가 MCP 클라이언트 역할을 하고, 각 외부 서비스에 대응하는 MCP 서버가 실제 통신을 처리합니다.
MCP 서버: 특정 서비스(GitHub, PostgreSQL 등)와의 통신을 담당하는 프로세스입니다. 도구(Tools), 리소스(Resources), 프롬프트(Prompts)를 노출합니다.
도구(Tools): MCP 서버가 제공하는 실행 가능한 함수입니다. 예를 들어 GitHub MCP 서버는 create_issue, list_pull_requests, merge_pr 같은 도구를 제공합니다.
리소스(Resources): 읽기 전용 데이터 소스입니다. 파일 내용, 데이터베이스 레코드, API 응답 등이 해당합니다.
도구 검색(Tool Search): Claude Code는 연결된 MCP 서버의 모든 도구를 세션 시작 시 로드하지 않습니다. 도구 이름만 먼저 로드하고, Claude가 필요하다고 판단할 때 전체 스키마를 가져옵니다. 이를 통해 많은 MCP 서버를 연결해도 컨텍스트 윈도우를 낭비하지 않습니다.
MCP 서버는 .claude/settings.json 또는 ~/.claude/settings.json에 설정합니다.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}| 필드 | 설명 |
|---|---|
command | MCP 서버를 실행하는 명령어 |
args | 명령어 인자 |
env | 환경 변수 (토큰, 인증 정보 등) |
cwd | 작업 디렉토리 (선택) |
${GITHUB_TOKEN}과 같이 환경 변수를 참조하면, 실제 토큰 값을 설정 파일에 직접 노출하지 않을 수 있습니다.
MCP 서버에 전달하는 토큰과 인증 정보는 환경 변수로 관리하고, 설정 파일에 직접 하드코딩하지 않습니다. 프로젝트 설정 파일(.claude/settings.json)에 토큰이 포함되면 Git을 통해 노출될 위험이 있습니다.
가장 널리 사용되는 MCP 서버 중 하나입니다. 이슈 관리, PR 생성, 코드 리뷰 등을 Claude Code 세션 내에서 직접 수행할 수 있습니다.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}설정 후 Claude Code에서 다음과 같이 활용합니다.
이 리포지토리의 열린 이슈 중 bug 라벨이 붙은 것들을 가져와서
가장 최근 이슈부터 처리해 줘
현재 브랜치의 변경사항으로 PR을 생성해 줘.
제목과 설명은 변경 내용에 맞게 자동으로 작성해 줘.
데이터베이스 스키마를 조회하고, 쿼리를 실행할 수 있습니다.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}users 테이블의 스키마를 보여주고,
최근 7일간 가입한 사용자 수를 쿼리해 줘
데이터베이스 MCP 서버를 프로덕션 환경에 연결할 때는 읽기 전용 계정을 사용하는 것을 강력히 권장합니다. Claude Code가 DELETE나 DROP 쿼리를 실행할 가능성을 원천 차단할 수 있습니다.
특정 디렉토리에 대한 세밀한 접근 제어가 필요할 때 사용합니다.
{
"mcpServers": {
"docs": {
"command": "npx",
"args": [
"-y", "@modelcontextprotocol/server-filesystem",
"/path/to/docs"
]
}
}
}Slack 채널의 메시지를 읽거나 보내는 것이 가능합니다.
{
"mcpServers": {
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
}
}
}
}#dev-alerts 채널의 최근 에러 알림을 확인하고
해당 에러를 수정해 줘
여러 MCP 서버를 동시에 연결하면 서비스 간 연계 작업이 가능해집니다.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
}
}
}
}이 구성에서는 다음과 같은 복합 작업이 가능합니다.
GitHub에서 #123 이슈를 가져와서 구현해 줘.
DB 스키마를 확인하고 필요한 마이그레이션을 작성한 뒤,
PR을 생성하고 #dev 채널에 알림을 보내 줘.
기존 MCP 서버가 없는 내부 시스템이나 독자적인 API와 연동해야 할 때는 커스텀 MCP 서버를 개발할 수 있습니다.
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-internal-api",
version: "1.0.0",
});
// 도구 정의
server.tool(
"get_deployments",
"최근 배포 목록을 조회합니다",
{
environment: z.enum(["production", "staging", "dev"])
.describe("배포 환경"),
limit: z.number().default(10)
.describe("조회할 배포 수"),
},
async ({ environment, limit }) => {
const response = await fetch(
`https://internal-api.company.com/deployments?env=${environment}&limit=${limit}`,
{
headers: {
Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
},
}
);
const data = await response.json();
return {
content: [
{
type: "text",
text: JSON.stringify(data, null, 2),
},
],
};
}
);
// 서버 시작
const transport = new StdioServerTransport();
server.connect(transport);{
"mcpServers": {
"internal-api": {
"command": "npx",
"args": ["tsx", "./my-mcp-server/index.ts"],
"env": {
"INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}"
}
}
}
}도구 설명을 명확하게 작성합니다: Claude는 도구 설명을 기반으로 어떤 도구를 사용할지 결정합니다. "배포 조회"보다 "특정 환경의 최근 배포 목록을 시간순으로 조회합니다"가 더 효과적입니다.
입력 스키마를 구체적으로 정의합니다: Zod 스키마에 .describe()를 사용하여 각 파라미터의 용도를 설명합니다.
에러 처리를 철저히 합니다: MCP 서버의 에러는 Claude의 컨텍스트에 반영되므로, 명확한 에러 메시지를 반환해야 Claude가 적절히 대응할 수 있습니다.
응답 크기를 제한합니다: 대량의 데이터를 반환하면 컨텍스트 윈도우를 낭비합니다. 페이지네이션을 지원하거나 결과를 요약하여 반환합니다.
Claude Code 세션에서 연결된 MCP 서버 상태를 확인할 수 있습니다.
현재 연결된 MCP 서버 목록과 사용 가능한 도구를 보여줘
서버가 시작되지 않는 경우: command와 args의 경로가 올바른지, 필요한 패키지가 설치되어 있는지 확인합니다.
인증 실패: 환경 변수가 올바르게 설정되어 있는지, 토큰이 만료되지 않았는지 확인합니다.
타임아웃: 네트워크 연결을 확인하고, 서버의 응답 시간이 적절한지 확인합니다.
MCP는 Claude Code의 기능을 외부 시스템으로 확장하는 핵심 프로토콜입니다.
settings.json에서 mcpServers 필드로 설정하며, 환경 변수로 인증 정보를 관리합니다다음 장에서는 Claude Code의 병렬 처리 능력인 서브에이전트와 에이전트 팀을 살펴봅니다.
이 글이 도움이 되셨나요?
Claude Code의 서브에이전트와 에이전트 팀 기능을 이해하고, 복잡한 작업을 병렬로 분할 처리하는 방법을 다룹니다.
Claude Code의 스킬 시스템을 이해하고, 반복 작업을 자동화하는 커스텀 슬래시 명령어를 설계하고 구현하는 방법을 다룹니다.
Claude Code를 Git 워크플로우에 통합하고, CI/CD 파이프라인에서 자동화된 코드 리뷰와 수정을 구성하는 방법을 다룹니다.