MCP · 커넥터 기기 이관 가이드 (2026-08-07)

목적: vhagar(kontology)에만 있는 MCP·커넥터 환경을 프레데터 및 다른 기기에서도 쓰게 만들기

작성 근거: 2026-08-07 vhagar 실측 (claude mcp list / ~/.claude.json / 토큰 파일 구조 / Tailscale 도달성)

0. 결론 먼저

1. 커넥터는 두 종류다 — 절반은 할 일이 없다

이게 혼동의 핵심입니다.

지금 vhagar에서 claude.ai 커넥터가 꺼져 있는 이유

claude mcp list 실행 시 나오는 경고입니다.

claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set and takes precedence over your claude.ai login

ANTHROPIC_API_KEY 환경변수가 claude.ai 로그인보다 우선 적용되어 조직 커넥터가 로드되지 않습니다.

→ 프레데터에서 Gmail/Drive/Airtable 커넥터를 쓰려면 그 기기에서 ANTHROPIC_API_KEY를 unset 하십시오. 이것 하나로 수십 개 커넥터가 붙습니다. (셸 프로필에 박혀 있으면 거기서도 제거)

2. Google Workspace MCP — 재인증 없이 이관

왜 재인증이 필요 없는가

토큰 파일을 열어 구조를 확인한 결과입니다.

~/.google_workspace_mcp/credentials/admin@bizdirect.co.kr.json
  keys : client_id, client_secret, refresh_token, token, token_uri, scopes, expiry
  has_refresh_token : True

refresh_token에 client_id / client_secret까지 한 파일에 모두 들어 있고,

OAuth 클라이언트가 Desktop(installed) 타입이라 IP 제한이 없습니다.

→ 파일만 복사하면 새 기기가 알아서 토큰을 갱신합니다.

💡 기존 메모에 기록된 "헤드리스 OAuth = localhost 콜백 URL 복사, SSH 순환터널 함정" 은

최초 1회 인증에만 해당합니다. 그 고통의 산출물이 refresh_token이므로

두 번째 기기부터는 그 과정을 통째로 건너뜁니다.

⚠️ expiry가 과거 시각으로 보여도 정상입니다. 그건 access token 만료시각이고

refresh_token으로 자동 재발급됩니다. 이걸 보고 "재인증해야겠다"고 판단하면 헛수고합니다.

복사할 파일 2개

등록 명령

claude mcp add workspace-mcp -s user \
  -e GOOGLE_CLIENT_SECRET_PATH=$HOME/.config/workspace-mcp/client_secret.json \
  -e USER_GOOGLE_EMAIL=admin@bizdirect.co.kr \
  -e OAUTHLIB_INSECURE_TRANSPORT=1 \
  -- uvx workspace-mcp

툴 프리픽스 mcp__workspace-mcp__*, 100+ 툴(Gmail·Drive·Docs·Sheets·Slides·Forms·Tasks·Calendar·Chat·Contacts·AppsScript). 툴 노출에는 세션 재시작이 필요합니다.

3. kontology 호스팅 MCP — URL을 반드시 바꿔야 함

여기가 기기 이관에서 가장 잘 틀리는 지점입니다.

vhagar의 설정은 http://127.0.0.1:8766/... 인데, 이걸 그대로 복사하면 프레데터가 자기 자신을 가리켜 연결에 실패합니다.

두 서버 모두 0.0.0.0에 바인딩되어 있어 Tailscale FQDN으로 접근 가능함을 실측했습니다(둘 다 HTTP 200 응답).

claude mcp add maester -s user -t http \
  http://kontology.tail8a76b2.ts.net:8766/sk-maester-2026/mcp

claude mcp add meta-ads -s user -t http \
  http://kontology.tail8a76b2.ts.net:8767/sk-meta-ads-83942425d27115134d3ac4308675b9cf/mcp

maester는 https://kontology.tail8a76b2.ts.net/sk-maester-2026/mcp (Funnel 경유)도 동작 확인됨.

4. 프레데터 세션에 붙일 프롬프트 (복붙용)

이 기기(프레데터/tlswkehd-laptop)에 Claude Code MCP를 vhagar(kontology)와 맞춰줘.

1) claude.ai 커넥터 살리기
   - env에 ANTHROPIC_API_KEY가 있으면 unset 해야 claude.ai 커넥터(Gmail/Drive/
     Airtable/Notion 등)가 로드된다. 확인하고 알려줘. (셸 프로필에 박혀 있으면 그것도)

2) Google Workspace MCP — 재인증 하지 마라. 자격증명은 kontology에서 복사해온다.
   필요한 파일 2개:
     ~/.config/workspace-mcp/client_secret.json
     ~/.google_workspace_mcp/credentials/admin@bizdirect.co.kr.json
   kontology(100.110.33.98, user=tlswkehd)에서 scp로 가져오고 권한 600 유지.
   디렉터리는 미리 만들고 credentials/는 700.
   그다음 등록:
     claude mcp add workspace-mcp -s user \
       -e GOOGLE_CLIENT_SECRET_PATH=$HOME/.config/workspace-mcp/client_secret.json \
       -e USER_GOOGLE_EMAIL=admin@bizdirect.co.kr \
       -e OAUTHLIB_INSECURE_TRANSPORT=1 \
       -- uvx workspace-mcp
   주의: 토큰의 expiry가 과거로 보여도 정상이다(그건 access token). refresh_token이
   있으니 재인증 필요 없다. OAuth 흐름 타지 마라.

3) kontology 호스팅 MCP는 반드시 Tailscale FQDN으로 등록 (127.0.0.1 금지):
     claude mcp add maester -s user -t http \
       http://kontology.tail8a76b2.ts.net:8766/sk-maester-2026/mcp
     claude mcp add meta-ads -s user -t http \
       http://kontology.tail8a76b2.ts.net:8767/sk-meta-ads-83942425d27115134d3ac4308675b9cf/mcp

4) 전제조건 확인: uv(uvx), node/npx 설치 여부. 없으면 설치.

5) 끝나면 claude mcp list로 연결상태 보여주고, workspace-mcp는
   list_gmail_labels 같은 읽기 툴 1회 실호출로 실제 인증까지 검증해줘.
   (세션 재시작해야 툴이 노출된다)

시크릿 값은 출력하지 마라. 파일 경로·권한만 보고해라.

5. 주의사항

5-1. 자격증명 취급

admin@bizdirect.co.kr.json 은 Gmail·Drive 전권 자격증명입니다.

• 반드시 Tailscale scp로만 전송 (카톡·메일·클라우드 업로드 금지)
• 양쪽 모두 파일 600, 디렉터리 700 유지
• 기기가 늘수록 유출면이 늘어난다는 점은 감수하는 트레이드오프

5-2. 개인 지메일은 이 클라이언트로 불가

OAuth 클라이언트가 org_internal 제한이라 개인 지메일(shinws8908)은 동의 자체가 거부됩니다

(authError=org_internal, 2026-08-03 실측).

개인 캘린더/드라이브가 필요하면 개인 GCP 프로젝트에 별도 Desktop 클라이언트를 만들어야 하며,

동의화면을 External + 프로덕션 게시까지 해야 합니다. "테스트" 상태로 두면 refresh token이 7일 만에 만료되어 조용히 멈춥니다.

참고 — vhagar 현재 MCP 목록 (14개, user scope)

연결 실패 3종(chrome-devtools 로컬 venv 경로, vercel, tavily)은 이관 대상에서 제외하는 것을 권장합니다.

플러그인 버전(plugin:chrome-devtools-mcp)이 정상 동작 중이라 중복입니다.