🔥 Claude Code 에이전트에 날개 달기 — MCP와 스킬 입문

들어가며

Claude Code 쓰다 보면 어느 순간 "이 작업 방식을 에이전트로 저장해두면 매번 다시 설명 안 해도 되겠다"는 생각이 들어요. 저도 그 생각으로 스킬 파일을 하나 만들었는데 나중에 보니까 스킬이 서너 개 넘으면서 관리가 슬슬 어려워지더라고요.

어떤 스킬이 있는지 파악하려면 디렉토리를 직접 열어봐야 하고 새로운 도구를 추가하면 연관된 스킬 파일을 전부 찾아서 고쳐야 하거든요. 그 불편함이 쌓여서 스킬을 검색하고 설치해주는 MCP 서버를 직접 만들어보게 됐어요. 만들면서 MCP와 스킬이 어떻게 연결되는지 제대로 들여다보니 생각보다 개념이 명확하고 재미있네요.

프롬프트 반복의 피로와 컨텍스트 관리의 한계

AI와 일하다 보면 이런 상황이 끝없이 반복돼요.

"오늘은 PR 리뷰를 부탁해. 아 맞다 우리 팀은 TypeScript를 쓰고 strict 모드가 켜져 있어. 테스트는 Jest를 쓰고 커버리지는 무조건 80% 이상 유지해야 해. 코멘트는 한국어로 친절하게 달아줘…"

새로운 세션을 시작할 때마다 이 긴 맥락(Context)을 처음부터 다시 설명해야 하거든요. 매번 똑같은 프롬프트를 복사해서 붙여넣는 건 엄청난 낭비고 실수로 하나라도 빠뜨리면 AI 결과물이 확 달라져요. 프로젝트 규모가 커지고 팀 규칙이 많아질수록 "우리 팀 룰에 맞게 해줘"라는 한 마디를 알아듣게 만들기 위한 사전 작업이 너무 버거워지죠.

그래서 등장한 개념이 스킬(Skill)이에요. 자주 쓰는 "프롬프트(역할과 규칙) + 사용할 도구(Tools) + 연결할 외부 데이터(MCP)" 세트를 하나의 파일로 영구적으로 박제해두고 필요할 때 이름만 불러서 쓰는(On-demand) 방식이죠. 일회성 대화로 휘발되던 지식을 '재사용 가능한 맞춤형 에이전트 모듈'로 만든 셈이에요.

에이전트의 '전두엽' 만들기

스킬을 기술적인 관점에서 보면 에이전트의 전두엽(Executive Function)을 구성하는 과정이라고 볼 수 있는데요.

단순히 "리뷰 해줘"라고 명령하는 건 본능적인 반응을 요구하는 것에 가깝지만 스킬 파일에 구체적인 가이드와 도구를 적어주는 건 에이전트에게 '이 작업을 할 때 고려해야 할 가치 판단 기준'과 '사용 가능한 수단'을 미리 세팅해 주는 작업이에요.

이 '전두엽'이 잘 설계되어 있을수록 에이전트는 복잡한 상황에서도 일관된 판단을 내릴 수 있게 됩니다. "나는 타입 안전성을 가장 중요하게 생각하는 리뷰어 스킬을 장착했으니까 이 코드는 그냥 넘어갈 수 없어"라고 스스로 판단하게 만드는 힘이 여기서 나오거든요.

역할 카드를 에이전트에게 주는 것

스킬을 가장 쉽게 설명하면 에이전트에게 주는 역할 카드예요. "너는 코드 리뷰 전문가야. 이런 도구를 쓸 수 있어. 이런 기준으로 리뷰해"라고 미리 써두는 거죠. 실체는 그냥 마크다운 파일이에요.

---
name: code-reviewer
description: "TypeScript 코드 리뷰 전문 에이전트"
tools: [Read, Bash]
mcpServers: [github]
---

PR을 받으면 코드 품질, 타입 안전성, 테스트 커버리지를 중심으로 리뷰해요.

frontmatter(파일 맨 위 --- 사이 영역)에 에이전트의 능력을 선언하고 그 아래 본문이 시스템 프롬프트가 돼요. Claude Code가 이 에이전트를 실행할 때 이 파일 전체를 컨텍스트로 넘겨주는 구조예요.

여기서 tools와 mcpServers는 역할이 달라요. tools는 Claude Code 안에 내장된 도구(Read, Bash, Write 같은 것들) 중에서 이 에이전트에게 허용할 목록이고 mcpServers는 외부에 별도로 띄운 MCP 서버를 연결하는 필드예요.

그리고 description 필드가 생각보다 중요해요. Claude가 어떤 스킬을 불러올지 결정할 때 이 필드를 봐요. "PR 리뷰해줘"라고 했을 때 description: "PR 번호를 주면 코드 품질을 리뷰해요"인 스킬을 찾아내는 거예요. 여기가 애매하면 Claude가 스킬을 못 찾거나 엉뚱한 걸 골라요.

어디에 두느냐에 따라 범위가 달라져요

파일 위치는 두 군데예요. ~/.claude/agents/에 두면 모든 프로젝트에서 쓸 수 있는 글로벌 스킬이 되고 프로젝트 루트의 .claude/agents/에 두면 그 프로젝트 안에서만 쓸 수 있어요. 같은 이름이면 프로젝트 스킬이 우선이에요.

어느 쪽에 둬야 할지 기준은 간단해요. 어디서든 쓰는 범용 작업(문서 작성, 코드 리뷰 같은 것들)은 글로벌에 두고 특정 프로젝트 도메인이 필요한 작업(사내 배포 시스템 접근, 특정 DB 구조 조회 같은 것들)은 프로젝트 스킬로 두는 게 맞아요. 사내 API에 연결하는 스킬을 글로벌로 두면 다른 프로젝트에서는 어차피 쓸 수 없는데 목록에만 남아 있어서 노이즈가 돼요.

쓰면 어떻게 되냐면

"PR 리뷰해줘"라고 Claude Code에 말하면 Claude가 등록된 스킬 목록을 보고 code-reviewer 스킬이 적합하다고 판단해요. 그 스킬을 불러와서 에이전트를 실행하고 tools에 적힌 Read, Bash와 mcpServers에 적힌 github을 이 에이전트에게 줘요. 에이전트는 그 도구들을 써서 GitHub에 직접 접근하고 댓글을 달고 리뷰를 남길 수 있게 되는 거예요.

매번 "GitHub 도구 써서 PR 번호 몇 번을 이런 기준으로 리뷰해"라고 설명할 필요 없이 한 번 스킬로 만들어두면 끝이에요.

---

MCP가 뭐예요?

왜 도구 하나 연동할 때마다 매번 '삽질'을 해야 했을까요?

스킬 파일에서 mcpServers에 이름을 적으면 에이전트가 외부 서비스에 접근할 수 있다고 했는데요. 그 외부 서비스를 연결해주는 게 MCP예요. 사실 이 MCP가 탄생한 배경을 알면 지금 AI 생태계가 얼마나 빠르게 진화하고 있는지 알 수 있어요.

과거에는 AI 클라이언트와 외부 데이터 소스를 연결하려면 이른바 'N × M 통합의 저주'를 겪어야 했는데요. 예를 들어 볼까요?

• AI 모델 측면(N): OpenAI API, Anthropic Claude, Google Gemini 등
• 데이터/서비스 측면(M): GitHub, Slack, Notion, Jira, 사나 데이터베이스 등

예전엔 OpenAI에 GitHub을 연결하려면 OpenAI 전용 Function Calling 체계에 맞춰 코드를 짜야 했고 이걸 Claude에 이식하려면 Claude 전용 규격으로 완전히 다시 짜야 했거든요. 반대로 새로운 사내 도구를 도입하면 그 도구를 우리가 쓰는 모든 AI 모델에 맞게 수십 개의 연동 코드를 개별적으로 만들어야 했어요. 모든 개발자가 각자의 바퀴를 다시 발명하고 있는 심각한 파편화 상태였죠.

어디든 꽂으면 작동하는 AI 전용 USB 포트의 등장

이 파편화 문제를 단번에 해결하려고 Anthropic이 주도해서 제안한 오픈 표준이 바로 MCP(Model Context Protocol)예요.

개발자분들이라면 과거 IDE 생태계를 혁신했던 LSP(Language Server Protocol)를 떠올리시면 정확할 텐데요. LSP 덕분에 언어별 분석 서버만 하나 잘 만들어두면 VSCode든 IntelliJ든 어떤 에디터에서든 쓸 수 있게 된 것처럼 "어떤 AI 클라이언트든 어떤 데이터 소스든 중간에 MCP라는 공통 규격 하나만 맞추자"는 혁신적인 접근이죠.

이제 한 번만 'GitHub MCP 서버'를 만들어 두면 Claude Code는 물론이고 Cursor나 Windsurf처럼 MCP 스펙을 지원하는 모든 클라이언트에서 별도 연동 코드 없이 그대로 가져다 쓸 수 있습니다. 말 그대로 AI에게 새로운 감각 기관을 빠르고 규격화되게 달아줄 수 있는 '공용 USB 포트'가 발명된 셈이에요.

과거에 갇힌 AI에게 '지금 이 순간'을 알려주는 법

개념적으로 더 깊이 들어가 보면 MCP는 AI 모델의 가장 고질적인 문제인 '지식 차단(Knowledge Cut-off)'과 '불투명한 외부 접근'을 해결하는 핵심 고리예요.

LLM은 학습된 시점까지의 데이터만 알고 있는 아주 똑똑한 '박제된 뇌'와 같은데요. MCP는 이 뇌에게 실시간으로 세상을 보고 느낄 수 있는 감각 신경과 운동 신경을 달아주는 프로토콜이라고 이해하시면 좋아요.

• 지식의 실시간성 확보: MCP 리소스를 통해 현재 프로젝트의 최신 코드나 문서 그리고 DB 상태를 LLM의 컨텍스트 윈도우 안에 실시간으로 '주입'해 줍니다.
• 행동의 규격화: MCP 도구를 통해 LLM이 추상적으로 생각만 하는 게 아니라 실제 세상에 영향을 주는 행동(PR 생성 이나 메시지 전송 등)을 표준화된 방식으로 수행하게 하죠.

Host-Client-Server 구조 이해하기

MCP가 실제로 동작할 때는 세 가지 주체가 서로 손잡아요.

1. MCP Host: 에이전트가 살고 있는 집이에요. (예: Claude Code) 여러 개의 MCP 서버를 관리하고 제어하는 컨트롤 타워 역할을 하거든요.
2. MCP Client: Host 내부에서 특정 서버와 대화하기 위한 대화 창구예요.
3. MCP Server: 실제로 데이터가 있거나 행동을 수행하는 외부 프로그램이죠.

재미있는 건 이 서버가 내 컴퓨터에서 돌아가는 간단한 스크립트일 수도 있고 저 멀리 클라우드에 떠 있는 거대한 시스템일 수도 있다는 점인데요. 어떤 형태든 MCP라는 통일된 언어로 말하니까 Host(에이전트) 입장에서는 그저 '내가 쓸 수 있는 추가적인 감각'으로 보일 뿐이에요.

Claude Code에 MCP 서버를 등록하는 건 명령어 한 줄이에요.

claude mcp add github -- npx @modelcontextprotocol/server-github

환경 변수가 필요한 경우엔 -e 플래그로 넘겨줘요.

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=<token> -- npx @modelcontextprotocol/server-github

모든 프로젝트에서 쓰고 싶다면 --scope global 옵션을 붙여요.

claude mcp add --scope global github -- npx @modelcontextprotocol/server-github

이렇게 등록하면 Claude Code가 필요할 때 그 서버를 실행하고 서버가 제공하는 도구들을 에이전트에게 넘겨줄 수 있는 상태가 돼요.

MCP 서버가 제공하는 것

MCP 서버가 에이전트에게 줄 수 있는 건 크게 세 가지예요.

Tool은 에이전트가 직접 호출하는 함수예요. "GitHub에 PR 만들어줘"나 "DB에서 이 쿼리 실행해줘" 같은 동작이 여기 해당하거든요. 이 글에서 다루는 대부분의 사례가 이 형태예요.

Resource는 읽기 전용 데이터예요. 문서나 설정 파일 또는 특정 파일 내용 같은 걸 에이전트가 참조할 수 있게 노출하는 방식인데요. Tool이 "행동"이라면 Resource는 "참고 자료"에 가깝다고 보시면 돼요.

Prompt는 재사용할 수 있는 프롬프트 템플릿이에요. 팀 공통으로 쓰는 리뷰 기준이나 분석 방식을 서버에 저장해두고 꺼내 쓰는 방식이죠. 여러 에이전트가 같은 기준을 공유해야 할 때 유용해요.

---

MCP로 뭘 연결할 수 있어요?

이미 만들어진 MCP 서버가 꽤 많아요. 실무에서 쓸 만한 사례들을 구체적으로 정리해봤어요.

GitHub MCP

PR 만들기나 이슈 코멘트 달기 또는 브랜치 관리를 에이전트가 직접 할 수 있어요. 코드를 분석한 뒤 GitHub에 직접 리뷰 코멘트를 남기는 식으로요. 지금까지 "이 코드 분석해줘 → 결과 복사 → GitHub에 직접 코멘트 붙여넣기" 하던 흐름이 한 번에 끝나서 정말 편해요.

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=<token> -- npx @modelcontextprotocol/server-github

등록하면 create_pull_request나 add_comment 그리고 list_issues 같은 도구가 에이전트에게 열려요.

파일 시스템 MCP

프로젝트 디렉토리 구조를 읽고 파일을 일괄 수정하거나 특정 패턴의 파일을 찾는 작업을 에이전트가 처리할 수 있어요. 대규모 코드 마이그레이션 작업이나 레거시 패턴 교체 같은 데 유용하거든요. Claude Code 내장 Read나 Write 도구보다 디렉토리 탐색이 훨씬 수월해요.

claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem

Slack MCP

특정 채널에 자동으로 리포트를 보내거나 팀 알림을 전송할 수 있어요. 배포 완료 알림이나 에러 분석 요약 또는 주간 코드 리뷰 결과를 에이전트가 직접 슬랙으로 보내주는 식이죠.

claude mcp add slack -- npx @modelcontextprotocol/server-slack

send_message나 list_channels 같은 도구를 에이전트에서 바로 쓸 수 있어요.

데이터베이스 MCP

DB 스키마 조회나 쿼리 실행 그리고 데이터 분석을 에이전트가 직접 할 수 있어요. 에러 원인 추적이나 데이터 집계 리포트 작업에서 "DB 나가서 확인해봐야 하는데" 하는 번거로움이 사라지거든요. PostgreSQL이나 MySQL 같은 주요 DB용 서버가 따로 있어요.

claude mcp add postgres -- npx @modelcontextprotocol/server-postgres

사내 API MCP

이게 개인적으로 가장 흥미로운 케이스예요. 배포 상태 조회나 티켓 시스템 업데이트 또는 내부 서비스 모니터링 같은 걸 에이전트에게 붙일 수 있거든요. MCP TypeScript SDK를 쓰면 사내 API를 MCP 서버로 감싸는 작업이 생각보다 오래 안 걸려요.

// 사내 API를 MCP 서버로 감싸는 핵심 구조
server.tool(
  "get_deploy_status",
  "배포 상태를 조회해요",
  { service: z.string() },
  async ({ service }) => {
    const status = await internalApi.getDeployStatus(service);
    return { content: [{ type: "text", text: JSON.stringify(status) }] };
  },
);

이 서버를 등록하면 에이전트가 get_deploy_status 도구를 쓸 수 있게 돼요.

---

스킬로 뭘 할 수 있어요?

MCP 개념을 알았으니 이제 스킬 사례를 보면 mcpServers 필드가 왜 있는지 자연스럽게 읽혀요. 써보면서 유용하게 쓰고 있는 사례 네 가지를 정리해봤는데요.

PR 리뷰 에이전트

PR 번호를 넘겨주면 코드 변경사항을 읽고 리뷰해주는 에이전트예요. 타입 안전성이나 테스트 누락 같은 기준을 스킬 본문에 적어두면 매번 같은 기준으로 리뷰해주거든요.

---
name: pr-reviewer
description: "PR 번호를 주면 코드 품질과 타입 안전성을 리뷰해요"
tools: [Read, Bash]
mcpServers: [github]
---

PR을 리뷰할 때 아래 순서로 진행해요.

1. GitHub에서 diff를 읽어요
2. 타입 안전성과 테스트 커버리지 그리고 코드 중복을 중심으로 분석해요
3. 심각도별로 분류해서 코멘트를 정리해요

mcpServers에 github이 없으면 GitHub에 실제로 접근하지 못하니까 GitHub MCP 서버 등록이 필수예요.

문서 작성 에이전트

코드를 읽고 README나 JSDoc 주석을 자동으로 써주는 에이전트예요. 함수 시그니처만 보고 설명을 만들어내는 게 생각보다 잘 되거든요.

---
name: doc-writer
description: "코드를 읽고 README나 JSDoc을 작성해요"
tools: [Read, Write, Bash]
---

파일을 분석해서 공개 API 위주로 JSDoc을 작성해요.
기존 주석이 있으면 덮어쓰지 않고 없는 것만 채워요.

외부 서비스 연결 없이 내장 도구(Read와 Write)만으로 충분한 사례예요. mcpServers가 없어도 되는 스킬이죠.

배포 전 체크리스트 에이전트

배포 전에 테스트나 린트 그리고 보안 이슈를 순서대로 확인해주는 에이전트예요. 매번 "테스트 돌리고 린트 확인하고 env 빠진 거 없는지 봐줘"라고 말하는 대신 "배포 전 체크해줘" 한 마디로 끝낼 수 있어요.

---
name: pre-deploy-check
description: "배포 전 체크리스트를 순서대로 실행해요"
tools: [Bash, Read]
---

아래 순서대로 확인해요. 하나라도 실패하면 멈추고 이유를 설명하거든요.

1. `npm test` — 전체 테스트 통과 여부
2. `npm run lint` — 린트 오류 없음
3. .env.example 대비 실제 .env 키 누락 없음
4. 하드코딩된 시크릿 키 패턴 검색

에러 분석 에이전트

에러 로그를 붙여넣으면 원인을 추적하고 수정 방향을 제안해주는 에이전트예요. 스택 트레이스가 길고 복잡할 때 특히 유용해요.

---
name: error-detective
description: "에러 로그를 분석하고 원인과 수정 방향을 제안해요"
tools: [Read, Bash]
mcpServers: [database]
---

에러 로그를 받으면 아래 순서로 분석해요.

1. 에러 타입과 발생 위치 파악
2. 관련 코드 파일 읽기
3. DB 쿼리 로그나 상태 조회 (database MCP 활용)
4. 원인 가설 제시 및 수정 코드 제안

이 에이전트는 database MCP 서버가 있으면 관련 DB 상태까지 같이 조회할 수 있는데요. 없어도 코드 분석은 잘 돼요.

---

스킬과 MCP가 실제로 어떻게 연결돼요?

조합 시나리오를 보기 전에 한 가지 짚고 넘어가면 좋을 게 있어요. 스킬 파일에 mcpServers: [github] 한 줄 적는 게 실제로 어떤 일을 하는지 말이죠.

1. Claude Code가 설정 파일에서 github이라는 이름의 서버 설정을 찾아요
2. 에이전트 실행 시점에 그 서버 프로세스를 띄우거든요
3. 서버가 제공하는 Tool 목록을 받아와요
4. 에이전트는 그 Tool들을 실제로 호출할 수 있게 돼요

스킬 파일: mcpServers: [github]
    ↓ 이름 매칭
설정 파일의 "github" 서버 설정
    ↓ 프로세스 스폰
GitHub MCP 서버
    ↓ Tool 목록 전달
에이전트가 create_pr 이나 add_comment 등을 쓸 수 있게 됨

스킬 파일이 직접 GitHub에 접근하는 게 아니에요. 스킬이 "이름표"를 들고 있고 Claude Code가 그 이름표를 보고 서버를 찾아서 연결하는 구조예요. 그래서 MCP 서버를 먼저 등록해두지 않으면 스킬 파일에 이름을 적어도 아무 일도 안 일어나요.

---

스킬과 MCP를 조합하면 진짜 강해져요

시나리오 1: PR 자동 리뷰 + 코멘트 봇

스킬: pr-reviewer + MCP: github

"PR #123 리뷰해줘"라고 하면 이렇게 흘러가요.

사용자: PR #123 리뷰해줘

→ Claude가 pr-reviewer 스킬 실행
→ github MCP로 PR diff 읽기
→ 코드 품질, 타입 안전성 분석
→ github MCP로 리뷰 코멘트 직접 등록
→ "리뷰 완료했어요. 심각도 높은 이슈 2개 발견했어요." 응답

예전엔 Claude한테 분석 받고 결과를 복사해서 GitHub에 직접 붙여넣어야 했지만 이 조합이라면 그 과정이 사라져요. 스킬 파일은 위에서 본 pr-reviewer에서 mcpServers: [github]가 붙어있는 게 전부거든요.

시나리오 2: 배포 파이프라인 에이전트

스킬: pre-deploy-check + MCP: github, slack

배포 전 자동 체크에서 완료 알림까지 한 흐름으로 연결하는 시나리오예요.

사용자: main 브랜치 배포 체크해줘

→ pre-deploy-check 스킬 실행
→ 테스트, 린트, 보안 이슈 순서대로 확인 (Bash 도구)
→ 이상 없으면 github MCP로 PR 상태 코멘트 등록
→ 완료 후 slack MCP로 #deploy 채널에 알림 전송
→ "체크 완료됐어요. PR에 결과 코멘트 남겼어요." 응답

스킬 파일에 mcpServers: [github, slack]을 추가하는 것만으로 이 흐름이 가능해집니다.

---
name: pre-deploy-check
description: "배포 전 체크부터 완료 알림까지 한 번에"
tools: [Bash, Read]
mcpServers: [github, slack]
---

체크리스트 통과 후 PR에 상태 코멘트를 남기고
완료되면 #deploy 채널에 결과를 전송해요.

시나리오 3: 에러 탐정 에이전트

스킬: error-detective + MCP: database, slack

에러 로그를 붙여넣으면 DB까지 뒤져서 원인을 찾고 슬랙으로 요약을 보내줘요.

사용자: (에러 로그 붙여넣기)

→ error-detective 스킬 실행
→ 스택 트레이스에서 에러 위치 파악
→ 관련 코드 파일 읽기 (Read 도구)
→ database MCP로 해당 시간대 DB 쿼리 로그 조회
→ 원인 분석: "3시 15분에 users 테이블 락 경합이 발생했어요"
→ slack MCP로 #on-call 채널에 분석 요약 전송
→ 수정 방향 제안

DB 쿼리 로그까지 자동으로 뒤지는 부분이 사실 제일 시간이 많이 걸리는 작업인데 그게 자동화되는 거죠. 야간 장애 대응할 때 유용하게 쓸 수 있어요.

이 세 시나리오의 공통점은 스킬이 "무엇을 어떻게 할지"를 정의하고 MCP가 "실제로 어디까지 손을 뻗을 수 있는지"를 결정한다는 거예요. 스킬만 있으면 분석까지지만 MCP가 붙으면 행동까지 가능해져요.

---

마무리

결국 스킬은 에이전트에게 역할과 도구를 미리 부여해두는 파일이었어요. MCP는 AI마다 달랐던 외부 도구 연결 방식을 표준화한 프로토콜이고요. 스킬 파일의 mcpServers가 그 두 세계를 연결하는 접점이 되는 셈이죠.

이 둘을 조합하면 생각보다 많은 게 가능해요. GitHub에 직접 코멘트를 다는 코드 리뷰 에이전트나 사내 API를 조회해서 정리해주는 데이터 에이전트 그리고 스킬 파일 자체를 관리해주는 에이전트까지 생각보다 확장성이 크거든요.

처음엔 MCP가 꽤 복잡한 기술처럼 느껴졌는데 실제로 써보니까 "도구를 에이전트에게 연결하는 표준 방식"이라는 개념 하나로 설명이 다 되더라고요. 스킬 파일에 이름 한 줄 적는 것만으로 외부 서비스를 에이전트에 붙일 수 있다는 게 아직도 좀 신기하긴 해요.

참고 자료

• Model Context Protocol 공식 문서
• MCP TypeScript SDK
• Claude Code - Sub-agents 문서