콘텐츠로 이동
MFA ServiceNow MCP

도구 패키지 — 고급 레퍼런스

대부분의 사용자는 이 페이지가 필요 없습니다. 기본 패키지는 standard로, 읽기 전용이며 어떤 환경에서도 안전합니다. standard로 충분하지 않은 쓰기 도구가 필요할 때만 이 문서를 참고하세요.

패키지 선택 가이드

섹션 제목: “패키지 선택 가이드”

자신의 작업에 필요한 가장 좁은 패키지부터 시작하세요. 단계가 올라갈수록 더 많은 도메인의 쓰기 권한이 추가됩니다:

읽기 전용 — 어떤 환경에서도 안전, 쓰기 도구 없음:

패키지명 도구 수 최대 토큰 최대 (인스턴스 3개) 사용 시기
core 12 ~2.0K ~2.6K 최소 읽기 전용: 헬스체크, 스키마, 탐색, 핵심 조회만
standard 31 ~7.0K ~7.9K (기본값) 인시던트/변경/포털/로그/소스 분석 읽기 전용
none 0 0 0 모든 도구를 의도적으로 비활성화 (테스트, 잠금 환경)

⚠️ 쓰기 가능 — 고급 옵션, 생성/수정/삭제 권한 부여:

패키지명 도구 수 최대 토큰 최대 (인스턴스 3개) 사용 시기
service_desk 33 ~7.7K ~8.7K ⚠️ 인시던트/변경 업데이트·종료가 필요한 서비스 데스크 담당자
portal_developer 52 ~15.2K ~17.0K ⚠️ 위젯, 체인지셋, Script Include를 배포하는 포털 개발자
platform_developer 46 ~12.8K ~14.4K ⚠️ 워크플로우, Flow Designer, 스크립트를 관리하는 플랫폼 엔지니어
full 63 ~17.6K ~19.8K ⚠️ 가장 고급 — 모든 도메인의 쓰기 도구 전체를 동시에 (아래 경고 참고)

최대 토큰 = 요청마다 해당 패키지의 툴 스키마가 모델 컨텍스트에 더하는 대략적 토큰 수(tiktoken cl100k_base 기준, 실제 Claude 토큰 수는 약간 다름). 좁은 패키지를 쓸수록 컨텍스트와 비용이 절약됩니다. 이 값은 최대치이며 평소 비용이 아닙니다. 모든 툴 스키마를 처음부터 싣는 클라이언트만 이 전부를 냅니다. 툴 지연 로딩을 지원하는 클라이언트(예: Claude Code의 툴 검색)는 실제로 쓰는 툴의 스키마만 불러오므로, 요청당 실제 비용은 훨씬 적습니다. 도구 수는 패키지 구성원 수입니다. 모든 패키지에 list_tool_packages가 함께 붙고, 멀티 인스턴스 구성에서는 list_instances, compare_instances와 모든 툴의 instance 파라미터가 더해집니다 — 두 번째 토큰 열은 인스턴스 3개 기준 실측값입니다. 수치는 추정이 아니라 tiktoken 실측입니다(uv run --no-sync --with tiktoken python scripts/measure_tool_tokens.py <package>로 툴별 내역 확인).

core와 none을 제외한 모든 패키지는 _extends를 통해 standard 읽기 전용 도구를 상속합니다. 전체 상속 구조는 config/tool_packages.yaml을 참고하세요.

패키지 설정 방법

섹션 제목: “패키지 설정 방법”

환경변수로 설정 (권장):

터미널 창
MCP_TOOL_PACKAGE=standard

CLI 플래그로 설정:

터미널 창
servicenow-mcp --tool-package standard --instance-url ...

MCP 클라이언트 설정 파일:

{
  "env": {
    "MCP_TOOL_PACKAGE": "standard"
  }
}

패키지에 없는 도구 호출 시

섹션 제목: “패키지에 없는 도구 호출 시”

현재 패키지에 없는 도구를 호출하면 서버가 명확한 오류를 반환합니다:

Tool 'manage_widget' is not available in package 'standard'.
Enable package 'portal_developer' or higher to use this tool.

자동 실패 없이 LLM이 어느 패키지가 필요한지 정확히 알 수 있습니다.

전체 도구 목록

섹션 제목: “전체 도구 목록”

카테고리와 패키지별 전체 77개 도구 목록은 도구 목록에서 확인하세요.