2026. 6. 29. 13:49ㆍAI코딩
MCP(Model Context Protocol) 사용법 완전 가이드 — 7년차 백엔드 개발자의 실전 후기
MCP란 무엇인가?
MCP(Model Context Protocol)는 AI 애플리케이션과 외부 도구·데이터를 연결하는 개방형 표준 프로토콜입니다. 2024년 11월 Anthropic이 발표했고, 현재는 오픈소스 커뮤니티와 Linux Foundation 산하 에이전틱 AI 재단이 공동 관리하는 벤더 중립 표준으로 자리잡았습니다.
쉽게 말하면 이렇습니다. AI 모델은 기본적으로 학습된 지식 안에 갇혀 있습니다. 내 DB를 직접 조회하거나, Notion 페이지를 읽거나, GitHub PR을 가져오려면 매번 사람이 복사해서 붙여넣어야 했습니다. MCP는 이 연결 과정을 표준화해서, AI가 외부 시스템에 직접 접근하게 만들어주는 "공통 규격"입니다.
공식 문서의 비유를 그대로 빌리면, "AI용 USB-C 포트" 입니다. USB-C 하나로 모니터·충전기·외장 드라이브를 연결하듯, MCP 하나로 파일 시스템·데이터베이스·Slack·GitHub를 AI에 연결할 수 있습니다.
이 글은 7년차 백엔드 개발자인 제가 실제로 MCP 서버를 Claude Code에 연결해 운영하면서 정리한 실사용 가이드입니다. 개념 설명에 그치지 않고, 직접 연결한 설정 코드와 겪은 함정까지 담았습니다.
MCP가 왜 지금 중요한가?
기존 AI 도구 연동 방식은 제각각이었습니다. 서비스마다 별도 플러그인·API·프롬프트 엔지니어링이 필요했고, 구현 방식이 달라 재사용이 어려웠습니다.
MCP는 이 문제를 표준으로 해결합니다. 한번 MCP 서버로 만들어두면, Claude Desktop·Cursor·VS Code·Claude Code 어디서든 동일한 서버를 재사용할 수 있습니다. 생태계 규모를 보면 현실감이 옵니다.
- SDK 월간 다운로드: 2026년 3월 기준 Python·TypeScript SDK 합산 9,700만 회/월 (런칭 시점 약 200만 회 대비 급성장)
- 공개 MCP 서버: 여러 레지스트리 합산 1만 개 이상(2026년 기준, 집계처마다 상이)
- 지원 클라이언트: Claude, ChatGPT, VS Code, Cursor 등 주요 AI 코딩 도구 다수가 지원(클라이언트별 지원 범위·전제 상이)
2025년 12월, Anthropic은 MCP를 Linux Foundation 산하 에이전틱 AI 재단에 기증했습니다. 단일 기업 소유에서 커뮤니티 거버넌스로 전환한 것으로, 장기적 표준 지위를 노린 결정입니다.
MCP 아키텍처는 어떻게 구성되는가?
MCP는 세 참여자가 역할을 나눕니다.
| 참여자 | 역할 | 예시 |
|---|---|---|
| MCP 호스트(Host) | MCP 클라이언트를 관리하는 AI 애플리케이션 | Claude Desktop, Claude Code, Cursor, VS Code |
| MCP 클라이언트(Client) | 호스트가 생성·관리하는 연결 단위. 서버 1개당 클라이언트 1개 | (호스트 내부에서 자동 생성) |
| MCP 서버(Server) | 실제 도구·데이터를 AI에게 제공하는 프로그램 | filesystem 서버, GitHub 서버, PostgreSQL 서버 |
호스트가 여러 서버에 동시 연결할 수 있고, 각 연결은 독립된 클라이언트 객체로 관리됩니다. Claude Code에서 filesystem 서버와 GitHub 서버를 동시에 연결하면, 내부적으로 클라이언트 2개가 각각 전용 연결을 유지합니다.
두 가지 통신 방식(트랜스포트)
Stdio 트랜스포트 — 로컬 프로세스 간 표준 입출력으로 통신합니다. 네트워크 오버헤드 없이 동일 머신에서만 작동하며, 파일 시스템·DB 서버처럼 로컬 자원에 접근할 때 씁니다.
Streamable HTTP 트랜스포트 — HTTP POST로 요청을 보내고, 선택적으로 SSE(Server-Sent Events)로 스트리밍을 받습니다. 원격 서버 연결에 사용하며, Bearer 토큰·API 키·OAuth 2.0 인증을 지원합니다. Sentry, Notion, GitHub 같은 클라우드 서비스 서버가 이 방식입니다.
⚠️ 이전에 쓰이던 SSE 단독 트랜스포트는 공식 문서 기준으로 deprecated 상태입니다. 새로 설정한다면 Streamable HTTP를 쓰는 게 맞습니다.
MCP 서버가 제공하는 세 가지 기본 기능(Primitive)
서버가 클라이언트에게 줄 수 있는 것은 세 종류입니다.
- Tools(도구): AI가 호출해서 실행하는 함수. 파일 읽기·DB 쿼리·API 호출 등 "액션"을 담당합니다.
- Resources(리소스): AI에게 컨텍스트로 제공하는 데이터. 파일 내용·DB 레코드·API 응답 등 "읽기 전용 정보"입니다.
- Prompts(프롬프트): 미리 정의한 프롬프트 템플릿. 자주 쓰는 지시 형식을 재사용합니다.
통신 프로토콜은 JSON-RPC 2.0 기반이고, 연결 시작 시 클라이언트·서버가 서로 지원 기능을 협의(capability negotiation)합니다.
MCP를 어디에 연결할 수 있는가?
MCP는 클라이언트마다 설정 방식이 조금씩 다릅니다. 지원 클라이언트는 계속 늘고 있으며, 2026년 기준 주요 AI 코딩 도구 다수가 지원합니다.
Claude Code 사용법 완전 가이드나 Cursor MCP 설정 가이드도 함께 읽으면 클라이언트별 차이를 빠르게 파악할 수 있습니다.
| 클라이언트 | MCP 지원 | 설정 방법 | 비고 |
|---|---|---|---|
| Claude Desktop | ✅ | JSON 설정 파일 편집 후 재시작 | macOS/Windows |
| Claude Code | ✅ | claude mcp add 명령어 |
CLI 기반, 글로벌/프로젝트/로컬 범위 |
| Cursor | ✅ | Settings → Tools & MCP | 설정 변경 시 자동 반영(재시작 불필요) |
| VS Code | ✅ | MCP 설정 파일 | Copilot Chat과 통합 |
| ChatGPT | ✅ | 원격 MCP 서버 연결 | Developer Mode(베타) 필요 · 유료 플랜(Pro/Plus/Business/Enterprise/Edu) 한정 · 웹 전용 |
Claude Desktop에 MCP 서버를 연결하는 방법
Claude Desktop은 설정 파일에 서버 목록을 JSON으로 작성합니다.
설정 파일 위치
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
filesystem 서버 추가 예시
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/yourname/Documents"
]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
}
}
}
}설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 재시작해야 반영됩니다. 앱을 재시작하면 입력창 하단에 도구 아이콘이 추가된 것을 확인할 수 있습니다.
✅ Node.js가 설치돼 있어야
npx기반 서버가 동작합니다. Python 서버는uvx또는pip install후 실행합니다.
Claude Code에 MCP 서버를 연결하는 방법
Claude Code는 claude mcp add 명령어로 터미널에서 직접 관리합니다. 설정 파일을 수동 편집할 필요 없이 CLI만으로 추가·확인·제거가 가능합니다.
원격 HTTP 서버 추가
# 기본 형식
claude mcp add --transport http <서버명> <URL>
# Notion 연결 예시
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Bearer 토큰 인증이 필요한 경우
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"로컬 Stdio 서버 추가
# PostgreSQL 읽기 전용 연결
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@localhost:5432/mydb"
# 파일 시스템 서버
claude mcp add --transport stdio filesystem -- npx -y \
@modelcontextprotocol/server-filesystem /path/to/allowed/dir설치 범위(scope) 선택
Claude Code는 서버를 세 범위 중 하나에 저장합니다.
# 로컬(기본): 현재 프로젝트, 나만 사용
claude mcp add --scope local --transport http sentry https://mcp.sentry.dev/mcp
# 프로젝트: 현재 프로젝트, 팀 전체 공유 (.mcp.json에 저장, git에 커밋 가능)
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_PAT"
# 사용자: 모든 프로젝트에서 나만 사용
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp서버 관리 명령어
# 등록된 서버 목록 확인
claude mcp list
# 특정 서버 상세 정보
claude mcp get github
# 서버 제거
claude mcp remove github
# 세션 내 서버 상태 확인 (Claude Code 안에서)
/mcpOAuth 인증이 필요한 원격 서버(Sentry, Notion 등)는 서버 추가 후 /mcp 명령으로 브라우저 로그인 흐름을 완료합니다. 인증 토큰은 시스템 키체인에 안전하게 저장되고 자동으로 갱신됩니다.
주요 MCP 서버 목록 — 어떤 것들이 있는가?
공식 레퍼런스 서버와 대표적인 서드파티 서버를 정리했습니다. 제공처 컬럼에 "아카이브" 표기는 modelcontextprotocol/servers 저장소 기준(2025-05-29)이며, 현재는 별도 대체 서버로 이관된 상태입니다.
| 서버 | 제공 기능 | 설치 | 제공처 |
|---|---|---|---|
| filesystem | 로컬 파일 읽기·쓰기·검색 (접근 경로 화이트리스트) | npx @modelcontextprotocol/server-filesystem |
공식 레퍼런스 |
| git | Git 저장소 읽기·검색·조작 | uvx mcp-server-git (Python) |
공식 레퍼런스 |
| fetch | 웹 페이지 내용 가져오기·변환 | uvx mcp-server-fetch (Python) |
공식 레퍼런스 |
| memory | 지식 그래프 기반 영속 메모리 | npx @modelcontextprotocol/server-memory |
공식 레퍼런스 |
| GitHub | PR 조회·이슈 관리·코드 검색 | 원격 HTTP (api.githubcopilot.com/mcp/) |
서드파티 (구 공식, 현재 아카이브 → github-mcp-server로 대체) |
| PostgreSQL | DB 읽기 전용 조회·스키마 검사 | npx @bytebase/dbhub |
서드파티 (구 공식, 현재 아카이브 → @bytebase/dbhub로 대체) |
| Sentry | 오류 추적·스택 트레이스 조회 | 원격 HTTP (mcp.sentry.dev/mcp) |
서드파티 |
| Notion | 페이지·DB 읽기·쓰기 | 원격 HTTP (mcp.notion.com/mcp) |
서드파티 |
| Slack | 채널 조회·메시지 전송 | 원격 HTTP | 서드파티 |
공식 레지스트리(registry.modelcontextprotocol.io)에서 검증된 서버를 탐색할 수 있고, GitHub의 modelcontextprotocol/servers 저장소와 커뮤니티 awesome-mcp-servers 목록에서도 다양한 서버를 찾을 수 있습니다.
MCP 서버를 직접 만들 수 있는가?
만들 수 있습니다. TypeScript와 Python SDK가 공식 제공됩니다.
// TypeScript 기반 간단한 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-server", version: "1.0.0" });
// 도구(tool) 등록
server.tool(
"get_stock_price",
{ ticker: z.string() },
async ({ ticker }) => ({
content: [{ type: "text", text: `${ticker}: $150.00 (예시)` }]
})
);
const transport = new StdioServerTransport();
await server.connect(transport);Claude Code 안에서도 서버 스캐폴딩 도구를 제공합니다.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install mcp-server-dev
/mcp-server-dev:build-mcp-server이 명령을 실행하면 Claude가 사용 사례를 물어보고, 로컬 stdio 또는 원격 HTTP 서버 중 어떤 방식으로 만들지 선택해 기본 골격을 자동 생성합니다. 개발 시 MCP Inspector(github.com/modelcontextprotocol/inspector)로 서버를 로컬에서 테스트할 수 있습니다.
공식 빌드 가이드는 modelcontextprotocol.io/docs/develop/build-server에 있습니다.
실전 사례: 내가 직접 Claude Code에 연결해서 쓰는 MCP 서버들
말로만 설명하면 실감이 없습니다. 제가 실제로 연결해서 운영하는 서버와 경험을 공유합니다.
PostgreSQL 서버 — "DB 스키마 물어보기가 이렇게 편해질 줄은"
현재 운영하는 사이드 프로젝트의 PostgreSQL에 읽기 전용 연결을 붙였습니다.
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@localhost:5433/openclaw"연결하고 나서 달라진 점은 명확합니다. "conversations 테이블에 user_id 컬럼이 있어?" 같은 질문을 Claude에게 바로 할 수 있습니다. 이전에는 psql 터미널 열고 \d conversations 치고 결과 복사해서 붙여넣는 과정이 있었는데, 그게 사라졌습니다.
실패 경험도 있습니다. 처음에 읽기 전용 계정이 아닌 관리자 계정으로 연결했다가 Claude가 "이 테이블을 DROP해도 될까요?" 라고 물어보는 상황이 생겼습니다. 다행히 제가 거절했지만, 이후 읽기 전용 계정으로 바꿨습니다. 연결 계정은 무조건 최소 권한으로 설정하는 게 맞습니다.
GitHub 서버 — "PR 컨텍스트 복사·붙여넣기 없어짐"
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer ghp_xxxx"코드 리뷰를 할 때 PR 내용을 Claude에 설명하는 과정이 있었습니다. MCP 연결 후에는 "PR #42 리뷰해줘"만 치면 됩니다. Claude가 직접 PR을 열어 diff와 코멘트를 읽습니다.
✅ 잘 작동한 것: 이슈·PR 조회, 변경사항 설명 요청.
⚠️ 주의할 점: GitHub PAT는 저장소 범위를 좁게 설정할 것. 전체 접근 토큰은 위험합니다.
filesystem 서버 — "설정 파일 읽기용으로만 제한적으로"
claude mcp add --transport stdio docs-fs -- npx -y \
@modelcontextprotocol/server-filesystem /Users/me/Documents/project-docs프로젝트 문서 디렉토리만 접근 가능하게 경로를 제한했습니다. filesystem 서버는 경로 화이트리스트를 인수로 받으므로, 전체 홈 디렉토리가 아닌 특정 폴더만 열어주는 게 안전합니다.
MCP 실전 팁과 함정
잘 작동하는 패턴
✅ 읽기 전용 계정으로 연결합니다: DB·파일 시스템 서버는 AI가 Write 작업을 시도할 수 있습니다. 읽기 전용 계정 또는 경로 제한으로 범위를 줄이는 게 기본입니다.
✅ 프로젝트 범위 서버는 .mcp.json에 커밋합니다: 팀원이 같은 서버를 쓰도록 .mcp.json을 git에 포함시킵니다. API 키 같은 민감 정보는 환경 변수로 분리하고 .gitignore 처리합니다.
✅ Claude Code에서 /mcp로 연결 상태를 확인합니다: 서버별 도구 개수와 연결 상태가 한눈에 보입니다. 문제가 생겼을 때 먼저 여기부터 확인합니다.
실제로 겪은 함정들
⚠️ 서버 추가 후 Claude Desktop은 재시작이 필요합니다: Claude Code는 변경 사항이 바로 반영되지만, Claude Desktop은 설정 파일 수정 후 앱을 완전히 종료하고 재시작해야 합니다. 재시작 안 하고 "왜 안 되지?" 하는 경우가 많습니다.
⚠️ 프롬프트 주입 위험이 있습니다: 외부 콘텐츠를 가져오는 서버(웹 fetch, 이슈 트래커 등)는 악의적으로 조작된 콘텐츠가 AI에 주입될 수 있습니다. 공식 문서도 이를 명시적으로 경고합니다. 신뢰할 수 있는 서버만 연결하고, 연결 전 서버 코드나 출처를 확인하는 습관이 필요합니다.
⚠️ Cursor는 도구 수가 많아지면 정확도가 떨어집니다: 약 40개 수준에서 도구 선택 정확도가 떨어진다는 커뮤니티 보고가 많습니다(공식 명문 수치 아님, 버전에 따라 다름). 서버를 여러 개 붙일 때는 실제로 쓰는 서버만 활성화하는 게 낫습니다.
⚠️ 로컬 서버는 Node.js나 Python이 필요합니다: npx 기반 서버는 Node.js, uvx 기반은 Python(+uv)이 설치돼 있어야 합니다. 환경이 없으면 서버가 시작되지 않으며 에러 메시지가 명확하지 않을 때도 있습니다.
자주 묻는 질문 (FAQ)
Q. MCP와 기존 AI 플러그인(ChatGPT 플러그인 등)의 차이는?
ChatGPT 플러그인은 OpenAI 생태계에 종속된 독점 방식이었습니다. MCP는 특정 AI 제공사에 종속되지 않는 개방형 표준입니다. 한 번 MCP 서버로 만들면 Claude, ChatGPT, Cursor, VS Code 등 어디서든 재사용할 수 있습니다. 생태계 측면에서 근본적으로 다릅니다.
Q. MCP 서버를 연결하면 내 데이터가 Anthropic 서버로 전송되나요?
로컬 Stdio 서버(filesystem, 로컬 DB 등)의 경우, 서버 자체는 내 머신에서 실행됩니다. AI 모델이 도구를 호출할 때 결과가 Claude에 전달되는 구조이므로, 해당 결과 내용은 AI 처리 과정에 포함됩니다. 민감한 데이터가 있는 서버를 연결할 때는 이 점을 고려해야 합니다. 원격 MCP 서버의 경우 해당 서비스의 개인정보 처리방침을 확인하는 게 맞습니다.
Q. MCP를 쓰려면 코딩을 알아야 하나요?
기존에 만들어진 서버를 연결하는 수준이라면 터미널 기본 명령어와 JSON 파일 편집 정도면 됩니다. 직접 서버를 만들려면 TypeScript나 Python 기본기가 필요합니다. Claude Code를 쓰고 있다면 플러그인 마켓에서 mcp-server-dev를 설치한 뒤 /mcp-server-dev:build-mcp-server 스캐폴딩 도구가 기본 구조를 잡아줍니다.
마무리
MCP는 "AI에게 도구를 주는" 표준입니다. 플러그인처럼 특정 플랫폼에 갇히지 않고, 한 번 만든 서버를 여러 AI 클라이언트에서 재사용할 수 있다는 점이 핵심입니다.
저는 PostgreSQL과 GitHub 서버를 Claude Code에 연결해서 쓰고 있는데, 체감 차이는 분명합니다. DB 스키마 확인, PR 컨텍스트 이해, 이슈 내용 파악에서 "복사·붙여넣기"가 사라졌습니다. 작아 보이지만 반복되는 마찰이 없어지면 흐름이 달라집니다.
다만 주의할 것도 있습니다. 연결 계정 권한 최소화, 신뢰할 수 없는 서버 연결 지양, 프롬프트 주입 위험 인지 — 이 세 가지는 운영하면서 직접 경험하고 배운 기준입니다.
MCP 생태계는 현재도 빠르게 성장 중입니다. 서버 품질도 천차만별이라, 처음에는 공식 레지스트리(registry.modelcontextprotocol.io)에서 검증된 서버부터 시작하는 게 안전합니다.
다음 글에서는 MCP 서버를 직접 만드는 구체적인 방법을 다룹니다.
출처
- MCP 공식 문서 — What is MCP? — 2026년 6월 확인
- MCP 아키텍처 공식 문서 — 2026년 6월 확인
- MCP 레퍼런스 서버 목록 — 2026년 6월 확인
- Claude Code MCP 연결 공식 가이드 (한국어) — 2026년 6월 확인
- 2026 MCP 로드맵 — MCP 공식 블로그 — 2026년 6월 확인
- MCP 공식 서버 레지스트리 — 2026년 6월 확인
- MCP 97M 다운로드 생태계 현황 — Effloow — 2026년 6월 확인 (집계 출처: 2차 블로그, 1차 출처는 Anthropic 발표 기준)
- MCP 2026 채택 통계 — Digital Applied — 2026년 6월 확인 (집계 출처: 2차 블로그)
- Claude Code에서 MCP 서버 연동하기 — Dale Seo — 2026년 6월 확인
관련 글
- Claude Code 사용법 완전 가이드
- Cursor MCP 설정 가이드
- (예정) MCP 서버 직접 만들기 — TypeScript SDK 실전
- (예정) Claude Code CLAUDE.md 활용 가이드
'AI코딩' 카테고리의 다른 글
| 커서(Cursor) 사용법 완벽 가이드 — 설치부터 실전 활용까지 (0) | 2026.06.26 |
|---|---|
| 클로드코드(Claude Code) 완벽 가이드 — 7년차 백엔드 개발자의 실사용 후기와 활용법 (0) | 2026.06.26 |