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>
54 lines
3.3 KiB
Markdown
54 lines
3.3 KiB
Markdown
# ADR-0008 공유 host의 path를 독립 MCP 배포로 연결한다
|
|
|
|
- 상태: Accepted
|
|
- 결정일: 2026-08-05
|
|
- 관련: [ADR-0006](ADR-0006-no-authentication-in-mcp.md), [ADR-0007](ADR-0007-one-mcp-per-tool-service.md)
|
|
|
|
## 배경
|
|
|
|
Agent Builder에는 하나의 HTTPS host를 제공하고 업무별 MCP를 `/mcp/core`, `/mcp/process`,
|
|
`/mcp/information` 같은 path로 구분해야 한다. 이를 하나의 애플리케이션 프로세스에서 처리하면
|
|
Registry snapshot·Redis cache·readiness·connection 자원을 route별로 다시 나눠야 하고, 한 프로세스의
|
|
장애와 배포가 모든 Tool Service에 전파된다.
|
|
|
|
## 결정
|
|
|
|
1. 환경마다 공개 MCP host를 하나 둔다.
|
|
2. `deployments.<key>.publicPath`는 한 MCP Deployment를 가리키며 topology 전체에서 유일하다.
|
|
3. OpenShift Route가 공개 path를 해당 MCP Service로 전달하고 내부 고정 endpoint `/mcp`로 rewrite한다.
|
|
4. MCP 애플리케이션과 Tool Service의 1:1 매핑, Registry snapshot, Redis key와 readiness는 배포별로 유지한다.
|
|
5. Agent Builder는 각 공개 URL을 독립 MCP endpoint로 등록하고 endpoint별로 initialize한다.
|
|
6. 요청 body·header·Tool 이름은 어느 MCP Service로 보낼지 결정하지 못한다. 대상은 Helm topology만 정한다.
|
|
|
|
```text
|
|
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 검증 계층이 중복되므로 채택하지 않았다.
|