Claude Code + MCP로 AI 코딩 워크플로우 구축: 입문에서 실전까지

Claude Code + MCP: 왜 이 조합이 주목할 만한가

Claude Code 자체만으로도 충분히 강력합니다 — 코드베이스 전체를 이해하고, 파일 간 코드를 수정하며, 터미널에서 명령을 실행할 수 있습니다. 하지만 그 “세상”은 프로젝트 폴더에 국한되어 있습니다.

MCP 프로토콜의 등장은 이 벽을 허물었습니다. MCP 서버를 통해 Claude Code는 전체 개발 도구 체인에 대한 접근 능력을 얻습니다:

• 프로젝트 관리 시스템: Jira, Linear, Notion
• 코드 호스팅 플랫폼: GitHub, GitLab
• 데이터베이스: PostgreSQL, SQLite, MongoDB
• 모니터링 도구: Sentry, Datadog
• 디자인 도구: Figma
• 커뮤니케이션 도구: Slack, Telegram, Discord

이제 티켓 설명을 수동으로 채팅 창에 복사하거나, 데이터베이스 쿼리 결과를 스크린샷하여 AI에 보낼 필요가 없습니다. Claude Code가 이러한 시스템을 직접 읽고 조작할 수 있습니다.

---

1단계: Claude Code 설치

아직 Claude Code를 설치하지 않았다면, 여러 가지 방법이 있습니다:

macOS / Linux / WSL (원클릭 설치 권장):

curl -fsSL https://claude.ai/install.sh | bash

Homebrew (macOS):

brew install --cask claude-code

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

설치 후 어떤 프로젝트 디렉토리에서든 실행:

cd your-project
claude

처음 실행 시 로그인을 요청합니다. Claude Pro/Max/Team 구독, Anthropic Console API 계정, 그리고 Amazon Bedrock, Google Vertex AI 같은 서드파티 제공자도 지원합니다.

로그인 후 자격 증명은 로컬에 저장되므로, 이후 재로그인이 필요하지 않습니다.

설치에 대한 자세한 내용: Claude Code 공식 문서

---

2단계: MCP의 세 가지 연결 방식 이해

Claude Code는 세 가지 MCP 서버 전송 프로토콜을 지원하며, 각각 다른 시나리오에 적합합니다:

1. 원격 HTTP 서버 (권장)

클라우드 서비스 연결에 적합하며, 현재 가장 널리 지원되는 전송 방식입니다.

# Notion MCP 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 인증이 필요한 API 연결
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

.mcp.json 설정 파일에서 type 필드는 http의 별칭으로 streamable-http도 허용하므로, 다른 MCP 문서에서 복사한 설정을 그대로 사용할 수 있습니다.

2. 원격 SSE 서버

# Asana 연결 (참고: SSE 전송은 더 이상 사용되지 않으며, HTTP를 우선 권장)
claude mcp add --transport sse asana https://mcp.asana.com/sse

3. 로컬 stdio 서버

로컬 시스템 리소스에 직접 접근해야 하는 시나리오에 적합합니다. Claude Code는 CLAUDE_PROJECT_DIR 환경 변수를 하위 프로세스에 자동으로 전달하여 서버가 프로젝트 상대 경로를 쉽게 해석할 수 있도록 합니다.

# Airtable MCP 서버 연결
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

⚠️ 옵션 순서가 중요합니다: 모든 옵션(--transport, --env, --scope, --header)은 서버 이름 앞에 와야 합니다. -- (더블 대시) 뒤에 MCP 서버에 전달되는 명령과 매개변수가 옵니다.

---

3단계: 실전 — 개발 워크플로우 구축

다음은 완전한 실전 시나리오입니다: Claude Code + MCP를 사용하여 티켓부터 PR까지의 자동화를 구현합니다.

시나리오 설명

웹 프로젝트를 유지보수하고 있습니다. 프로덕트 매니저가 Linear에서 새로운 요구사항을 생성했고, 여러분은 다음을 수행해야 합니다:

1. 요구사항 설명 읽기
2. 코드베이스에 기능 구현
3. 테스트 실행
4. 코드 커밋 및 GitHub PR 생성
5. Slack에서 팀에 알림

MCP 서버 설정

먼저 GitHub와 Linear를 연결합니다:

# GitHub 연결 (개인 토큰 사용)
claude mcp add --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  github -- npx -y @anthropic/mcp-server-github

# Linear 연결
claude mcp add --transport http linear https://mcp.linear.app/mcp \
  --header "Authorization: Bearer lin_api_xxxx"

연결 후 다음 명령으로 상태를 확인할 수 있습니다:

claude mcp list

Claude Code 세션에서 /mcp을 실행하면 각 서버의 도구 수와 연결 상태를 확인할 수 있습니다.

실제 사용

이제 자연어로 전체 워크플로우를 완료할 수 있습니다:

Linear 티켓 WEB-123의 요구사항을 읽고 이 기능을 구현하세요.
GitHub에 feature/web-123 브랜치를 만들고,
작업完成后 테스트를 실행하고 통과하면 PR을 제출하고 팀에 알림하세요.

Claude Code는 다음을 수행합니다:

1. Linear MCP 서버를 통해 티켓 상세정보 읽기
2. Git 브랜치 생성
3. 요구사항을 이해하고 코드 작성
4. npm test 등의 테스트 명령 실행
5. GitHub MCP 서버를 통해 Pull Request 생성
6. Slack MCP 서버를 통해 알림 전송

데이터베이스 쿼리 워크플로우

개발을 보조하기 위해 데이터베이스를 쿼리해야 하는 경우:

# PostgreSQL 연결
claude mcp add --transport stdio \
  --env PG_CONNECTION_STRING=postgresql://user:pass@host:5432/db \
  postgres -- npx -y @modelcontextprotocol/server-postgres

그런 다음 Claude Code에 이렇게 질문할 수 있습니다:

최근 일주일간 /api/search 엔드포인트를 사용한 사용자 데이터를 조회하고,
성능 병목현상을 분석한 다음 관련 코드 최적화를 도와줘.

---

4단계: 고급 기법

동적 도구 업데이트

Claude Code는 MCP list_changed 알림을 지원하여, MCP 서버가 세션을 재시작하지 않고도 사용 가능한 도구 목록을 동적으로 업데이트할 수 있습니다. 이는 다음을 의미합니다:

• 세션 중에 일시적으로 일부 도구를 활성화/비활성화
• 프로젝트 컨텍스트에 따라 도구 세트 전환
• 조건부 도구 노출 구현

Claude로 MCP 서버 자동 생성

기존 MCP 서버로 요구사항을 충족할 수 없다면, Claude Code 자체가 구축을 도와줄 수 있습니다:

# Claude Code 세션에서 공식 플러그인 설치
/plugin install mcp-server-dev@claude-plugins-official

# 플러그인 다시 로드
/reload-plugins

# 빌드 도구 실행
/mcp-server-dev:build-mcp-server

Claude는 사용 사례를 질문한 다음, 원격 HTTP 또는 로컬 stdio 서버의 스캐폴드 코드를 자동으로 생성합니다.

프로젝트 수준 MCP 설정

MCP 설정은 특정 프로젝트에 한정할 수 있습니다. 프로젝트 루트 디렉토리에 .mcp.json 파일을 만들면, 해당 설정은 현재 프로젝트에만 적용됩니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

이렇게 하면 서로 다른 프로젝트가 완전히 다른 MCP 서버 세트를 가지면서 상호 간섭 없이 사용할 수 있습니다.

---

보안 주의사항

MCP 서버에 연결할 때 다음 보안 문제에 주의해야 합니다:

• 신뢰할 수 있는 서버에만 연결: 외부 콘텐츠를 가져오는 서버는 프롬프트 주입 위험을 초래할 수 있습니다
• 최소 권한 원칙: MCP 서버의 API 토큰에는 필요한 권한만 부여
• 연결된 서버 정기 검토: claude mcp list로 설정을 감사하고 사용하지 않는 서버 제거
• 민감한 데이터 격리: 데이터베이스 연결 문자열 등 민감한 정보는 환경 변수로 관리하고 하드코딩하지 말 것

---

요약

Claude Code + MCP의 조합은 본질적으로 핵심 문제를 해결합니다: AI 코딩 어시스턴트를 “코드를 쓸 수 있는” 상태에서 “일을 할 수 있는” 상태로 변환하는 것.

Claude Code가 티켓을 직접 읽고, 데이터베이스를 쿼리하며, Git을 조작하고, 알림을 보낼 수 있을 때, 이는 더 이상 수동적인 Q&A 도구가 아니라 전체 개발 워크플로우를 독립적으로 실행할 수 있는 지능형 에이전트가 됩니다.

이 워크플로우의 진입장벽은 높지 않습니다 — Claude Code를 설치하고, 몇 개의 MCP 서버를 연결하고, 자연어로 요구사항을 설명하면 나머지는 AI에 맡기면 됩니다. 아직 수동으로 티켓 내용을 복사하고, 수동으로 데이터베이스를 쿼리하며, 수동으로 PR을 만든다면, 이 솔루션을 시도해볼 가치가 있습니다.

---

추천 독서:

• Claude Code 공식 문서
• MCP 프로토콜 소개
• Anthropic MCP 디렉토리
• MCP 서버 개발 가이드
• Claude Code Hooks 자동화