itglue-mcp

Example Corp / examplecorp IT Glue 테넌트(your-company.itglue.com)에 대한 읽기 전용 MCP 서버. 채팅에서 "이 고객에 대해 우리가 아는 것은 무엇인가"에 답하고, "X의 자격 증명은 무엇인가"에는 비밀이 아닌 IT Glue 링크로 답한다.

사내 원격 MCP 표준(fastmcp 리소스 서버 + Entra ID 인증, Portainer의 Nginx Proxy Manager 뒤)을 기반으로 구축됨. ~/.claude/context/mcp-server-playbook.md 참조.

이 설계를 만든 API 및 콘텐츠 감사 결과는 FEASIBILITY.md에 있음. 변경 전에 §0과 §1을 읽을 것.

두 가지 보장

1. IT Glue에 어떤 것도 기록되지 않음

사용 중인 API 키는 전체 쓰기 및 삭제 권한을 가짐. 가정이 아닌 검증된 사실:

PATCH  /configurations/999999999  -> 404 "Record not found"
PATCH  /passwords/999999999       -> 404 "Record not found"
DELETE /configurations/999999999  -> 404

쓰기 권한이 없는 키는 레코드 조회 이전에 401/403으로 실패함. 404는 변형이 승인되었고 단지 작동할 대상이 없었음을 의미함. IT Glue는 읽기 범위의 클래식 API 키를 발급하지 않으므로 서버 측 권한에 의존할 수 없음 — 보장은 전적으로 이 코드베이스에 있음:

• client.py는 정확히 하나의 요청 메서드 get()만 노출하며, method="GET"을 하드코딩함.

• post/patch/put/delete 헬퍼는 존재하지 않음. 추가하는 것은 기능이 아니라 보안 회귀임.

• WriteAttemptError 트립와이어는 GET이 아닌 요청이 생성되면 발동함.

• tests/smoke_local.py는 부재한 메서드와 부재한 동사를 모두 검증함.

쓰기 기능이 구축되면(FEASIBILITY.md 옵션 C) 별도의 키를 가진 별도의 프로세스에 들어감. 그 분리가 전체 안전 논거인데, IT Glue 문서는 모델이 요약하는 고객 작성 텍스트, 즉 신뢰할 수 없는 입력이기 때문임.

2. 자격 증명 값은 절대 반환되지 않음

itglue_find_credential은 포인터를 반환함: 자격 증명의 이름, 카테고리, 속한 장치, 마지막 회전 시기, OTP 활성화 여부, IT Glue 딥 링크. 사용자가 링크를 클릭하고 IT Glue에 로그인하여 비밀을 확인함.

수정(redaction)은 미러로 들어가는 경로에서 발생하므로(redact.py), 다운스트림 도구가 필드를 제거하는 것을 잊어 누출할 수 없음. IT Glue가 restricted로 표시한 레코드는 완전히 제외됨.

Related MCP server: invgate-mcp

로컬 미러가 있는 이유

IT Glue의 filter[name]은 정확히 일치하는 경우에만 작동하며, 일부 필터는 거부되지 않고 조용히 무시됨:

따라서 서버 측 검색은 모델이 가지고 있지 않은 정확한 문자열을 요구하거나 조용히 거짓말을 함. 그래서 모든 것이 RAM에 미러링되어 로컬에서 검색됨(search.py, index.py).

동기화 비용(측정됨): ~7,000개 구조화 레코드에 ~10개 요청; 300개 문서 본문에 ~400개 요청(95개 조직 목록 + 문서별 가져오기), 5분당 3,000개 상한 대비. 코어는 몇 초 안에 워밍업되고, 문서는 백그라운드에서 몇 분에 걸쳐 워밍업되며, 문서 도구는 멈추는 대신 status: indexing을 보고함.

디스크에 아무것도 유지되지 않음 — 코퍼스가 작아서 재시작 시 다시 동기화할 뿐이고 오래된 캐시 실패 모드가 없음.

검색은 의도적으로 관대한데, 실제 쿼리는 *"EF Vista Del Mar Unified Controller"*처럼 보이기 때문임: 약어, 전체 이름, 데이터에 Unifi로 철자된 제품. 약어 매칭(EF → Example Foundation), 단어별 퍼지 매칭(unified ≈ unifi, 비율 0.83), 조직 토큰 빼기, 원자적 식별자 처리를 통해 192.0.2.51이 ['10','105','251']로 분해되지 않도록 처리함.

도구

모두 readOnlyHint: true로 주석 처리됨.

이 도구가 만들어진 쿼리

"Example Foundation UniFi 컨트롤러의 자격 증명은 무엇인가?"

itglue_find_credential은 문장에서 조직을 추론하고, 이름 단어를 빼고, 460개 EF 자격 증명 레코드에서 unified→unifi를 퍼지 매칭하고, 다섯 개의 포인터를 반환함 — 현재 *Unifi Controller (New Staging)*의 두 개와 이전 VDM_Cloudwifi 로그인 세 개 — 각각 클릭 가능한 링크, 장치 URL, 마지막 회전 날짜 포함. 비밀은 서버를 떠나지 않음.

로컬 개발

python -m venv .venv && .venv/Scripts/activate    # Windows
pip install -r requirements.txt
cp .env.example .env      # fill in ITGLUE_API_KEY; set MCP_AUTH_ENABLED=false
python -m itglue_mcp

인증이 없는 서버를 절대 노출하지 말 것. MCP_AUTH_ENABLED=false는 localhost의 MCP Inspector 전용임.

스모크 테스트(라이브, 읽기 전용)

python tests/smoke_local.py

라이브 테넌트에 대한 47개 검증. 환경에 ITGLUE_API_KEY가 설정되지 않은 경우 ~/.claude/credentials/itglue.env를 읽으며, fastmcp 설치가 필요 없음. 자격 증명 검증이 중요한 것임 — 하나라도 실패하면 배포 전에 멈추고 수정할 것.

배포

1. Entra 앱 + 그룹 + 토큰 수명 — scripts/setup_entra_app.ps1(기본적으로 드라이런; 실행하려면 -Apply). 앱, 5명의 초기 구성원이 있는 ITGlue-MCP-Users 보안 그룹, 할당 강제, 23h59m 액세스 토큰 수명 정책을 프로비저닝함. docs/ENTRA_SETUP_CHECKLIST.md 참조.

2. Portainer 스택 + NPM — PORTAINER_DEPLOY.md. 호스트 포트 8111(2026-07-29에 10.0.0.10에서 사용 가능 확인 — 8100과 8110은 사용 중). 공개 호스트 itglue-mcp.example.com.

유지 관리

• IT Glue 키 회전 — 아직 미해결. 이제 사내 KEY=VALUE 형식의 ~/.claude/credentials/itglue.env에 있음(2026-07-30에 일반 텍스트 .itglueapicreds.txt에서 마이그레이션됨), 하지만 그것은 형식 변경이지 회전이 아님 — 키 값은 변경되지 않음. 쓰기 + 삭제 권한이 있고 알 수 없는 기간 동안 일반 텍스트 .txt에 있었음. 회전하려면: IT Glue → 계정 → 설정 → API 키에서 새 키를 발급하고, itglue.env와 Portainer 스택의 ITGLUE_API_KEY를 업데이트한 다음, 이전 키를 폐기.

• IT Glue는 90일 이상 사용되지 않은 API 키를 자동으로 폐기함. 미러 새로고침이 이 키를 활성 상태로 유지함; 서버가 중단되면 깨어날 때 401이 예상됨.

• 코드가 아닌 ITGlue-MCP-Users 그룹을 통해 액세스를 추가 및 제거.