AI 커넥터 (Claude 연결)

타이거빔 프로젝트에 외부 AI 비서를 직접 연결하는 기능입니다. 연결 방법은 두 가지입니다.

AI는 판단하지 않고 돕습니다. 조회·요약·초안 작성까지가 AI의 역할이고, 최종 판단·게시·책임은 사람에게 있습니다. (10. AI 검토와 같은 원칙)

1. 원격 커넥터 — Claude에 주소로 연결

• 무엇: 타이거빔은 MCP(Model Context Protocol) 표준 원격 커넥터를 제공합니다. Claude에 주소 하나를 입력하고 타이거빔 계정으로 로그인하면 연결됩니다. 설치하거나 명령어·설정 파일을 준비할 필요가 없습니다.
• 누가: 조회(프로젝트·도면·마크업 목록)는 요금제와 무관합니다(무료 포함). 본인이 소유자·관리자(admin) 인 프로젝트가 있는 계정이면 연결할 수 있습니다. 연결하면 내가 관리하는 프로젝트가 자동으로 연결됩니다(개인 계정 단위). 마크업 추가는 API 접근이 있는 read_write 플랜에서만 동작합니다 — 무료·read 전용 플랜 계정도 연결 자체는 되지만, 마크업 추가를 시키면 Claude가 권한 오류를 알려줍니다.

커넥터 주소

https://app.tigerbeam.co.kr/api/mcp

연결하기 (Claude)

1. Claude(데스크톱 앱 또는 claude.ai 웹)에서 설정 → 커넥터를 엽니다.
2. 커스텀 커넥터 추가 를 누르고 위 주소를 붙여넣습니다.
3. 타이거빔에 연결 로그인 화면이 열립니다. "AI(Claude)가 내 프로젝트에 접근하도록 허용하려면 로그인하세요." 이메일·비밀번호를 입력하고 로그인하고 연결 허용 을 누릅니다.
4. Claude로 자동 복귀하면 연결이 끝납니다.

연결 확인: 대화창에 이렇게 물어보세요.

"타이거빔에서 내 프로젝트 목록 보여줘"

내가 관리하는 프로젝트가 나오면 성공입니다.

📷 [스크린샷: Claude 커스텀 커넥터 추가 → 타이거빔 로그인 → 프로젝트 목록 확인]

지금 제공되는 범위

• 원격 커넥터는 CLI 와 같은 도구 목록(이슈·RFI·제출물·변경지시·견적·회의·작업일보·보고서 조회·작성 포함)을 쓰되, 연결한 토큰에 허용된 도구만 보여 줍니다. Claude 원격 커넥터로 연결하면 프로젝트·도면·마크업·변경사항·영향·조치·결정 조회, 프로젝트 기본 정보·태그 목록, 마크업 추가·비공개 마크업 삭제(12개)가 보입니다. 멤버·검측·RFI 초안 등 그 외 도구는 아래 ② CLI 연결에서 씁니다. (도면 파일 업로드·다운로드처럼 PC의 파일을 다루는 도구는 CLI 에만 있습니다.)
• 조회 도구는 요금제와 무관하게 동작합니다. 마크업 추가는 read_write 플랜의 계정에서만 성공합니다 — 무료·read 전용 플랜 계정은 연결은 되지만 추가 시도 시 권한 오류가 돌아옵니다.

알아둘 것

• 연결하면 프로필 · 설정 → API 토큰 · Agent 목록에 Claude 원격 커넥터 라는 Agent와 토큰이 자동으로 생깁니다. 정상 동작입니다. 연결을 끊으려면 여기서 토큰을 폐기하거나 Claude의 커넥터 설정에서 제거하면 됩니다.
• 연결은 30일 후 만료됩니다. 만료되면 Claude에서 다시 로그인하세요.
• 재연결을 반복해 "API 키 발급 한도" 오류가 나면, 프로필 · 설정 → API 토큰 · Agent에서 쓰지 않는 기존 토큰을 폐기하세요.
• 마크업 추가 권한(read_write 플랜)은 연결하는 그 순간의 플랜으로 정해집니다. 이미 연결된 상태에서 플랜을 업그레이드해도 기존 연결은 이전 권한 그대로입니다 — 업그레이드 후 마크업 추가가 안 되면, Claude의 커넥터 설정에서 타이거빔 커넥터를 한 번 끊었다가 다시 연결하세요.

다른 AI 앱

Hermes Agent 연결

Hermes Agent 는 로그인 창 대신 API 토큰으로 원격 커넥터에 붙습니다.

1. 프로필 → 연동 → API 토큰 · Agent 에서 Agent 를 만들고 프로젝트를 부여한 뒤 토큰을 발급합니다. 권한 표에서 AI에게 맡길 영역만 고릅니다(빨간 칸 = 승인·삭제·기록 확정은 필요할 때만).
2. 발급 창의 Hermes Agent에 연결 에서 두 가지를 복사합니다.

• 설정 → ~/.hermes/config.yaml 의 mcp_servers: 아래에 붙여넣습니다.

     mcp_servers:
       tigerbeam:
         url: "https://app.tigerbeam.co.kr/api/mcp"
         headers:
           Authorization: "Bearer ${TIGERBEAM_TOKEN}"
         timeout: 120
         connect_timeout: 30

• .env 줄 → ~/.hermes/.env 에 TIGERBEAM_TOKEN=… 한 줄로 넣습니다. 토큰은 설정 파일이 아니라 이 파일에만 남습니다(Hermes 가 ${TIGERBEAM_TOKEN} 을 여기서 채웁니다).

1. 터미널에서 hermes mcp test tigerbeam 으로 연결을 확인합니다. 보이는 도구는 토큰에 준 권한만큼입니다.

프로필별로 따로 쓰려면 그 프로필 폴더의 config.yaml·.env 에 같은 내용을 넣습니다. 토큰을 회수하려면 타이거빔에서 그 토큰을 폐기하면 즉시 끊깁니다.

2. CLI 연결 — Claude Desktop에서 전체 도구 쓰기

PC의 Claude Desktop에 타이거빔 CLI를 연결하면 도구 전체(프로젝트·도면·마크업·멤버·변경사항 조회, 도면 다운로드·업로드, 마크업 추가, 검측 입력, 이슈·RFI·제출물·변경지시·견적·회의·작업일보·보고서 조회·작성·승인, 채팅, 멤버 초대, 공유·외부 링크, 태그·그룹, 알림 등)를 쓸 수 있습니다. 실제로 쓸 수 있는 도구는 토큰을 만들 때 체크한 권한(스코프)에 따라 정해집니다.

API 토큰(PAT) 발급 — 5단계

모든 토큰에는 Agent라는 이름표가 붙고, Agent는 권한을 부여한 프로젝트만 접근합니다(deny-by-default).

1. 계정 메뉴 → 프로필 · 설정 → API 토큰 · Agent 패널.
2. Agent 생성 — 이름을 붙입니다(예: my-laptop-cli). "모든 PAT는 Agent에 바인딩됩니다. Agent를 만들고 접근할 프로젝트를 부여하세요."
3. Agent를 선택하고 프로젝트 접근 권한 에서 프로젝트 선택 → 권한 부여. (프로젝트 권한은 그 프로젝트의 소유자만 부여할 수 있습니다.)
4. 토큰 발급: 토큰 이름 · Agent · 권한 범위 (scope)(기본은 읽기 3종: project:read·sheet:read·markup:read) · 만료 기간(30일/90일) 선택 → 발급.
5. 새 API 토큰 창에서 토큰을 즉시 복사합니다. "이 토큰은 지금 한 번만 표시됩니다. 지금 복사해 안전한 곳에 보관하세요 — 다시 볼 수 없습니다."

요금제: 발급은 요금제에 API 접근이 있어야 합니다 — Team은 읽기 전용 scope만, 쓰기 scope(sheet:write·markup:write 등)는 상위 플랜이 필요합니다. 발급이 잠겨 있으면 "이 요금제는 API 토큰 발급을 지원하지 않습니다"류 안내가 표시됩니다.

Claude Desktop 원클릭 연결

토큰 발급 직후 같은 창의 Claude Desktop에 연결 섹션에서 다음과 같이 설정합니다.

1. 설정 복사 버튼을 누릅니다. 토큰·주소가 이미 채워진 설정(JSON) 전체가 복사됩니다.
2. 아래 경로의 파일을 열어 붙여넣습니다(파일이 없으면 새로 만드세요):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Claude Desktop을 완전히 종료했다가 다시 엽니다. 도구 목록에 tigerbeam 도구들이 나타납니다.

• 주의: "이 방법은 PC에 Node.js가 설치돼 있어야 합니다. 없으면 nodejs.org에서 먼저 설치하세요." 스니펫에는 방금 발급된 토큰 평문이 들어 있으니 채팅이나 메일로 공유하지 마세요. 창을 닫으면 같은 스니펫은 다시 볼 수 없습니다(분실 시 재발급).

📷 [스크린샷: 토큰 발급 모달 — 1회 표시 토큰 + Claude Desktop에 연결(설정 복사)]

토큰 관리

• 발급된 토큰 목록에서 상태(활성/폐기됨/만료됨)를 확인하고, 폐기 하면 즉시 접근을 차단합니다.
• Agent를 삭제하면 연결된 토큰·프로젝트 권한도 삭제됩니다. 용도별로 Agent를 나누면(노트북용·자동화용) 회수하기 쉽습니다.

3. 보안·권한

• 연결하려면 타이거빔에 로그인하거나 유효한 토큰을 제시해야 합니다. 둘 다 없으면 어떤 데이터도 열리지 않습니다.
• AI·Agent는 deny-by-default입니다. 명시적으로 권한을 부여한 프로젝트만 보입니다. 다른 사람의 프로젝트나 권한 밖 프로젝트는 보이지 않습니다.
• AI는 시킨 일을 바로 실행합니다. 토큰에 쓰기 권한을 주면 이슈·RFI를 만들고, 답하고, 상태를 바꾸고, 댓글을 다는 일이 초안 단계 없이 즉시 반영됩니다. 기록의 작성자는 토큰 주인이고, 그 기록이 AI(에이전트)로 만들어졌다는 표시가 함께 남습니다.
• AI는 토큰 주인이 화면에서 할 수 있는 일까지만 합니다. 주인이 뷰어인 프로젝트에서는 읽기만 되고, 이슈·RFI 삭제는 프로젝트 소유자의 토큰으로만 됩니다. 요금제가 read 로 바뀌면 이미 발급한 토큰으로도 쓰기가 막힙니다.
• 승인·삭제 권한은 따로 체크해야 켜집니다. 제출물 검토 제출·최종 판정(submittal:approve), 변경지시 승인(change_order:approve), 견적 낙찰(rfq:approve)·마크업 게시·검토(markup:approve)와 각 영역의 삭제(issue:delete·rfi:delete·markup:delete·submittal:delete·change_order:delete·rfq:delete 등)는 발급 화면에서 따로 골라야 합니다. 삭제는 되돌릴 수 없으니 필요할 때만 주세요.
• 밖으로 여는 권한도 따로 체크합니다. 멤버 초대·역할 변경·내보내기(member:write, 프로젝트 소유자만), 도면 공유 링크(share:write), 외부 게스트 링크(external:write)는 기본으로 꺼져 있습니다. AI는 초대·링크 메일을 보내지 않고 링크 주소만 돌려주니, 받은 링크를 직접 전달하세요.
• 공개 범위가 제한된 회의록은 토큰 주인이 볼 수 있는 것만 AI에게 보입니다. 작업일보·점검 기록은 주인이 쓴 것만 고치거나 제출할 수 있고, 제출하면 잠깁니다. 보고서 발행은 project:write 권한으로 됩니다.
• AI가 한 일도 사람이 한 것과 같은 알림을 냅니다. 예를 들어 제출물의 볼·검토자·상태를 바꾸면 관련 담당자에게 알림(설정에 따라 이메일)이 갑니다.
• RFI 답변 초안·알림 계획·영향 제안 도구는 지금처럼 검토 대기 초안으로 저장합니다. 마크업 게시·검토·수정·삭제는 주인이 화면에서 할 수 있는 범위(뷰어는 게시 불가, 남의 마크업은 소유자만 삭제)에서 즉시 반영됩니다.
• 모델·도면 미리보기: 「B1 보 400x600 → 400x700」처럼 말하면 프로젝트의 현재 판 MIDAS MGT 모델·DXF 구조 도면에서 그 부재를 찾아 단면 치수·층별 영향 요소 수·도면 글자·구름표·개정 행이 어떻게 바뀌는지 보여 줍니다. ★파일은 바꾸지 않습니다★ — 새 판 저장은 변경지시 화면의 「확인 — 새 판 저장」에서 사람이 합니다. 원격 커넥터에서는 파일당 20MB 까지, CLI 연결에서는 50MB 까지 봅니다.
• 만든 기록은 수정도 됩니다: 회의록·회의 과업, 작성 중인 견적 요청(품목 포함), 내가 보낸 채팅 메시지, 채널 이름·주제·보관, 태그·그룹 이름. 권한은 화면과 같습니다(회의·채널은 소유자·편집자, 메시지는 보낸 사람만, 발송한 견적은 못 고침).
• AI 도구가 아직 없는 일: 도면·프로젝트 삭제(파일 정리가 함께 필요), 도면 새 버전 게시, 조직·요금제·양식 관리. 이런 일은 화면에서 하세요.

조직 차원의 자동화(조직 Agent·이벤트 구독 웹훅·실행 원장)는 → 17. Agent 활동

4. 문제 해결