• 비개발자 기준으로 친절하게.

  .mcp.json

  편집이나 토큰 발급을 처음 해보는 사람도 완주할 수 있어야 한다.
• 묻기 전에 먼저 확인한다. 이미 되어있으면 "이미 됐네요 ✅" 한 줄로 스킵.
• 절대 자동으로 기존 설정을 덮어쓰지 않는다. 충돌 시 사용자에게 묻는다.
• 존댓말 사용. "~했습니다/~할까요?" 체.
• step-by-step, 한 번에 하나씩. 체크리스트 여러 개 한꺼번에 들이밀지 말 것.

AskUserQuestion

• 옵션 A: 이 프로젝트만 (추천) — 현재 디렉토리

  ./.mcp.json

  . 팀이 이 프로젝트를 쓸 때 동일 설정을 공유할 수 있고, 다른 프로젝트에 영향이 없음.
• 옵션 B: 전역 —

  ~/.claude/.mcp.json

  . 어느 프로젝트에서든 동작.

$MCP_PATH

undefined

AskUserQuestion

1. which gh

   체크
2. 없으면:

   GitHub CLI가 없네요. 터미널에서 다음 명령어를 실행해주세요:
   
   macOS:   brew install gh
   Windows: winget install --id GitHub.cli
   Linux:   https://github.com/cli/cli/blob/trunk/docs/install_linux.md 참고
   
   설치 끝나셨나요?

   →

   AskUserQuestion

   (네/아직). 네면

   which gh

   재검증.

3. gh auth status

   체크
4. 로그인 안 돼있으면:

   이제 로그인할게요. 터미널에 이거 치시고, 기본값으로 엔터 엔터 쭉 누르시면 됩니다:
   
   gh auth login
   
   브라우저가 열리고 one-time code 입력하라고 나와요. 완료하셨나요?

   →

   AskUserQuestion

   (네/문제있음). 네면

   gh auth status

   재검증.
5. 성공: "✅ GitHub 로그인 완료: @username"

AskUserQuestion

1. $MCP_PATH

   에 다음 블록을 merge:
   json

   {
     "mcpServers": {
       "linear-server": {
         "type": "http",
         "url": "https://mcp.linear.app/mcp"
       }
     }
   }

2. 병합 규칙: 파일이 없으면 새로 생성. 있으면

   jq

   로

   mcpServers["linear-server"]

   추가 (기존 키 있으면 "덮어쓸까요?" 물어봄).
3. 안내:

   ✅ Linear 설정 추가 완료!
   
   Claude Code를 한 번 재시작해주세요 (Cmd+Q 후 다시 열기).
   재시작 후 Linear에 처음 접근할 때 브라우저가 뜨면 Linear 계정으로 로그인해주세요.

4. 재시작 여부 확인 →

   ToolSearch "+linear"

   로 검증.

AskUserQuestion

Slack은 토큰 발급이 필요해서 5분 정도 걸려요.
브라우저에서 Slack 앱 하나 만들어주셔야 하는데, 제가 단계별로 안내할게요.
준비되셨으면 시작할게요!

👉 https://api.slack.com/apps 열어주세요.
👉 'Create New App' → 'From scratch' 클릭
👉 App Name: `s-skills-mcp` (아무거나 OK)
👉 Pick a workspace: 회사 워크스페이스 선택
👉 'Create App' 클릭

생성 완료하셨어요?

AskUserQuestion

👉 왼쪽 메뉴에서 'OAuth & Permissions' 클릭
👉 페이지 하단의 'User Token Scopes' 섹션으로 스크롤
👉 'Add an OAuth Scope' 버튼을 눌러서 아래 스코프를 **하나씩 추가**해주세요

읽기 계열:
  channels:history, channels:read, groups:history, groups:read,
  im:history, im:read, mpim:history, mpim:read, search:read,
  users:read, users:read.email, usergroups:read, files:read,
  reactions:read, team:read, emoji:read, links:read

쓰기 계열:
  chat:write, files:write, reactions:write, usergroups:write, links:write

(많아 보이지만 미리 넓게 잡아두면 나중에 스킬 추가돼도 재발급할 필요 없어요.)

다 추가하셨어요?

AskUserQuestion

👉 같은 페이지 맨 위로 스크롤해서 'Install to Workspace' 클릭
👉 브라우저 새 탭에서 권한 승인 화면 → 'Allow' 클릭

(주의: 워크스페이스에 따라 관리자 승인이 필요할 수 있어요.
 "요청을 보냈습니다"가 뜨면 관리자한테 승인 요청이 간 거예요. 승인받으시면 계속 진행.)

설치 완료하셨어요?

AskUserQuestion

👉 설치 후 'OAuth & Permissions' 페이지로 돌아가면
👉 상단에 'User OAuth Token' 이라는 필드가 생겨있어요
👉 `xoxp-` 로 시작하는 긴 토큰을 복사해서 여기에 붙여넣어주세요

(이 토큰은 당신의 Slack 계정처럼 동작하니까 깃에 올리거나 공유하지 마세요.)

AskUserQuestion

xoxp-

$MCP_PATH

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "slack-mcp-server"],
      "env": {
        "SLACK_MCP_XOXP_TOKEN": "xoxp-...사용자가_준_값...",
        "SLACK_MCP_ADD_MESSAGE_TOOL": "true"
      }
    }
  }
}

✅ Slack 토큰 저장 완료!

Claude Code를 재시작해주세요. 재시작 후에 Slack MCP가 도구 목록에 나타나면 성공이에요.

ToolSearch "+slack"

• "403 missing_scope" → 누락된 스코프 재추가 후 토큰 재발급 필요
• 관리자 승인 대기 → 승인 받을 때까지 pause
• 토큰이

  xoxb-

  로 시작 → Bot token임,

  xoxp-

  (User) 토큰을 써야 함

AskUserQuestion

1. $MCP_PATH

   에 merge:
   json

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

2. 안내:

   ✅ Notion 설정 추가 완료!
   
   Claude Code를 재시작해주세요.
   재시작 후 Notion MCP에 처음 접근할 때 브라우저가 뜨면 Notion 계정으로 로그인하고
   'Allow access' 눌러주세요. 어떤 페이지에 접근 권한을 줄지 선택하는 화면이 나옵니다.

3. 재시작 확인 →

   ToolSearch "+notion"

   검증.

AskUserQuestion

1. 바이너리 확보 (4곳 탐색 → 없으면 GitHub에서 자동 다운로드):
   bash

   SHIFTEE_BIN=""
   for p in \
     "$HOME/.cache/s-skill-shiftee/shiftee" \
     "$HOME/.claude/skills/s-skill-shiftee/shiftee" \
     "./.claude/skills/s-skill-shiftee/shiftee" \
     "$HOME/.agents/skills/s-skill-shiftee/shiftee"; do
     if [ -x "$p" ]; then SHIFTEE_BIN="$p"; break; fi
   done
   
   if [ -z "$SHIFTEE_BIN" ]; then
     mkdir -p "$HOME/.cache/s-skill-shiftee"
     SHIFTEE_BIN="$HOME/.cache/s-skill-shiftee/shiftee"
     curl -fsSL https://raw.githubusercontent.com/Salesmap-tech/s-skill/main/bin/shiftee \
          -o "$SHIFTEE_BIN" && chmod +x "$SHIFTEE_BIN"
   fi

   curl

   까지 실패한 경우(오프라인/방화벽):

   shiftee 바이너리를 받지 못했어요. 네트워크를 확인하거나 아래 수동 명령을 써주세요:
   
   git clone https://github.com/Salesmap-tech/s-skill.git /tmp/s-skill
   mkdir -p ~/.cache/s-skill-shiftee
   cp /tmp/s-skill/bin/shiftee ~/.cache/s-skill-shiftee/shiftee
   chmod +x ~/.cache/s-skill-shiftee/shiftee

   → 이 분기 스킵.
2. 로그인 상태 확인:
   bash

   [ -f "$HOME/.config/shiftee-cli/config.json" ]

   이미 있으면 "✅ Shiftee 이미 로그인됨" 한 줄로 스킵.
3. 로그인 안내 (이메일/비밀번호가 아니라 브라우저 쿠키 토큰 2개를 붙여넣는 방식임에 주의):

   Shiftee 로그인을 진행할게요. 아래 명령을 터미널에서 직접 실행해주세요:
   
   $SHIFTEE_BIN login
   
   토큰은 브라우저에서 가져옵니다:
   1. shiftee.io에 로그인된 상태에서 F12 → Application(또는 Storage) → Cookies → https://shiftee.io
   2. `shiftee_account_auth_token` 값 복사해서 첫 번째 입력란에 붙여넣기
   3. `shiftee_employee_auth_token` 값 복사해서 두 번째 입력란에 붙여넣기
   
   토큰은 ~/.config/shiftee-cli/config.json (0600)에 저장됩니다. 완료하셨나요?

   →

   AskUserQuestion

   (네/문제있음). 네면

   $SHIFTEE_BIN me

   로 검증.
4. 검증 실패 시 흔한 원인:
   • 토큰 복사할 때 앞뒤 공백·줄바꿈 포함 → 정확한 쿠키 Value 필드만 복사
   • 토큰 만료 (expires_at 지남) → Shiftee 재로그인 후 쿠키 다시 복사
   • Shiftee 로그아웃 상태의 쿠키 → shiftee.io에 먼저 로그인한 뒤 쿠키 조회
   • Python 3 없음 →

     python3 --version

     으로 확인, 없으면

     brew install python

     안내

gh api user --jq .login

mcp__linear-server__list_projects

mcp__slack__channels_list

mcp__notion__...search

$SHIFTEE_BIN me

• 에러 메시지 출력
• 해당 분기의 "흔한 실패" 섹션 참고해서 구체적인 재시도 안내

AskUserQuestion: "기존 $SERVER_NAME 설정이 있네요. 덮어쓸까요?"

Y: 아래로 진행. N: skip.

1. 묻기 전에 체크. 이미 되어있으면 질문하지 않는다.
2. 한 번에 한 질문.

   AskUserQuestion

   은 2~4개 옵션짜리 하나씩.
3. 실패 시 친절 모드로. 에러 메시지 그대로 보여주고, 해석해주고, 다음 액션 제안.
4. 파괴적 작업 금지. 기존

   .mcp.json

   을 덮어쓸 때는 반드시 백업 + 재확인.
5. 비밀키 노출 주의. 토큰은 파일에 쓰되, 출력에는 절대 echo하지 않는다.
6. "스킵" 옵션 항상 제공. 질문마다 "나중에 설정"이 가능해야 한다.