Claude 연동을 사용하기까지의 절차입니다. GeckoFlag 관리자가 기능을 켜고 사용자를 허가한 뒤, 사용자가 API 토큰을 만들어 Claude 데스크톱 앱에 확장 프로그램을 추가합니다.

시작하기 전에

  • GeckoFlag v1.11.0 이상 ― HTTPS로 공개되어 있어야 합니다.
  • GeckoFlag 관리자 계정 ― STEP 1·STEP 2의 설정은 관리자만 할 수 있습니다.
  • Claude 데스크톱 앱(Windows·macOS) ― Claude 요금제 계정으로 로그인해 둡니다. 확장 프로그램에 필요한 Node.js는 앱에 포함되어 있으므로 따로 설치할 필요가 없습니다.
  • GeckoFlag 확장 프로그램 파일(.mcpb) ― Claude 데스크톱 앱에 추가하는 파일입니다. GeckoFlag 구매 후 받을 수 있는 다운로드 파일에 GeckoFlag 본체, 매뉴얼과 함께 포함되어 있습니다.

화면은 영어로 표시한 예입니다(GeckoFlag와 Claude 모두 표시 언어에 따라 항목 이름이 바뀝니다). Claude 데스크톱 앱 화면은 2026년 10월 기준이며, Anthropic의 사정에 따라 바뀔 수 있습니다.

전체 흐름

  1. 관리자가 GeckoFlag 설정 화면에서 Claude 연동을 켭니다
  2. 관리자가 사용할 사람마다 “Claude 연동(API) 이용 허용”을 켭니다
  3. 사용자가 프로필 화면에서 API 토큰을 만들고 복사합니다
  4. 사용자가 Claude 데스크톱 앱에 확장 프로그램을 설치합니다
  5. 확장 프로그램에 GeckoFlag URL과 API 토큰을 입력합니다
  6. Claude에게 요청해 연결되었는지 확인합니다

STEP 1　Claude 연동 켜기(관리자)

  1. GeckoFlag에 관리자로 로그인하고 왼쪽 메뉴의 “설정”(Settings)을 엽니다.
  2. “Claude 연동”(Claude Integration) 카드의 “편집”(Edit)을 누릅니다.
GeckoFlag 설정 화면. “Claude Integration” 카드(Work from the Claude desktop app)가 빨간 테두리로 표시되어 있다
  1. “Claude 연동 사용”(Enable Claude integration)을 켭니다. 초기 상태는 꺼져 있습니다.
  2. Claude가 이슈 생성·업데이트나 댓글 작성까지 하게 하려면 “쓰기 허용”(Allow writing)도 켜고 저장합니다.
  • 쓰기를 허용하지 않는 경우 ― 모든 토큰이 읽기 전용이 됩니다. “읽기 및 쓰기”로 만든 토큰도 검색·조회에만 사용할 수 있습니다.
  • 이용 현황 확인 ― 같은 화면에서 이용을 허가한 사용자 수와 생성된 API 토큰 수를 확인할 수 있습니다.
GeckoFlag의 Claude 연동 설정 화면. 상태 “Enabled”와 “Enable Claude integration”, “Allow writing (create and update issues, post comments)” 두 체크 상자가 빨간 테두리로 표시되어 있다

STEP 2　사용할 사용자 허가하기(관리자)

Claude 연동은 관리자가 허가한 사용자만 사용할 수 있습니다(관리자 본인도 허가가 필요합니다).

  1. 왼쪽 메뉴의 “사용자”(Users)를 열고 대상 사용자의 “편집”을 누릅니다.
  2. “Claude 연동(API) 이용 허용”(Allow Claude integration (API))을 켜고 “업데이트”(Update)를 누릅니다.
GeckoFlag 사용자 편집 화면. 왼쪽 메뉴의 “Users”와 “Allow Claude integration (API)” 체크 상자가 빨간 테두리로 표시되어 있다
  • “AI로 작성”과는 별도 설정 ― 바로 위의 “AI 등록 허용”(Allow AI-assisted registration)은 AI로 작성의 허가입니다. Claude 연동만 사용한다면 켤 필요가 없습니다.
  • 허가를 해제하면 ― 해당 사용자의 API 토큰이 모두 삭제되어 Claude에서 사용할 수 없게 됩니다.

STEP 3　API 토큰 만들기

여기서부터는 Claude 연동을 사용하는 사람이 각자 진행합니다.

  1. 왼쪽 메뉴의 “프로필”(Profile)을 열고 “API 토큰(Claude 연동)”(API Tokens) 항목을 표시합니다.
  2. “확장 프로그램에 입력할 URL”(URL to enter in the extension)을 메모해 둡니다. STEP 5에서 사용합니다.
  3. “토큰 이름”(Token name)에 어느 PC에서 사용하는지 알 수 있는 이름을 입력합니다(예: 업무용 PC의 Claude).
  4. “유효 기간”(Expires in)을 30일·90일·365일·무기한 중에서 선택합니다(기본값은 90일).
  5. “권한”(Permission)을 선택하고 “토큰 생성”(Create token)을 누릅니다.
GeckoFlag 프로필 화면의 “API Tokens (Claude Integration)” 항목. 왼쪽 메뉴의 “Profile”과 Token name·Expires in·Permission 입력란이 빨간 테두리로 표시되어 있다
  • 권한 선택 방법 ― 검색·조회만 한다면 “읽기”(Read only), 이슈 생성·업데이트나 댓글 작성까지 하게 하려면 “읽기 및 쓰기”(Read and write)를 선택합니다. 쓰기는 필요할 때만 선택하세요.
  • 토큰은 만든 직후 한 번만 표시됩니다.반드시 그 자리에서 복사하세요. 비밀번호처럼 다른 사람이 알지 못하도록 관리하세요.
  • 만들 수 있는 개수 ― 1인당 5개까지 만들 수 있습니다. 더 이상 쓰지 않는 토큰은 같은 화면에서 언제든지 삭제할 수 있습니다.
  • 비밀번호를 변경하면 ― 해당 사용자의 토큰이 모두 삭제됩니다. 다시 만들어 확장 프로그램에 새로 입력하세요.

STEP 4　Claude에 확장 프로그램 설치하기

  1. Claude 데스크톱 앱을 열고 왼쪽 아래의 계정 이름을 눌러 “설정”(Settings)을 엽니다.
Claude 데스크톱 앱 홈 화면. 왼쪽 아래 계정 메뉴가 열려 있고 “Settings”가 빨간 테두리로 표시되어 있다
  1. 왼쪽 메뉴의 “확장 프로그램”(Extensions)을 엽니다.
  2. GeckoFlag 확장 프로그램 파일(.mcpb)을 이 화면에 드래그 앤 드롭합니다. “고급 설정”(Advanced settings)의 “확장 프로그램 설치”에서 파일을 선택하거나 파일을 더블클릭해도 설치할 수 있습니다.
Claude 설정 화면의 “Extensions”. 아직 확장 프로그램이 없으며 “Advanced settings” 버튼과 “Drag .MCPB or .DXT files here to install” 안내가 표시되어 있다
  1. GeckoFlag 확장 프로그램 설명이 표시되면 내용을 확인하고 “설치”(Install)를 누릅니다.
GeckoFlag 확장 프로그램 설치 화면. 확장 프로그램 설명과 주의 문구가 표시되어 있고 오른쪽 위의 “Install” 버튼이 빨간 테두리로 표시되어 있다

설치 화면에는 “확장 프로그램에 PC 접근을 허용한다”, “개발자 정보는 Anthropic이 확인한 것이 아니다”라는 Claude의 표준 주의 문구가 표시됩니다. GeckoFlag 확장 프로그램은 입력한 GeckoFlag URL과만 통신하며, 파일 저장은 Gantt 차트 Excel 내보내기에만 사용합니다.

STEP 5　연결 대상과 토큰 설정하기

  1. 설치하면 설정 화면(Configure)이 열립니다. 다음 항목을 입력하고 “저장”(Save)을 누릅니다.
GeckoFlag 확장 프로그램 설정 화면. GeckoFlag URL(필수), API token(필수), Export folder 입력란과 “Cancel”, “Save” 버튼이 있다
항목입력할 내용
GeckoFlag URL
(필수)		STEP 3에서 메모한 “확장 프로그램에 입력할 URL”(예: https://pm.example.com). https://로 시작하는 URL이어야 합니다.
API token
(필수)		STEP 3에서 복사한 API 토큰(gfk_ 로 시작하는 문자열). 마스킹되어 저장됩니다.
Export folder
(선택)		Gantt 차트 Excel 파일의 저장 위치. 비워 두면 “다운로드” 폴더에 저장됩니다.
  1. “확장 프로그램” 목록에 “GeckoFlag”가 표시되면 설치가 완료된 것입니다. 확장 프로그램이 켜져 있는지 확인하세요. 설정을 바꾸고 싶을 때는 “구성”(Configure)에서 다시 열 수 있습니다.
Claude 설정 화면의 “Extensions”. “Installed on your computer”에 “GeckoFlag”가 표시되어 있고 “Configure” 버튼이 있다
  • 쓰기 전에 확인하고 싶은 경우(권장) ― 같은 화면에서 GeckoFlag 확장 프로그램을 열고 이슈 생성·업데이트 등의 쓰기 작업을 “매번 확인”으로 해 두면, Claude가 실행하기 전에 반드시 확인을 요청합니다.

STEP 6　연결 확인하기

  1. Claude에서 새 대화를 열고 “GeckoFlag에 연결되어 있는지 확인해 줘”라고 요청합니다.
  2. Claude가 토큰 소유자의 이름, GeckoFlag 버전, 쓰기 가능 여부를 답하면 설정이 완료된 것입니다.

이제 “내가 담당이고 이번 주가 마감인 이슈를 알려 줘”처럼 평소 말투로 요청하기만 하면 됩니다. 요청 예시는 Claude 연동 페이지를 참고하세요.

문제가 생겼을 때

대부분의 경우 Claude가 대화 중에 원인과 해결 방법을 설명합니다. 자주 있는 예는 다음과 같습니다.

  • Claude가 GeckoFlag를 사용하지 않음 ― 확장 프로그램이 꺼져 있거나 설치되지 않았습니다. 설정의 “확장 프로그램”에서 GeckoFlag를 켜고 대화를 다시 여세요.
  • API를 찾을 수 없음(404) ― Claude 연동이 꺼져 있거나, GeckoFlag 버전이 오래되었거나, URL이 잘못되었습니다. 관리자 설정, GeckoFlag 버전, 입력한 URL을 확인하세요.
  • 토큰이 거부됨(401) ― 토큰이 잘못되었거나, 유효 기간이 지났거나, 삭제되었을 수 있습니다(비밀번호를 변경해도 삭제됩니다). 프로필 화면에서 다시 만들어 확장 프로그램에 새로 입력하세요.
  • 이용이 허가되지 않음 ― 관리자가 사용자 편집 화면에서 “Claude 연동(API) 이용 허용”을 켜야 합니다.
  • 쓸 수 없음(403) ― “읽기” 토큰을 사용하고 있거나 사이트의 “쓰기 허용”이 꺼져 있습니다. “읽기 및 쓰기” 토큰을 만들거나 관리자에게 허용을 요청하세요.
  • 이슈나 프로젝트를 찾을 수 없음 ― 키가 잘못되었거나 해당 프로젝트의 멤버가 아닙니다. 키를 확인하거나 소유자에게 멤버 추가를 요청하세요.
  • 리디렉션됨 ― http와 https, www 유무 등이 다릅니다. 브라우저에서 열었을 때의 최종 URL을 입력하세요.
  • 사이트에서 거부됨 ― GeckoFlag의 IP 주소 접근 제한이 API에도 적용되고 있습니다. 허용된 위치에서 사용하거나 관리자에게 허용 범위 재검토를 요청하세요.
  • 횟수 제한(429) ― 토큰 1개당 1분에 60회까지입니다. 잘못된 토큰이 계속된 경우에는 최대 15분 정도 기다린 뒤 다시 시도하세요.
  • 응답 없음 ― 서버가 느리거나 중지되었을 수 있습니다. 쓰기 작업이라면 이미 저장되었을 수 있으므로 GeckoFlag 화면에서 확인한 뒤 다시 시도하세요.
  • Apache 서버에서 401이 계속됨 ― 보통은 자동으로 회피됩니다. 계속된다면 GeckoFlag의 webroot/.htaccess가 최신인지 확인하세요.
“Claude 연동”으로 돌아가기