koseokmin
58d3014a0f
계약 테스트는 docs/contracts 아래 예제를 golden example로 읽는다.
docs/와 README.md가 ignore되어 있어 예제 파일이 사라졌고 9건이
실패하고 있었다. 문서가 온전했던 마지막 상태(3de052a)에서 복원하고
.gitignore에서 두 항목을 제거한다. 에이전트 산출물인
docs/superpowers/ 제외는 유지한다.
initialize 응답의 capabilities.tools.listChanged를 문서는 true로
적고 있었으나 InitializeHandler는 false를 낸다. 현재 HTTP 단발 응답
transport가 notification을 push할 수 없으므로 false가 맞다. 예제와
architecture.md를 코드에 맞추고, ToolListChangedEvent가 발행되지만
아직 소비되지 않는다는 점과 SSE 도입 시 true로 바꾼다는 조건을
남긴다.
169개 테스트 전부 통과.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4.7 KiB
ADR-0006 MCP Server는 인증·인가를 하지 않는다
- 상태: Accepted
- 결정일: 2026-08-01
- 관련 결정: ADR-0001
배경
Tool 실행 권한은 Agent Builder가 Agent를 구성할 때 이미 확인하고 넘어온다. MCP Server는 Agent Builder가 지정한 Tool을 검증·실행하는 계층이므로 권한을 다시 판단할 근거가 없다.
문제는 MCP가 판단하지 않는 계층인 동시에 집행 지점이라는 데 있다. MCP는 이 배포에 속한 모든 Tool Service에 도달할 수 있는 유일한 경로다. 따라서 "MCP는 아무것도 하지 않는다"는 결정은, 그러면 누가 하는가를 함께 적지 않으면 세 계층이 서로 상대가 확인했다고 가정하는 공백을 만든다.
이 문서는 그 공백을 막기 위해 책임 소재를 명시한다.
결정
MCP Server는 인증(authentication)과 인가(authorization)를 수행하지 않는다.
- 요청자의 신원을 검증하지 않는다.
- Tool 실행 권한을 판단하지 않는다.
employee-no·virtual-employee-no를 복호화·검증·저장하지 않는다.- Authorization 헤더를 해석하지 않는다.
mcp.tool-client.forward-authorization이 켜져 있으면 값을 그대로 전달만 한다.
이에 따라 무검증 JWT decode 구현(JwtClaimExtractor, UnverifiedJwtClaimExtractor)을 삭제한다.
검증하지 않는 인증 코드는 없는 것보다 나쁘다. 이후 누군가 그 claim을 판단 근거로 쓸 여지를 남기고,
코드베이스에 인증이 처리되고 있다는 잘못된 인상을 준다.
책임 소재
| 책임 | 주체 | 근거 |
|---|---|---|
| 호출자가 Agent Builder인지 보장 | 플랫폼(NetworkPolicy) | Helm Chart의 templates/networkpolicy.yaml. 환경별 허용 namespace는 values-{env}.yaml의 global.agentBuilderNamespace |
| 사용자 인증, Tool 실행 권한 판단 | Agent Builder | Agent 구성 시점에 확인 |
| 사원 식별자 복호화와 업무 권한 집행 | Tool Service | KMS에서 발급받은 키 사용 |
| 요청 형식·schema 검증, 단일 Tool 실행 | MCP Server | ADR-0001 |
이 결정이 성립하기 위한 전제
전제 1 — 네트워크가 호출자를 고정한다.
MCP는 요청자를 확인하지 않으므로, /mcp에 도달할 수 있다는 것 자체가 곧 인가다.
NetworkPolicy로 Agent Builder namespace만 8080에 접근하도록 제한한다.
이 정책 없이 배포하면 클러스터 안의 어떤 Pod이든 Tool을 실행할 수 있다.
정책은 선택적 강화가 아니라 이 ADR의 성립 조건이다.
그래서 Helm Chart에 비활성화 스위치를 두지 않았고, HelmDeploymentContractTest가
조건부 렌더링이 들어오는 것까지 막는다. values 한 줄로 인가가 사라지지 않게 하기 위해서다.
전제 2 — 사원 식별자의 신뢰는 Tool Service가 확보한다.
employee-no·virtual-employee-no는 암호화되어 전달되고, 복호화 키는 사내 KMS에서 발급받는다.
MCP는 키를 갖지 않으므로 값을 읽을 수 없고, 따라서 위조 여부도 판별할 수 없다.
Tool 파트가 확인할 항목:
- 복호화는 KMS 키로만 가능하므로 기밀성은 확보된다. 위조 방지는 암호화 키의 배포 범위에 달려 있다. 암호화 키를 널리 배포하면 임의의 사원번호를 스스로 암호화해 넣을 수 있으므로, 키 배포 범위를 신뢰 경계와 맞춘다.
- 동일한 암호문의 재사용(replay)을 허용할지, 만료·nonce를 둘지 결정한다.
- 두 헤더가 모두 없는 요청의 처리 방침을 정한다. 현재 계약에서 두 값은 선택값이다.
전제 3 — 감사 추적은 세 계층의 로그를 합쳐야 완성된다.
MCP 로그에는 guid와 x-request-id만 남는다.
사원 식별자는 개인 식별자이므로 암호문이라도 기록하지 않는다.
따라서 "누가 조회했는가"는 MCP 로그만으로 답할 수 없다.
guid를 Agent Builder·MCP·Tool Service가 공통 상관 키로 사용해 세 로그를 연결한다.
규제 감사 요건이 확정되면 별도 durable sink를 설계한다.
영향
- MCP에 인증 코드를 추가하지 않는다. 필요가 생기면 이 ADR을 대체하는 새 ADR을 먼저 쓴다.
- NetworkPolicy는 배포 필수 구성요소다. 누락은 설정 실수가 아니라 보안 결함으로 다룬다.
- 인증 모델이 token 기반으로 바뀌면 이 결정과 전제 1을 함께 재검토한다.
forward-authorization설정은 유지한다. 검증이 아니라 통과 전달이며, Tool Service가 자체 인증을 도입할 때 필요한 연결점이다.