Claude Code와 Model Context Protocol(MCP) 통합 도구 확장 비결

MCP란?

MCP(Model Context Protocol)는 LLM이 외부 도구/데이터 소스에 접근하도록 표준화한 오픈 프로토콜입니다. Claude Code는 MCP 클라이언트로서 여러 MCP 서버에 연결해 기능을 확장합니다. 예를 들어 DB 스키마 파악, 이슈 시스템 조회, 파일 편집 도구 접근 등 “LLM+도구” 워크플로를 터미널에서 곧바로 구현할 수 있습니다.

⚠️ 보안 주의: 인터넷과 통신하는 서드파티 MCP 서버는 프롬프트 인젝션 위험이 있으므로, 신뢰 가능한 서버만 연결하세요. 조직 정책과 승인 절차를 반드시 거치십시오.

빠른 시작: MCP 서버 추가·관리 명령

Claude Code에서 MCP 서버를 추가하는 방법은 크게 두 가지입니다. stdio(표준입출력)와 SSE(Server-Sent Events). 추가 후에는 목록/조회/삭제로 관리합니다.

A. stdio 서버 추가

# 기본 문법
claude mcp add <이름> <명령어> [인자...]

# 예시: 로컬 실행형 서버 + 환경변수 전달
claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2

• -e/--env KEY=value : 서버 실행 시 환경변수 주입
• MCP_TIMEOUT=10000 claude : 서버 시작 타임아웃(밀리초) 설정 예시(10초)
• /mcp : 현재 MCP 상태를 대화형으로 확인

B. SSE 서버 추가

# 기본 문법
claude mcp add --transport sse <이름> <url>

# 예시
claude mcp add --transport sse sse-server https://example.com/sse-endpoint

C. 서버 관리

claude mcp list          # 등록 서버 목록
claude mcp get my-server # 서버 상세
claude mcp remove my-server

스코프(scope) 이해: local / project / user

서버 설정을 어디에 저장/적용할지 범위를 정할 수 있습니다. 동일 이름이 여러 스코프에 있으면 우선순위는 local > project > user입니다.

• local(기본값) : 현재 프로젝트에서 나만 사용

  claude mcp add my-private-server /path/to/server
  # 혹은 명시적으로
  claude mcp add my-private-server -s local /path/to/server

• project : 프로젝트 루트 .mcp.json 에 기록되어 팀과 공유

  claude mcp reset-project-choices

  .mcp.json 예시

  {
    "mcpServers": {
      "shared-server": {
        "command": "/path/to/server",
        "args": [],
        "env": {}
      }
    }
  }

  프로젝트 스코프 사용 여부를 초기화하려면

  claude mcp add shared-server -s project /path/to/server

• user : 내 사용자 환경 전체에서 사용(개인 전역)

  claude mcp add my-user-server -s user /path/to/server

✅ 운영 팁: .mcp.json을 VCS에 포함하면 팀이 동일 도구를 공유합니다. 도구 검증·승인·변경관리 절차를 함께 문서화하세요.

실전 예시 ①: Mysql MCP 서버로 DB 인사이트 얻기

읽기 전용 Mysql MCP 서버를 연결하면 Claude에게 “스키마 설명/최근 주문/테이블 관계” 같은 질의를 자연어로 요청할 수 있습니다.

# 연결(예시)
claude mcp add mysql-server /opt/mcp/mysql-mcp-server \
  --connection-string "mysql://readonly_user:securepass@127.0.0.1:3306/newsdb"

Claude 세션에서 예시 질의

describe the schema of our users table
what are the most recent orders in the system?
show me the relationship between customers and invoices

🔒 보안 포인트

• 계정은 최소 권한(READ ONLY) 으로 제한
• DB 접근·쿼리 로그 수집 및 감사를 활성화
• 연결문자열·비밀은 환경변수/전용 비밀저장소로 관리

실전 예시 ②: JSON으로 서버 한 방에 추가

단일 JSON으로 서버 구성을 곧바로 등록할 수 있습니다. 셸 이스케이프에 유의하세요.

# 기본 문법
claude mcp add-json <이름> '<json>'

# 예시(stdio)
claude mcp add-json news-api \
'{"type":"stdio","command":"/path/to/news-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 확인
claude mcp get news-api

팁: 전역 추가가 필요하면 -s global(= user 스코프 계열)로도 등록할 수 있습니다.

Claude Desktop 설정 가져오기

이미 Claude Desktop에서 MCP 서버를 써왔다면, 아래 명령으로 가져와 재사용할 수 있습니다.

(대화형 선택 지원, macOS/WSL 한정)

claude mcp add-from-claude-desktop
claude mcp list

동일 이름이 있으면 _1 같은 접미사가 붙습니다.

300x250

Claude Code 자체를 MCP 서버로 제공하기

Claude Code를 MCP 서버로 띄워 다른 MCP 클라이언트(예: Claude Desktop)에서 Claude의 View/Edit/LS 같은 도구에 접근하게 만들 수 있습니다.

# Claude를 MCP 서버로 시작
claude mcp serve

다른 애플리케이션(클라이언트)에서 연결 설정 예

{
  "command": "claude",
  "args": ["mcp", "serve"],
  "env": {}
}

⚠️ 보안 포인트

• 파일 열람/편집 등 민감 도구가 노출될 수 있으므로 접근주체·허용경로·승인흐름을 명확히 통제
• 각 클라이언트는 도구 호출 시 사용자 승인(권한 프롬프트) 을 구현해야 합니다(원문 권고).

보안·운영 체크리스트

1. 서버 신뢰성: 외부 MCP는 공급망·프롬프트 인젝션 리스크를 평가하고, 내부 전용 또는 검증된 서버만 허용.
2. 최소 권한: DB/클라우드/API 키는 읽기 전용·스코프 최소화. 롤 기반 접근통제(RBAC) 적용.
3. 비밀 관리: --env로 넘기는 키는 환경변수/전용 비밀저장소 사용, 저장 파일 권한 제한.
4. 스코프 정책: local/project/user 사용 기준을 보안정책에 명문화(프로젝트 스코프는 리뷰·승인 필수). 우선순위(local>project>user) 인지.
5. 설정 형상관리: .mcp.json/JSON 구성 파일은 민감정보 제거 후 버전관리. 필요 시 Git-secret/암호화.
6. 승인 프롬프트: 위험 작업은 사용자 승인 필요. 팀 교육과 UX 가이드 제공.
7. 로깅/감사: 도구 호출·데이터 접근 로그 수집, 경보 규칙(SIEM) 연동, 정기 점검 리포트화.
8. 타임아웃/견고성: MCP_TIMEOUT 등으로 지연/응답 불능 시 복구 전략을 문서화.
9. 온보딩 문서: 서버 추가/삭제/점검 절차, 책임자, 비상 연락 루트를 위키에 상시 최신화.

트러블슈팅 힌트

• 연결 지연/실패: MCP_TIMEOUT 조정, 네트워크/방화벽/프록시 점검.
• 프로젝트 스코프 미적용: .mcp.json 경로/형식 재확인, 필요 시 claude mcp reset-project-choices로 초기화.
• 권한 관련 이슈: 클라이언트의 도구 허용 상태(/mcp 또는 설정에서)와 승인 프롬프트 확인.

베스트 프랙티스 모음

• 개발/운영 분리: 실험 서버는 local, 팀 표준 서버는 project로 구분. 릴리스 규칙을 문서화.
• 세분화된 서버 구성: DB(READ ONLY), 이슈 트래커, 빌드/배포 도구 등 역할별 MCP 서버를 분리해 권한 최소화.
• 도구 카탈로그 운영: 승인된 MCP 서버 목록, 도구 설명서, 사용 예시를 내부 위키에 정리.
• 감사 자동화: 등록 서버(claude mcp list)와 .mcp.json을 정기 검사해 무단 추가를 탐지.

실무 예제 모음

① 프로젝트 공유 서버(프로젝트 스코프)

# 서버 추가
claude mcp add shared-server -s project /opt/tools/my-mcp

# .mcp.json 생성 여부 확인 후 커밋
git add .mcp.json && git commit -m "Add shared MCP server"

② JSON 한 방 등록 + 전역 사용

claude mcp add-json -s user news-api \
'{"type":"stdio","command":"/usr/local/bin/news-cli","args":["--api-key","$NEWS_KEY"],"env":{"CACHE_DIR":"/var/cache/news"}}'
claude mcp get news-api

③ SSE 원격 서버

claude mcp add --transport sse sentry-mcp https://mcp.example.com/sse
claude mcp list

④ Claude를 MCP 서버로 노출

# 서버 기동
claude mcp serve

# (다른 클라이언트 설정 예)
# {
#   "command": "claude",
#   "args": ["mcp", "serve"],
#   "env": {}
# }

이제 Claude Code와 MCP를 통해 터미널 안에서 바로 도구를 부르고, 데이터를 읽고, 팀과 표준 도구 구성을 공유할 수 있습니다. 위의 스코프/보안 원칙만 지키면, LLM 보조 개발환경을 안전하게 팀 차원으로 확장할 수 있습니다. 세팅을 문서화하고, 승인/로깅 체계를 갖추어 지속 가능한 운영을 완성하세요.