koseokmin
58d3014a0f
All checks were successful
Deploy Gateway / deploy (push) Successful in 2m52s
계약 테스트는 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>
3.3 KiB
3.3 KiB
ADR-0008 공유 host의 path를 독립 MCP 배포로 연결한다
배경
Agent Builder에는 하나의 HTTPS host를 제공하고 업무별 MCP를 /mcp/core, /mcp/process,
/mcp/information 같은 path로 구분해야 한다. 이를 하나의 애플리케이션 프로세스에서 처리하면
Registry snapshot·Redis cache·readiness·connection 자원을 route별로 다시 나눠야 하고, 한 프로세스의
장애와 배포가 모든 Tool Service에 전파된다.
결정
- 환경마다 공개 MCP host를 하나 둔다.
deployments.<key>.publicPath는 한 MCP Deployment를 가리키며 topology 전체에서 유일하다.- OpenShift Route가 공개 path를 해당 MCP Service로 전달하고 내부 고정 endpoint
/mcp로 rewrite한다. - MCP 애플리케이션과 Tool Service의 1:1 매핑, Registry snapshot, Redis key와 readiness는 배포별로 유지한다.
- Agent Builder는 각 공개 URL을 독립 MCP endpoint로 등록하고 endpoint별로 initialize한다.
- 요청 body·header·Tool 이름은 어느 MCP Service로 보낼지 결정하지 못한다. 대상은 Helm topology만 정한다.
https://{host}/mcp/core -> core MCP /mcp -> core Tool Service
https://{host}/mcp/process -> process MCP /mcp -> process Tool Service
https://{host}/mcp/information -> information MCP /mcp -> information Tool Service
가용성 등급으로 같은 업무를 둘로 나누면 path도 구분한다. 예를 들어
/mcp/process-critical과 /mcp/process-standard는 서로 다른 MCP Deployment와 Tool Service를 가리킨다.
근거
- 외부 URL은 한 host로 단순화하면서 내부 장애 범위는 업무·가용성 등급별로 유지한다.
- 현재 Java transport·Registry·cache 코드를 route-aware Gateway로 바꾸지 않아도 된다.
- 한 Tool Service의 조회 실패나 부하가 다른 MCP의 readiness와 snapshot 갱신을 막지 않는다.
- 공개 path와 Service 매핑을 한 topology에서 검토하고 계약 테스트로 중복·형식을 막을 수 있다.
영향
- 하나의 Helm release는 Deployment·Service·Route를 하나씩 만든다. 여러 release의 Route가 같은 host와 서로 다른 path를 사용한다.
- OpenShift Router가 TLS를 종료하고 path를 rewrite하므로 backend 애플리케이션은 계속
POST /mcp만 처리한다. - 공개 URL 변경 시 Agent Builder 재등록 또는 endpoint 설정 변경이 필요하다.
- Gateway 기능은 OpenShift Route가 소유한다. MCP Java 프로세스는 Tool 선택이나 다른 MCP로의 proxy를 하지 않는다.
- 실제 환경 host와 인증서·TLS 종료 방식은 플랫폼 적용 전에 확정해야 한다.
채택하지 않은 대안
하나의 MCP 프로세스가 모든 path를 처리한다. 배포 수는 줄지만 전역 장애 범위와 noisy neighbor가 생기고, route별 Registry·cache·readiness를 새로 구현해야 하므로 채택하지 않았다.
Tool Service가 MCP protocol을 직접 구현하고 중앙 Gateway가 raw proxy한다. Tool Service 계약과 책임이 크게 바뀌며 현재의 공통 MCP 검증 계층이 중복되므로 채택하지 않았다.