오늘만 무료

Claude Code MCP 완전 입문

MCP 아키텍처 이해와 claude mcp add 실전 활용법

Mar 22. 2026 brunch_membership's

배경 지식

MCP란 무엇인가

MCP(Model Context Protocol)는 AI 어시스턴트가 외부의 툴이나 데이터 소스에 접속하기 위한 표준 프로토콜입니다. 기존에 AI 모델이 외부 서비스와 연계하려면 서비스마다 개별 API 통합이나 플러그인 개발이 필요했습니다. MCP는 이 과제를 해결하여, 통일된 인터페이스로 다양한 외부 서비스로의 접속을 가능하게 합니다.

공식 문서에서는 MCP를 "Claude Code의 능력을 확장하기 위한 구조"로 자리매김하고 있습니다.

※ 한국 개발 환경에서의 MCP 활용 배경
GitHub, Jira, Confluence, Slack, AWS 등 현재 한국 개발 팀이 사용하는 대부분의 서비스가 MCP 서버를 통해 Claude Code와 연계될 수 있습니다. 1장(Skills)에서 배운 자동화 절차에 실제 외부 서비스 데이터를 조합하면, 훨씬 강력한 개발 워크플로우를 구축할 수 있습니다.

MCP의 아키텍처

MCP는 클라이언트·서버 모델로 동작합니다.

왜 MCP가 필요한가

스코프의 이해

MCP 서버를 등록할 때 지정하는 스코프는, 설정이 어느 범위에 적용되는지를 결정합니다.

※ 팀 공유 관점
--scope project로 등록된 MCP 서버 설정은 .mcp.json에 저장됩니다. 이 파일을 Git으로 관리하면 팀 멤버 전원이 git pull만으로 같은 MCP 환경을 사용할 수 있습니다. 1장에서 .claude/skills/를 Git 관리한 것과 같은 접근 방식입니다.

대표적인 유스케이스

파일 시스템 접속: 로컬 파일의 읽기·쓰기·검색을 MCP 경유로 실행

GitHub 연계: 리포지토리 조작, Issue 관리, PR 작성을 Claude Code에서 직접 실행

데이터베이스 접속: SQLite나 PostgreSQL로의 쿼리 실행

API 연계: REST API나 GraphQL API로의 접속

개발 툴 통합: ESLint, Jest 등 린터·테스트 러너의 통합

협업 툴 연계: Slack, Jira, Confluence, Notion 등과의 연결

"외부 서비스 통합 워크스페이스"의 전체 구조

2부 전 9회를 통해, 다음의 통합 워크스페이스를 단계적으로 구축합니다.

외부 서비스 통합 워크스페이스

├── filesystem MCP ← 2부 1장에서 접속

├── GitHub MCP ← 2부 3장에서 추가

├── 인증 설정 ← 2부 4장에서 API 키 / OAuth 관리

├── claude mcp serve ← 2부 6장에서 서버화

└── 통합 환경 ← 2부 9장에서 완성

따라하기

1단계: 프로젝트 디렉토리 준비

먼저 "외부 서비스 통합 워크스페이스"용 프로젝트 디렉토리를 작성합니다.

mkdir -p ~/mcp-workspace
cd ~/mcp-workspace
git init
echo "# MCP 통합 워크스페이스" > README.md
git add README.md
git commit -m "Initial commit: MCP 통합 워크스페이스"

디렉토리 구성을 정돈합니다.

mkdir -p src docs config
touch src/.gitkeep docs/.gitkeep config/.gitkeep

※ 커밋 메시지 규칙
1장에서 배운 Conventional Commits 규칙(feat:, docs: 등)을 MCP 관련 작업에도 일관되게 적용하면 이력 추적이 쉬워집니다.

2단계: 현재 MCP 접속 상황 확인

Claude Code에서 현재 등록된 MCP 서버의 목록을 확인합니다.

claude mcp list

기대되는 출력 (초기 상태인 경우):

No MCP servers configured. Use `claude mcp add` to add a server.

이미 무언가 등록되어 있는 경우는 그 목록이 표시됩니다. 현재 상황을 파악해두세요.

3단계: filesystem MCP 서버를 추가한다

최초의 MCP 서버로서, Node.js기반의 filesystem MCP 서버를 등록합니다. 이 서버는 로컬 파일 시스템으로의 접근을 제공합니다.

claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem $PWD

각 옵션의 의미:

--transport stdio: 표준 입출력으로 서버와 통신한다

--scope project: 프로젝트 스코프로 등록 (이 프로젝트 내에서만 유효)

filesystem: 서버의 이름 (임의의 식별자)

--: 옵션과 커맨드의 구분자

npx -y @modelcontextprotocol/server-filesystem: 기동 커맨드

$PWD: 서버에 전달하는 인수 (현재 디렉토리 = 접근 허가하는 디렉토리)

기대되는 출력:

Added stdio MCP server "filesystem" with command: npx -y @modelcontextprotocol/server-filesystem /Users/yourname/mcp-workspace

등록 후, .mcp.json 파일이 생성되어 있는지 확인합니다.

cat .mcp.json

기대되는 출력:

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/yourname/mcp-workspace"
]
}
}
}

※ 팀 공유 포인트
.mcp.json을 Git에 커밋하면 팀 멤버 전원이 같은 MCP 환경을 사용할 수 있습니다. 단, 절대 경로($PWD로 전달된 값)가 포함되어 있으므로, 팀 멤버별로 경로가 다른 경우는 상대 경로나 환경 변수로 치환하는 방법을 검토하세요.

4단계: MCP 서버를 사용해본다

--scope project로 등록한 서버는 .mcp.json 파일에 저장됩니다. 이 파일은 대화 모드 시작 시에 읽어 들여지고, 승인을 거쳐 유효화됩니다.

Claude Code의 대화 모드를 시작합니다.

claude

시작 시에 .mcp.json의 서버를 유효화할지 확인됩니다. 승인하면 filesystem MCP 서버가 접속됩니다.

여기서는 프로젝트 스코프에서 사용하기 위해 2번을 선택합니다.

먼저 /mcp로 접속 상태를 확인합니다.

> /mcp

접속 중인 MCP 서버의 상태나 툴 목록이 표시됩니다. 이것은 1장에서 배운 슬래시 커맨드의 지식이 활용되는 장면입니다.

이어서, filesystem MCP 서버가 제공하는 툴을 사용해봅니다. (MCP 확인을 종료할 때는 ESC 키를 눌러 대화 모드로 돌아갑니다)

> MCP 서버의 툴을 사용해서, mcp-workspace 디렉토리 내의 파일 목록을 표시해주세요

Claude Code가 filesystem MCP 서버를 통해 디렉토리 내용을 취득하여 결과를 표시할 것입니다.

파일 작성도 시험해봅니다.

> MCP 서버의 툴로 src/hello.txt 라는 파일을 작성하고, 내용은 "MCP 최초 테스트"로 해주세요

파일이 실제로 생성되었는지 대화 모드 외에서 확인합니다.

cat ~/mcp-workspace/src/hello.txt

5단계: MCP 서버의 삭제와 재등록

학습을 위해 한 번 서버를 삭제하고 재등록해봅니다.

주의: 대화 모드 내에서는 /mcp로 상태 확인은 가능하지만, add / remove는 할 수 없습니다. 대화 모드를 종료(/exit 입력)하고 터미널로 돌아간 후 실행하세요.

claude mcp remove filesystem

기대되는 출력:

Removed MCP server "filesystem" from project config
File modified: /Users/username/mcp-workspace/.mcp.json

삭제를 확인합니다. --scope project의 서버는 .mcp.json에 저장되어 있으므로 파일의 내용을 확인합니다.

cat .mcp.json

재등록합니다.

claude mcp add --transport stdio --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem $PWD

MCP 서버 관리 커맨드 정리:

이 "추가 → 확인 → 삭제 → 재추가"의 사이클에 익숙해지면, 향후 트러블슈팅에서 도움이 됩니다.

더 나아가기

스코프 비교 실습

user 스코프와 project 스코프 양쪽으로 동일한 서버를 등록해보고, claude mcp list의 출력 차이를 비교해보세요.

# user 스코프로 등록 (전체에 적용)
claude mcp add --transport stdio --scope user filesystem-user -- npx -y @modelcontextprotocol/server-filesystem $HOME

# list로 양쪽 확인
claude mcp list