💡 MCP가 가능하게 하는 것들

• Claude Code가 GitHub 이슈 내용을 읽고 코드를 자동 생성
• AI 에이전트가 Google Calendar + Notion을 동시에 참조해 일정 관리
• 기업 챗봇이 조직 내 복수의 데이터베이스에 접근해 데이터 분석
• Figma 디자인을 AI가 읽어 React 컴포넌트를 즉시 생성

{
"mcpServers": {
"server-name": {
"type": "stdio",
"command": "npx",
"args": ["-y", "패키지명"],
"env": {
"API_KEY": "여기에_키_입력"
}
}
}
}

# GitHub MCP 서버를 유저 전체 범위로 설치
claude mcp add github --scope user
# 설치된 서버 목록 확인
claude mcp list
# Claude Code 대화 중 MCP 상태 확인
/mcp

⚠️ 핵심 주의사항

API 키와 비밀번호는 절대 .mcp.json(팀 공유 파일)에 직접 입력하지 마세요. 개인 파일(.claude/settings.local.json)이나 환경 변수를 사용하는 것이 보안상 안전합니다.

GitHub MCP 서버는 가장 즉각적인 생산성 향상을 체감할 수 있는 서버입니다. 이슈 번호 하나만 알려주면 Claude가 내용을 읽고 코드를 작성한 뒤 PR까지 올려줍니다.

{
"mcpServers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_여기에_토큰"
}
}
}
}

활용 예: "GitHub 이슈 #142 읽고 해당 기능 구현 후 PR 만들어줘"

Notion MCP는 OAuth 인증 방식으로 워크스페이스에 안전하게 연결됩니다. 코드베이스 분석 결과를 자동으로 Notion에 문서화하거나, 스프린트 완료 태스크를 기반으로 릴리즈 노트를 자동 생성하는 데 특히 강점을 발휘합니다.

{
"mcpServers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
}
}
}

활용 예: "이번 스프린트 완료 태스크로 릴리즈 노트 Notion에 작성해줘"

더 이상 SQL을 직접 작성하지 않아도 됩니다. “지난 30일간 신규 가입자 수 집계해줘”라고 말하면 Claude가 스키마를 탐색하고 올바른 쿼리를 실행해 결과를 반환합니다. 중요한 점은 DB 접속 정보는 로컬에만 저장됩니다.

{
"mcpServers": {
"postgres": {
"type": "stdio",
"command": "npx",
"args": ["postgres-mcp-server"],
"env": {
"POSTGRES_URL": "postgresql://user:pass@localhost:5432/mydb"
}
}
}
}

현재 오픈 베타 단계이지만 이미 실무 적용 사례가 폭발적으로 늘고 있습니다. Figma 프레임을 선택하면 Claude가 디자인 토큰(색상, 타이포, 스페이싱)을 추출해 React + Tailwind CSS 컴포넌트를 생성합니다. Professional 이상 플랜에서 사용 가능합니다.

claude mcp add --transport http figma https://mcp.figma.com/mcp

결제 플로우, 회원가입 프로세스 등 복잡한 E2E 테스트를 “결제 전체 플로우 테스트 만들어줘” 한 마디로 생성할 수 있습니다. Chrome, Firefox, Safari 크로스 브라우저 테스트와 접근성 검증(WCAG 2.1 AA)까지 자동 적용됩니다.

claude mcp add playwright npx @playwright/mcp@latest

10만 줄이 넘는 대형 프로젝트에서 진가를 발휘합니다. 함수 하나의 이름을 바꾸면 모든 import와 호출부를 자동으로 업데이트하고, 아키텍처 결정사항과 코딩 컨벤션을 세션 간에 기억합니다. 팀 온보딩 시간을 획기적으로 단축시켜 주는 서버입니다.

claude mcp add-json "serena" '{"command":"uvx","args":["--from","git+https://github.com/oraios/serena","start-mcp-server"]}'

단 한 문장으로 가능한 것:

"Sentry에서 최근 에러 로그 가져와서 관련 코드 수정하고,
GitHub에 PR 만들고, Slack #engineering 채널에 알림 보내줘"

Step 1. Sentry MCP → 에러 로그 조회
Step 2. Filesystem MCP → 관련 파일 탐색
Step 3. Claude Code → 코드 수정 실행
Step 4. GitHub MCP → PR 자동 생성
Step 5. Slack MCP → 알림 전송

{
"mcpServers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
},
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
},
"postgres": {
"type": "stdio",
"command": "npx",
"args": ["postgres-mcp-server"],
"env": { "POSTGRES_URL": "postgresql://user:pass@localhost:5432/db" }
},
"slack": {
"type": "stdio",
"command": "npx",
"args": ["slack-mcp-server"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-xxx",
"SLACK_TEAM_ID": "T1234567890"
}
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}

❌ 오류 1: MCP Error -32000 (Connection Closed)

원인: stdout에 로그를 직접 출력하면 JSON-RPC 프로토콜과 충돌합니다. 해결: Python은 logging 모듈, Node.js는 console.error()를 사용해야 합니다. stdout은 프로토콜 전용입니다.

❌ 오류 2: 서버가 목록에 나타나지 않음

체크리스트: JSON 문법 오류 확인(cat .mcp.json | jq .), 파일 경로 절대경로 여부, API 키 값 정확도, Claude Code 재시작 여부. 이 4가지만 확인하면 99% 해결됩니다.

❌ 오류 3: 응답이 느리거나 토큰 초과 경고

원인: DB 쿼리 결과나 파일 내용이 컨텍스트 윈도우(기본 25,000 토큰)를 초과합니다. 해결: SQL에 LIMIT 추가, SELECT * 대신 필요 컬럼만 지정, Claude Code v2.1.7+ 에서는 "defer_loading": true 설정으로 필요한 도구만 로드합니다.

# 서버 상태 확인
claude mcp list
# 로그 실시간 확인 (macOS)
tail -f ~/Library/Logs/Claude/mcp*.log
# MCP Inspector로 시각적 디버깅
npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-github
# JSON 문법 검증
cat .mcp.json | jq .

# 1. 프로젝트 초기화
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
# 2. 서버 코드 작성 (index.ts)
# 3. 빌드 및 테스트
npx tsc && node dist/index.js

🏆 커스텀 서버 개발 4가지 황금 원칙

• 절대 stdout에 로그 출력 금지 — 프로토콜 충돌의 주범
• Zod/Pydantic으로 입력값 검증 — 타입 안전성 보장
• 도구명은 snake_case + 동사 시작 — get_user_info 형식
• 에러를 isError: true로 명시 — Claude가 에러를 정확히 인식