MCP Connector Setup

MCP 커넥터 셋업 가이드

개요

Drive·Notion·Higgsfield 3커넥터를 Cowork에 연결하는 단계별 가이드를 제공합니다. 인증 흐름, API 키 입력, 1회 호출 검증, 트러블슈팅까지 셋업 전 과정을 다룹니다.

셋업 완료 체크리스트

Drive·Notion·Higgsfield — 인증 성공 + 1회 호출 성공 (Drive: 폴더 list / Notion: 공유 페이지 read / Higgsfield: 모델 list)

트리거 키워드

MCP 커넥터 연결, Drive 인증, Notion Integration Token, Higgsfield API 키, 3커넥터 설치, computer:// 링크, MAX_PATH 오류, 한글 파일명 오류, OAuth redirect URI

워크플로우

Step 1 — 사전 준비물

커넥터 연결 전에 아래 계정을 미리 생성해 두세요:

• Google 계정 (Drive)
• Notion 계정
• Higgsfield 계정 + 워크스페이스 크레딧 충전

> [HARD] API 키 보안 수칙: API 키는 본인이 직접 발급·보관합니다. 채팅 대화나 공유 문서에 키 원문을 붙여넣지 말고, 커넥터 설정 화면의 API Key 필드에만 입력하세요.

Connector A — Google Drive

목적: Cowork 폴더 마운트 + 파일 접근 (drive.readonly, drive.file 권한)

인증 방법: Cowork 앱 → 커넥터 추가 → Google Drive → OAuth 로그인

필수 권한

• drive.readonly — 파일 읽기
• drive.file — Cowork가 생성한 파일 접근

인증 단계

• Cowork 앱 → 설정 → MCP 커넥터 → Google Drive 선택
• "Google 계정으로 연결" 클릭
• Google OAuth 화면에서 계정 선택 + 권한 허용
• 연결 완료 후 Drive 폴더 list 1회 호출로 검증

1회 호출 검증: 폴더 목록이 응답에 나타나면 성공

Connector B — Notion

목적: 작업 결과물 Notion 페이지 읽기·쓰기

인증 방법: Cowork 앱 → 커넥터 추가 → Notion → OAuth 인증

인증 단계

• Cowork 앱 → 설정 → MCP 커넥터 → Notion 선택
• "Notion으로 연결" 클릭
• Notion OAuth 화면에서 워크스페이스 선택 + 페이지 접근 권한 허용
• 연결 완료 후 공유 페이지 read 1회 호출로 검증

1회 호출 검증: 공유 페이지 내용이 응답에 나타나면 성공

Connector C — Higgsfield

목적: 광고 영상 생성 등 미디어 작업 (이미지·영상 생성 모델 호출)

인증 방법: API 키 방식 (OAuth 아님)

사전 확인 사항

• Higgsfield 워크스페이스 크레딧 충전 여부 확인 (잔액 부족 시 인증은 성공해도 생성 호출이 실패할 수 있음)
• 예상 사용량 가늠: 영상 1편(5-10초) 기준 크레딧 소모량을 미리 확인
• 비용 한도: 워크스페이스 설정에서 사용 한도를 지정해 예상 외 과금 방지

인증 단계

• Cowork 앱 → 설정 → MCP 커넥터 → Higgsfield 선택
• API Key 필드에 발급받은 키 입력 (발급처: higgsfield.ai → API Keys)
• 연결 완료 후 모델 list 1회 호출로 검증

1회 호출 검증: 사용 가능한 모델 목록이 응답에 나타나면 성공

트러블슈팅

T1 — Windows MAX_PATH 260자 초과 오류

증상: Cowork 폴더 마운트 실패, 경로 관련 오류 메시지

원인: Windows 기본 MAX_PATH 260자 제한. 한글 파일명이 포함된 긴 경로에서 자주 발생.

해결 방법

• 폴더를 드라이브 루트 가까운 위치로 이동 (예: C:\cowork\ 또는 D:\cw\)
• 한글 파일명 30자 룰: 폴더명·파일명을 30자 이내로 유지
• 필요 시 Windows Registry로 MAX_PATH 제한 해제 (관리자 권한 필요)

해결이 어려운 경우 (대체 경로): 위 방법으로 해결되지 않으면 로컬 폴더 마운트 대신 Google Drive 커넥터(Connector A)로 파일에 접근하는 임시 경로를 사용할 수 있습니다.

T2 — computer:// 링크 안 열림

증상: Cowork가 제공하는 computer:// 링크를 클릭해도 열리지 않음

해결 방법

• Chrome 시크릿 모드로 재시도
• 브라우저 기본 프로토콜 핸들러 확인 (설정 → 기본 앱 → 링크 처리)
• Cowork 앱 재시작 후 재시도

T3 — OAuth 인증 실패 (Drive·Notion)

증상: OAuth 화면에서 "접근 거부" 또는 redirect 오류

해결 방법

• Chrome 시크릿 모드에서 재시도 (캐시된 세션 충돌 방지)
• Google 계정이 workspace 계정인 경우: 관리자 승인이 필요할 수 있음
• OAuth redirect URI 문제: Cowork 앱 버전 업데이트 후 재시도
• 팝업 차단 해제 확인 (브라우저 설정 → 팝업 허용)

T4 — API 키 인증 실패 (Higgsfield)

증상: "Invalid API key" 또는 "Unauthorized" 오류

해결 방법

• API 키 앞뒤 공백 없이 정확히 복사·붙여넣기 확인
• Higgsfield: 워크스페이스 충전 여부 확인 (잔액 부족 시 인증 실패)
• 키 재발급 후 재시도

슬래시 커맨드 등록 안내

커넥터 셋업을 마친 뒤, 프로젝트 CLAUDE.md에 아래와 같은 슬래시 커맨드를 등록하면 자주 쓰는 스킬을 빠르게 호출할 수 있습니다:

## 슬래시 커맨드

- `/morning-brief` — 아침 브리핑 (commerce-morning-brief)
- `/detail-copy` — 상세페이지 카피 (detail-page-copy)
- `/channel-msg` — 채널 메시지 (commerce-channel-message)

프로젝트 폴더의 CLAUDE.md에 위 블록을 붙여넣어 등록합니다.

사전 점검 체크리스트 (--check 옵션)

사전 준비물 기준으로 3커넥터 가입·인증 상태를 체크하는 옵션입니다.

/mcp-connector-setup --check

출력 예시:

[✅] Google Drive — 계정 확인 완료
[✅] Notion — 계정 확인 완료
[⚠️] Higgsfield — 워크스페이스 크레딧 충전 미확인 (충전 후 재시도)

사용 예시

예시 1

> "Drive MCP 연결하는 방법 알려줘"

→ Connector A (Google Drive) 인증 단계 제공 + 1회 호출 검증 안내

예시 2

> "Windows에서 Cowork 마운트가 안 돼요"

→ T1 (MAX_PATH 오류) 해결 방법 제공 + 대체 경로 안내

출력 형식

• 단계별 인증 가이드 (Markdown)
• 트러블슈팅 해결 방법 (번호 목록)
• --check 옵션: 3커넥터 상태 체크리스트 (.md 파일 저장 가능)

셋업 완료 체크리스트

| 커넥터 | 인증 방법 | 1회 호출 검증 |

|--------|-----------|---------------|

| Google Drive | OAuth (drive.readonly, drive.file) | 폴더 list 응답 |

| Notion | OAuth (워크스페이스 연결) | 공유 페이지 read 응답 |

| Higgsfield | API Key | 모델 list 응답 |

3커넥터 모두 인증 성공 + 1회 호출 성공이면 셋업이 완료된 것입니다.

관련 스킬

• moai-commerce:commerce-morning-brief — 인증 완료 후 매장 데이터 아침 브리핑 + 신규 주문 통합 요약 (주문 요약 모드)
• moai-media:higgsfield-image / moai-media:higgsfield-video — Higgsfield 커넥터 인증 완료 후 이미지·영상 생성

이 스킬을 사용하지 말아야 할 때

• 이미 3커넥터가 모두 연결된 경우 → moai-commerce:commerce-morning-brief 직접 호출 (전체 브리핑 또는 주문 요약 모드)
• MCP 호출 결과물(아침 브리핑·주문 요약) 생성이 목적인 경우 → moai-commerce 스킬 사용
• Cowork 앱 설치 자체가 안 되는 경우 → Cowork 공식 지원 채널 문의 (본 스킬 범위 외)
• 광고 플랫폼 커넥터 (Meta 광고 등) 연결 → moai-marketing:meta-ads-manager 스킬 참조