저는 HolySheep AI 기술 문서팀에서 2년 넘게 일해온 엔지니어입니다. 오늘은 Claude Code를 팀 환경에서 안전하고 효율적으로 운영하기 위한 설정 방법을 초보자도 이해할 수 있도록 단계별로 설명드리겠습니다. 이 가이드를 마치면 팀所有人都能在受控 환경下使用 Claude Code를 경험할 수 있을 것입니다.

이 가이드가 다루는 내용

팀 협업이 왜 중요한가요?

Claude Code를 혼자 사용하는 것과 팀에서 사용하는 것은根本적으로 다릅니다. 혼자 사용할 때는 모든 도구에 자유롭게 접근하고 코드도 마음껏 수정하지만, 팀 환경에서는 보안을 유지하면서 협업 효율을 높여야 합니다. 특히 여러 명이 동시에 Claude Code를 사용하면 다음과 같은 문제가 발생할 수 있습니다:

HolySheep AI는 이런 팀 협업의 문제를 해결하기 위해 MCP 도구 화이트리스트, 상세한 감사 로그, 세밀한 권한 분배 기능을 제공합니다. 이제 각 기능을 설정하는 방법을 배워보겠습니다.

MCP 도구 화이트리스트 설정

MCP란 무엇인가요?

MCP(Model Context Protocol)는 Claude Code가 외부 도구나 서비스와 연결할 수 있게 해주는 프로토콜입니다. 예를 들어 데이터베이스에 연결하거나, GitHub 리포지토리를 관리하거나, 파일 시스템을 조작하는 등의 도구가 MCP를 통해 연결됩니다.

팀 환경에서는 모든 도구를 허용하면 보안 위험이 높아지므로, 필요한 도구만 화이트리스트에 추가하여 사용자의 접근을 제어합니다.

HolySheep AI 대시보드에서 MCP 설정하기

1단계: HolySheep AI에 로그인하고 팀 설정 접속

먼저 지금 가입하고ダッシュ보드에 접속합니다. 상단 메뉴에서 "팀 설정(Team Settings)"을 클릭하세요. 이 메뉴는 화면 상단 오른쪽에 있는 사람 모양 아이콘을 클릭하면 나타납니다.

2단계: MCP 도구 관리 페이지 이동

팀 설정 화면에서 왼쪽 사이드바를 보면 "MCP 도구(MCP Tools)"라는 항목이 있습니다. 이를 클릭하면 도구 화이트리스트 관리 페이지로 이동합니다. 페이지에는 현재 허용된 도구 목록과 차단된 도구가 표시됩니다.

3단계: 화이트리스트에 도구 추가

"도구 추가(Add Tool)" 버튼을 클릭하면 도구 선택 팝업이 나타납니다. 여기서 팀에서 사용할 수 있게 하려는 도구를 선택할 수 있습니다. 자주 사용되는 도구들은 다음과 같습니다:

MCP 설정 파일 직접 편집하기

대시보드 외에 설정 파일을 직접 편집하여 MCP 도구를 구성할 수도 있습니다. 프로젝트 루트 디렉토리에 claude_desktop_config.json 파일을 생성하거나 수정하세요.

{
  "mcp_tools": {
    "enabled": ["filesystem", "git", "search"],
    "disabled": ["database", "network"],
    "restricted": {
      "database": {
        "allowed_operations": ["SELECT"],
        "blocked_operations": ["DELETE", "DROP", "TRUNCATE"]
      },
      "network": {
        "allowed_hosts": ["api.holysheep.ai", "github.com"],
        "blocked_hosts": ["*.internal", "localhost:5432"]
      }
    }
  },
  "team_settings": {
    "require_approval_for_new_tools": true,
    "audit_all_tool_calls": true
  }
}

이 설정은 다음과 같은 역할을 합니다:

감사 로그 활용하기

감사 로그란 무엇인가요?

감사 로그(Audit Log)는 팀에서 Claude Code를 어떻게 사용했는지 모든 활동을 기록하는 로그입니다. 누가 언제 어떤 도구를 사용했는지, 어떤 파일을 수정했는지, 어떤 명령어를 실행했는지 Chronological 순서로 기록됩니다.

감사 로그는 다음과 같은 경우에 필수적입니다:

HolySheep AI에서 감사 로그 확인하기

HolySheep AI 대시보드에서 "감사 로그(Audit Logs)" 메뉴를 클릭하면 팀의 모든 활동이 표시됩니다. 로그 화면은 다음과 같이 구성됩니다:

[화면 구성: 상단에 날짜 범위 선택기와 필터 옵션이 있고, 아래에 활동 목록 테이블이 표시됨. 테이블 컬럼은 시간, 사용자, 활동 유형, 도구, 대상 파일/리소스, 결과]

컬럼명 설명 예시
시간(Timestamp) 활동이 발생한 시간 2026-05-30 14:32:15 KST
사용자(User) 활동한 팀원 이름 [email protected]
활동 유형(Action) 수행한 작업의 종류 ToolExecution, FileWrite, CommandRun
도구(Tool) 사용된 MCP 도구 이름 filesystem, git, database
대상(Subject) 작업이 수행된 파일이나 리소스 /src/api/users.ts
결과(Result) 작업 성공/실패 여부 Success, Failed, Blocked

감사 로그를プログラム적으로查询하기

대시보드 외에 HolySheep AI API를 사용하여 감사 로그를程序적으로 가져올 수 있습니다. 이를 통해 자신만의 대시보드나 보고서를 만들 수 있습니다.

import requests
import json
from datetime import datetime, timedelta

class HolySheepAuditLogger:
    """HolySheep AI 감사 로그 조회 클래스"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.holysheep.ai/v1"
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
    
    def get_audit_logs(
        self, 
        start_date: datetime = None,
        end_date: datetime = None,
        user_id: str = None,
        action_type: str = None,
        tool_name: str = None,
        limit: int = 100
    ) -> dict:
        """
        팀 감사 로그를 조회합니다.
        
        Args:
            start_date: 조회 시작 날짜 (기본값: 7일 전)
            end_date: 조회 종료 날짜 (기본값: 현재)
            user_id: 특정 사용자 필터링
            action_type: 활동 유형 필터링 (ToolExecution, FileWrite 등)
            tool_name: MCP 도구 이름 필터링
            limit: 최대 결과 수
        
        Returns:
            감사 로그 목록과 메타데이터
        """
        if start_date is None:
            start_date = datetime.now() - timedelta(days=7)
        if end_date is None:
            end_date = datetime.now()
        
        params = {
            "start_date": start_date.isoformat(),
            "end_date": end_date.isoformat(),
            "limit": limit
        }
        
        if user_id:
            params["user_id"] = user_id
        if action_type:
            params["action_type"] = action_type
        if tool_name:
            params["tool_name"] = tool_name
        
        response = requests.get(
            f"{self.base_url}/team/audit-logs",
            headers=self.headers,
            params=params
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"감사 로그 조회 실패: {response.status_code} - {response.text}")
    
    def get_user_activity_summary(self, user_id: str, days: int = 30) -> dict:
        """
        특정 사용자의 활동 요약을 가져옵니다.
        
        Args:
            user_id: 사용자 ID
            days: 분석 기간 (일)
        
        Returns:
            사용자 활동 통계
        """
        end_date = datetime.now()
        start_date = end_date - timedelta(days=days)
        
        logs = self.get_audit_logs(
            start_date=start_date,
            end_date=end_date,
            user_id=user_id,
            limit=1000
        )
        
        # 활동 통계 계산
        tool_usage = {}
        action_counts = {"Success": 0, "Failed": 0, "Blocked": 0}
        
        for log in logs.get("logs", []):
            tool = log.get("tool", "unknown")
            tool_usage[tool] = tool_usage.get(tool, 0) + 1
            
            result = log.get("result", "unknown")
            if result in action_counts:
                action_counts[result] += 1
        
        return {
            "user_id": user_id,
            "period_days": days,
            "total_actions": len(logs.get("logs", [])),
            "tool_usage": tool_usage,
            "result_summary": action_counts
        }


사용 예시

if __name__ == "__main__":
    API_KEY = "YOUR_HOLYSHEEP_API_KEY"
    logger = HolySheepAuditLogger(API_KEY)
    
    # 전체 감사 로그 조회
    print("최근 7일간의 감사 로그 조회...")
    logs = logger.get_audit_logs(limit=50)
    print(f"총 {logs.get('total_count', 0)}개의 로그 항목 발견")
    
    # 특정 사용자 활동 요약
    print("\n팀장([email protected])의 월간 활동 요약:")
    summary = logger.get_user_activity_summary("[email protected]", days=30)
    print(json.dumps(summary, indent=2, ensure_ascii=False))

의심스러운 활동 알림 설정

감사 로그뿐만 아니라 의심스러운 활동이 발생하면 즉시 알림을 받을 수도 있습니다. HolySheep AI에서는 다음과 같은 조건으로 알림을 설정할 수 있습니다:

class HolySheepAlertManager:
    """HolySheep AI 알림 관리 클래스"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.holysheep.ai/v1"
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
    
    def create_alert_rule(
        self,
        name: str,
        condition: dict,
        channels: list,
        severity: str = "medium"
    ) -> dict:
        """
        새로운 알림 규칙을 생성합니다.
        
        Args:
            name: 규칙 이름
            condition: 알림 발생 조건
                - type: "tool_access", "file_modification", "unusual_activity"
                - tool: 도구 이름
                - file_pattern: 파일 패턴 (glob 형식)
                - threshold: 횟수 임계값
            channels: 알림 채널 목록 ["email", "slack", "webhook"]
            severity: 심각도 ["low", "medium", "high", "critical"]
        
        Returns:
            생성된 규칙 정보
        """
        payload = {
            "name": name,
            "condition": condition,
            "channels": channels,
            "severity": severity,
            "enabled": True
        }
        
        response = requests.post(
            f"{self.base_url}/team/alert-rules",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 201:
            return response.json()
        else:
            raise Exception(f"알림 규칙 생성 실패: {response.status_code}")
    
    def setup_security_alerts(self) -> list:
        """팀용 보안 알림 규칙을 한 번에 설정합니다."""
        rules = [
            {
                "name": "민감 도구 접근 알림",
                "condition": {
                    "type": "tool_access",
                    "tool": "database",
                    "operations": ["DELETE", "DROP", "TRUNCATE"]
                },
                "channels": ["email", "slack"],
                "severity": "high"
            },
            {
                "name": "대량 파일 수정 알림",
                "condition": {
                    "type": "file_modification",
                    "file_pattern": "**/*.py",
                    "threshold": 10,
                    "time_window_minutes": 60
                },
                "channels": ["email"],
                "severity": "medium"
            },
            {
                "name": "비업무시간 활동 알림",
                "condition": {
                    "type": "unusual_activity",
                    "outside_hours": True,
                    "timezone": "Asia/Seoul"
                },
                "channels": ["webhook"],
                "severity": "low"
            }
        ]
        
        created_rules = []
        for rule in rules:
            created = self.create_alert_rule(**rule)
            created_rules.append(created)
            print(f"규칙 생성 완료: {created['name']} (ID: {created['id']})")
        
        return created_rules


사용 예시

if __name__ == "__main__":
    API_KEY = "YOUR_HOLYSHEEP_API_KEY"
    alerts = HolySheepAlertManager(API_KEY)
    
    # 보안 알림 규칙 일괄 설정
    print("팀 보안 알림 규칙 설정 중...")
    rules = alerts.setup_security_alerts()
    print(f"총 {len(rules)}개의 알림 규칙이 활성화되었습니다.")

권한 분배와 역할 관리

권한 레벨 구조 이해하기

HolySheep AI는 팀원을 여러 권한 레벨로 구분하여 관리할 수 있습니다. 각 레벨은 Claude Code 사용 시 사용할 수 있는 기능과 도구가 다릅니다.

권한 레벨 설명 도구 접근 MCP 설정 감사 로그
관리자(Admin) 팀 설정 전체 관리 모든 도구 편집 가능 전체 조회
팀장(Team Lead) 프로젝트 관리 및 팀원 감독 대부분의 도구 조회만 팀 전체 조회
개발자(Developer) 일반 개발 작업 수행 선택적 도구 제한적 본인만
뷰어(Viewer) 코드 리뷰 및 읽기 전용 읽기 전용 도구 없음 없음
외부 협력자(External) 특정 프로젝트만 접근 프로젝트별 설정 없음 없음

팀원 권한 설정하기

각 팀원의 권한을 설정하려면 HolySheep AI 대시보드에서 "팀원 관리(Team Members)" 페이지로 이동하세요. 팀원 목록에서 특정인을 클릭하면 권한 편집 화면이 나타납니다.

[화면 구성: 팀원 이름과 이메일, 현재 권한 레벨, 마지막 활동 시간, 권한 편집 버튼이 표시됨]

class HolySheepTeamManager:
    """HolySheep AI 팀원 권한 관리 클래스"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.holysheep.ai/v1"
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
    
    def get_team_members(self) -> list:
        """팀원 목록을 조회합니다."""
        response = requests.get(
            f"{self.base_url}/team/members",
            headers=self.headers
        )
        
        if response.status_code == 200:
            return response.json().get("members", [])
        else:
            raise Exception(f"팀원 목록 조회 실패: {response.status_code}")
    
    def update_member_role(
        self,
        member_id: str,
        role: str,
        mcp_permissions: dict = None
    ) -> dict:
        """
        팀원의 역할과 권한을 업데이트합니다.
        
        Args:
            member_id: 팀원 ID
            role: 새 역할 ("admin", "team_lead", "developer", "viewer", "external")
            mcp_permissions: MCP 도구별 상세 권한
        
        Returns:
            업데이트된 팀원 정보
        """
        payload = {
            "role": role,
            "mcp_permissions": mcp_permissions or {}
        }
        
        response = requests.patch(
            f"{self.base_url}/team/members/{member_id}",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"권한 업데이트 실패: {response.status_code}")
    
    def setup_developer_permissions(self, member_id: str) -> dict:
        """일반 개발자 권한을 권장 설정으로 구성합니다."""
        mcp_permissions = {
            "filesystem": {
                "enabled": True,
                "allowed_paths": [
                    "/project/src",
                    "/project/tests",
                    "/project/docs"
                ],
                "blocked_paths": [
                    "/project/secrets",
                    "/project/config/local"
                ]
            },
            "git": {
                "enabled": True,
                "allowed_operations": ["status", "diff", "log", "commit", "push"],
                "blocked_operations": ["force_push", "rebase", "reset"]
            },
            "search": {
                "enabled": True,
                "max_results": 100
            },
            "database": {
                "enabled": True,
                "allowed_operations": ["SELECT"],
                "blocked_operations": ["INSERT", "UPDATE", "DELETE", "DROP"]
            },
            "network": {
                "enabled": False
            }
        }
        
        return self.update_member_role(
            member_id,
            role="developer",
            mcp_permissions=mcp_permissions
        )
    
    def invite_external_collaborator(
        self,
        email: str,
        project_name: str,
        project_id: str
    ) -> dict:
        """
        외부 협력자를 초대합니다 (특정 프로젝트만 접근 가능).
        
        Args:
            email: 외부 협력자 이메일
            project_name: 접근 허용할 프로젝트명
            project_id: 프로젝트 ID
        
        Returns:
            초대 정보
        """
        mcp_permissions = {
            "filesystem": {
                "enabled": True,
                "allowed_paths": [f"/projects/{project_id}/**"],
                "readonly": True
            },
            "git": {
                "enabled": True,
                "allowed_operations": ["clone", "fetch", "diff"],
                "blocked_operations": ["push", "commit"]
            }
        }
        
        payload = {
            "email": email,
            "role": "external",
            "project_scope": project_id,
            "mcp_permissions": mcp_permissions,
            "expires_in_days": 30  # 30일 후 자동 만료
        }
        
        response = requests.post(
            f"{self.base_url}/team/invitations",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 201:
            return response.json()
        else:
            raise Exception(f"외부 협력자 초대 실패: {response.status_code}")


사용 예시

if __name__ == "__main__":
    API_KEY = "YOUR_HOLYSHEEP_API_KEY"
    manager = HolySheepTeamManager(API_KEY)
    
    # 전체 팀원 조회
    print("팀원 목록:")
    members = manager.get_team_members()
    for member in members:
        print(f"  - {member['name']} ({member['email']}): {member['role']}")
    
    # 특정 개발자 권한 설정
    print("\n새로운 개발자([email protected]) 권한 설정 중...")
    updated = manager.setup_developer_permissions("member_12345")
    print(f"권한 업데이트 완료: {updated['name']}")
    
    # 외부 디자이너 초대
    print("\n외부 디자이너 초대 중...")
    invitation = manager.invite_external_collaborator(
        email="[email protected]",
        project_name="landing-page-redesign",
        project_id="proj_98765"
    )
    print(f"초대 전송 완료: {invitation['invitation_url']}")

실전 시나리오: 완전한 팀 협업 설정

이제 앞에서 배운 모든 기능을 통합하여 실제 팀 협업 환경을 구축하는 방법을 보여드리겠습니다. 이 시나리오는 5명으로 구성된 개발팀을 위한 설정입니다.

class HolySheepTeamSetup:
    """HolySheep AI 팀 협업 환경 자동 설정"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.team_manager = HolySheepTeamManager(api_key)
        self.alert_manager = HolySheepAlertManager(api_key)
        self.audit_logger = HolySheepAuditLogger(api_key)
    
    def setup_complete_team_environment(self, team_config: dict) -> dict:
        """
        완전한 팀 협업 환경을 한 번에 설정합니다.
        
        Args:
            team_config: 팀 설정 정보
                {
                    "team_name": "backend-dev-team",
                    "members": [
                        {"email": "...", "name": "...", "role": "..."},
                        ...
                    ],
                    "mcp_tools": {...},
                    "alert_rules": [...]
                }
        
        Returns:
            설정 완료 결과
        """
        results = {
            "members": [],
            "mcp_tools": None,
            "alert_rules": [],
            "errors": []
        }
        
        # 1단계: MCP 도구 화이트리스트 설정
        print("[1/4] MCP 도구 화이트리스트 설정 중...")
        try:
            results["mcp_tools"] = self._configure_mcp_tools(team_config.get("mcp_tools", {}))
            print("  ✓ MCP 도구 설정 완료")
        except Exception as e:
            results["errors"].append(f"MCP 설정 오류: {str(e)}")
        
        # 2단계: 팀원 권한 설정
        print("[2/4] 팀원 권한 설정 중...")
        for member in team_config.get("members", []):
            try:
                member_result = self._setup_member(member)
                results["members"].append(member_result)
                print(f"  ✓ {member['name']} ({member['role']}) 설정 완료")
            except Exception as e:
                results["errors"].append(f"{member['name']} 설정 오류: {str(e)}")
        
        # 3단계: 보안 알림 규칙 설정
        print("[3/4] 보안 알림 규칙 설정 중...")
        for rule in team_config.get("alert_rules", []):
            try:
                rule_result = self.alert_manager.create_alert_rule(**rule)
                results["alert_rules"].append(rule_result)
                print(f"  ✓ '{rule['name']}' 규칙 활성화")
            except Exception as e:
                results["errors"].append(f"알림 규칙 오류: {str(e)}")
        
        # 4단계: 감사 로그 기반 보고서 생성
        print("[4/4] 초기 감사 리포트 생성 중...")
        try:
            report = self._generate_initial_report()
            results["initial_report"] = report
            print("  ✓ 초기 감사 리포트 생성 완료")
        except Exception as e:
            results["errors"].append(f"리포트 생성 오류: {str(e)}")
        
        return results
    
    def _configure_mcp_tools(self, tools_config: dict) -> dict:
        """MCP 도구 설정을 구성합니다."""
        # 실제 API 호출 시뮬레이션
        return {
            "enabled_tools": tools_config.get("enabled", []),
            "restricted_tools": tools_config.get("restricted", {}),
            "global_policy": "team_restricted"
        }
    
    def _setup_member(self, member: dict) -> dict:
        """개별 팀원 권한을 설정합니다."""
        role = member.get("role", "developer")
        
        if role == "admin":
            mcp_perms = {"*": {"enabled": True}}
        elif role == "team_lead":
            mcp_perms = {
                "filesystem": {"enabled": True},
                "git": {"enabled": True},
                "database": {"enabled": True, "operations": ["SELECT", "INSERT"]},
                "network": {"enabled": True, "allowed_hosts": ["api.holysheep.ai"]}
            }
        elif role == "developer":
            mcp_perms = {
                "filesystem": {"enabled": True, "allowed_paths": ["/project/**"]},
                "git": {"enabled": True},
                "search": {"enabled": True}
            }
        else:
            mcp_perms = {
                "filesystem": {"enabled": True, "readonly": True}
            }
        
        return {
            "email": member["email"],
            "name": member["name"],
            "role": role,
            "mcp_permissions": mcp_perms
        }
    
    def _generate_initial_report(self) -> dict:
        """초기 감사 리포트를 생성합니다."""
        logs = self.audit_logger.get_audit_logs(limit=100)
        summary = {
            "total_logs": logs.get("total_count", 0),
            "period": "최근 7일",
            "generated_at": datetime.now().isoformat()
        }
        return summary


실전 사용 예시

if __name__ == "__main__":
    API_KEY = "YOUR_HOLYSHEEP_API_KEY"
    
    # 팀 구성 설정
    team_config = {
        "team_name": "holy-gangnam-backend",
        "mcp_tools": {
            "enabled": ["filesystem", "git", "search"],
            "restricted": {
                "database": {"allowed_operations": ["SELECT"]},
                "network": {"allowed_hosts": ["api.holysheep.ai"]}
            }
        },
        "members": [
            {
                "email": "[email protected]",
                "name": "김팀장",
                "role": "team_lead"
            },
            {
                "email": "[email protected]",
                "name": "박주니어",
                "role": "developer"
            },
            {
                "email": "[email protected]",
                "name": "이시니어",
                "role": "developer"
            },
            {
                "email": "[email protected]",
                "name": "최인턴",
                "role": "viewer"
            }
        ],
        "alert_rules": [
            {
                "name": "데이터베이스 위험 작업 알림",
                "condition": {
                    "type": "tool_access",
                    "tool": "database",
                    "operations": ["DELETE", "DROP"]
                },
                "channels": ["email", "slack"],
                "severity": "critical"
            },
            {
                "name": "비업무시간 대규모 수정 알림",
                "condition": {
                    "type": "file_modification",
                    "file_pattern": "**/*.py",
                    "threshold": 20,
                    "time_window_minutes": 60
                },
                "channels": ["email"],
                "severity": "high"
            }
        ]
    }
    
    # 팀 환경 자동 설정
    print("=" * 50)
    print("HolySheep AI 팀 협업 환경 설정 시작")
    print("=" * 50)
    
    setup = HolySheepTeamSetup(API_KEY)
    results = setup.setup_complete_team_environment(team_config)
    
    print("\n" + "=" * 50)
    print("설정 완료 요약")
    print("=" * 50)
    print(f"팀원 설정: {len(results['members'])}명")
    print(f"활성화된 알림 규칙: {len(results['alert_rules'])}개")
    
    if results["errors"]:
        print(f"\n⚠️  오류 발생: {len(results['errors'])}건")
        for error in results["errors"]:
            print(f"  - {error}")
    else:
        print("\n✅ 모든 설정이 성공적으로 완료되었습니다!")

자주 발생하는 오류와 해결책

오류 1: API 키 권한 부족 (403 Forbidden)

# 증상: API 호출 시 403 오류 발생

원인: 사용 중인 API 키에 해당 작업에 대한 권한이 없음


해결: 관리자에게 더 높은 권한의 API 키를 요청하거나, 역할 변경


import requests

API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"

def check_api_permissions():
    """현재 API 키의 권한 상태를 확인합니다."""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    # 팀 설정 조회 시도
    response = requests.get(f"{BASE_URL}/team/settings", headers=headers)
    
    if response.status_code == 403:
        print("❌ API 키 권한 부족")
        print("해결 방법:")
        print("1. HolySheep AI 대시보드에서 '팀 설정 > API 키 관리' 접속")
        print("2. 해당 API 키의 역할이 'admin' 또는 'team_lead'인지 확인")
        print("3. 역할이 낮다면 관리자에게 역할 승격을 요청")
        print("4. 또는 새 API 키를 생성하여 관리자 권한으로 설정")
        return False
    elif response.status_code == 200:
        print("✅ API 키 권한 정상")
        return True
    else:
        print(f"⚠️ 기타 오류: {response.status_code}")
        return False


API 키 권한 확인

check_api_permissions()

오류 2: MCP 도구가 실행되지 않음 (Tool Not Enabled)

# 증상: Claude Code에서 특정 도구를 사용하려 할 때 "Tool Not Enabled" 오류

원인: 해당 도구가 팀의 MCP 화이트리스트에 포함되어 있지 않음


해결: 관리자가 화이트리스트에 해당 도구를 추가


import requests

API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"

def enable_mcp_tool(tool_name: str, team_id: str = None) -> dict:
    """
    MCP 도구를 팀 화이트리스트에 추가합니다.
    
    Args:
        tool_name: 활성화할 도구 이름 (예: "database", "network")
        team_id: 팀 ID (없으면 기본값 사용)
    
    Returns:
        업데이트 결과
    """
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "tool_name": tool_name,
        "action": "enable",
        "reason": "팀 작업 필요에 따라 활성화"
    }
    
    response = requests.post(
        f"{BASE_URL}/team/mcp-tools",
        headers=headers,
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"✅ '{tool_name}' 도구가 활성화되었습니다")
        return result
    else:
        print(f"❌ 도구 활성화 실패: {response.status_code}")
        if response.status_code == 403:
            print("   → 관리자 권한이 필요합니다. 팀 관리자에게 문의하세요.")
        elif response.status_code == 404:
            print("   → 해당 도구가 HolySheep에서 지원되지 않습니다.")
        return None


사용 예시: 데이터베이스 도구 활성화

if __name__ == "__main__":
    # 활성화하려는 도구 목록
    tools_to_enable = ["database", "network", "custom_api"]
    
    for tool in tools_to_enable:
        result = enable_mcp_tool(tool)
        if result:
            print(f"   제한 조건: {result.get('restrictions', '없음')}")

오류 3: 감사 로그 조회 시 빈 결과 반환

# 증상: 감사 로그 API를 호출하면 데이터가 없음

원인: 날짜 범위 설정 오류, 필터 조건 불일치, 또는 실제로 활동이 없음


해결:


관련 리소스
관련 문서