MCP 연결 트러블슈팅

요약

MCP 연결 과정에서 발생한 세 가지 핵심 문제를 분석하고 해결했다. 환경변수 주입 방식 오류, Windows cmd /c 래퍼 누락, 그리고 Claude 내장 커넥터를 먼저 확인하지 않은 순서 문제가 원인이었다.

---

트러블슈팅

문제 1 — settings.local.json 파싱 에러

에러 메시지:

Settings Error
C:\Users\mung9\IdeaProjects\onboarding-automation\.claude\settings.local.json
└ Invalid or malformed JSON
Files with errors are skipped entirely, not just the invalid settings.

원인:
Claude Code가 settings.local.json에 mcpServers 키를 직접 작성하려고 시도했으나, 해당 파일은 mcpServers 키를 지원하지 않아 JSON 구조가 잘못됐다.

해결:
settings.local.json은 오직 env 키 아래에 실제 토큰값만 넣는다.

{
  "env": {
    "GITHUB_TOKEN": "실제_토큰값",
    "SLACK_BOT_TOKEN": "실제_토큰값",
    "SLACK_TEAM_ID": "실제_팀ID"
  }
}

핵심 규칙:

settings.json        → MCP 서버 정의 + ${VAR} 플레이스홀더 (git 커밋 가능)
settings.local.json  → env 키 아래 실제 토큰값만 (git 제외)
                        mcpServers 키는 지원 안 됨

---

문제 2 — Windows cmd /c 래퍼 누락

에러 메시지:

[Warning] [slack] mcpServers.slack: Windows requires 'cmd /c' wrapper to execute npx
[Warning] [google-workspace] mcpServers.google-workspace: Windows requires 'cmd /c' wrapper to execute npx

원인:
Claude가 macOS/Linux 기준의 npx 직접 실행 명령어를 제안했다. Windows에서는 npx를 직접 실행할 수 없고 cmd /c 래퍼가 필요하다.

Claude가 틀린 이유:
훈련 데이터의 MCP 예시가 대부분 macOS/Linux 기준이라 Windows 특수 처리를 놓쳤다. 사용자의 OS를 먼저 확인했어야 했다.

해결:

# 잘못된 방식 (macOS/Linux)
claude mcp add slack -- npx -y @modelcontextprotocol/server-slack

# 올바른 방식 (Windows)
claude mcp add slack -- cmd /c npx -y @modelcontextprotocol/server-slack

교훈:
AI가 제안하는 명령어가 내 OS에서 동작하는 형태인지 항상 먼저 확인한다. Windows라면 npx 관련 명령어는 cmd /c 래퍼가 필요하다.

---

문제 3 — Claude 내장 커넥터를 몰라서 불필요한 API 키 발급

상황:
Gmail, Google Calendar 연결을 위해 Google Cloud Console에서 OAuth 앱 등록, Client ID, Client Secret, Refresh Token을 발급하려 했다.

실제로 필요했던 것:
Claude Code에 이미 내장 커넥터가 있어서 Google 로그인만 하면 됐다.

claude.ai Gmail            - Needs authentication → 클릭 → Google 로그인
claude.ai Google Calendar  - Needs authentication → 클릭 → Google 로그인

API 키 발급, Google Cloud Console 설정, .env 작성 전혀 불필요했다.

---

MCP 연결 전 올바른 순서 — 체크리스트

앞으로 어떤 MCP든 연결하기 전에 이 순서로 확인한다.

1단계: Claude 내장 커넥터 있는지 먼저 확인
           ↓ 있으면
       /mcp → Needs authentication 클릭 → 로그인만
           ↓ 없으면
2단계: 공식 HTTP MCP 엔드포인트 있는지 확인
           ↓ 있으면
       claude mcp add --transport http 이름 https://엔드포인트
           ↓ 없으면
3단계: npx 패키지로 로컬 설치 (이때만 API 키 필요)

MCP	종류	방법
Gmail	Claude 내장 커넥터	/mcp → 로그인
Google Calendar	Claude 내장 커넥터	/mcp → 로그인
GitHub	공식 HTTP 엔드포인트	--transport http + token
Playwright	npx 로컬	API 키 불필요
Firecrawl	npx 로컬	Firecrawl API 키 필요
Context7	npx 로컬	API 키 불필요

---

팀 Plugin 배포 시 문서화 방법

팀원과 공유하는 Plugin README에는 이 두 섹션을 명확하게 나눠서 작성한다.

## MCP 연결 방법

### Connector로 연결 (API 키 불필요 — 개인 계정 서비스)
1. Claude Code 실행 후 /mcp 입력
2. 아래 항목에서 "Needs authentication" 클릭 후 본인 계정 로그인:
   - claude.ai Gmail
   - claude.ai Google Calendar

### .env로 연결 (API 키 필요 — 팀 공용 또는 커넥터 없는 서비스)
1. 프로젝트 루트에 .env 파일 생성 (.gitignore에 추가)
2. 아래 값 채우기:
   GITHUB_TOKEN=     ← 본인 GitHub PAT
   SLACK_BOT_TOKEN=  ← 팀 Slack 앱 토큰 (팀장에게 요청)
   SLACK_TEAM_ID=    ← 팀 Slack 워크스페이스 ID
3. settings.local.json의 "env" 키 아래에 실제값 작성

한 줄 기준:

개인 계정 서비스 (Gmail, Calendar) → Connector
팀 공용 또는 Connector 없는 서비스 → .env

---

회고

세 가지 문제 모두 "먼저 확인했다면 막을 수 있었던" 문제들이다.
API 키 설정에 들인 시간을 Claude 내장 커넥터 존재 여부를 먼저 확인하는 것으로 대부분 줄일 수 있다.
AI가 제안하는 명령어는 내 OS와 환경에 맞는지 항상 검증하는 습관이 필요하다.