koseokmin
cb29b192b4
5cfb8a1이 .gitignore에 docs/를 넣고 68개 파일을 지웠다. 그런데
AgentBuilderContractExampleTest, ToolBundleContractExampleTest,
ArchitectureDocumentContractTest는 docs/ 아래 계약 예제와 architecture
문서를 입력으로 직접 읽는다. 그 결과 clean clone에서 테스트 10건이
입력을 찾지 못해 실패했다.
제외 범위를 원래 의도대로 좁힌다. 에이전트 산출물(AGENTS.md, .agents/,
.codex/, docs/superpowers/)은 계속 제외하고 저장소 문서는 추적한다.
문서는 삭제 직전 상태(3de052a)를 기준으로 복원하고, 그 위에 main 코드와
대조해 어긋난 부분을 고쳤다.
- ADR-0007을 Superseded로 바꾸고 ADR-0013을 새로 쓴다. route당 Tool
Service N개가 최종안이며, PortalToolRegistryClient가 이미 route별로
N개를 유지하고 있는데 ADR-0007은 "bundles는 항상 한 항목"을 Accepted
상태로 주장하고 있었다. ADR-0009 결정 4도 부분 대체한다.
- ADR-0008 파일 헤더가 Accepted였으나 ADR-0009가 이미 대체한 상태였다.
- 6078852의 endpoint 소유권 반전이 반영되지 않은 서술을 계약 v0.2,
bundle 설정 예제, Tool 적재 안내에서 고친다.
- Portal registry 계약 v0.1과 route key 규약을 새로 문서화한다. 둘 다
구현은 있는데 계약 문서가 없었다.
- MCP SDK 2.0.0 SBOM을 추가한다.
번호 주석: ADR-0011과 0012는 feature/mcp-integration이 Tool inputSchema
정책에 쓰고 있어 비워 둔다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
59 lines
3.6 KiB
Markdown
59 lines
3.6 KiB
Markdown
# ADR-0008 공유 host의 path를 독립 MCP 배포로 연결한다
|
|
|
|
- 상태: Superseded
|
|
- 결정일: 2026-08-05
|
|
- 대체 결정: [ADR-0009](ADR-0009-container-handles-public-mcp-path.md)
|
|
- 관련: [ADR-0006](ADR-0006-no-authentication-in-mcp.md), [ADR-0007](ADR-0007-one-mcp-per-tool-service.md)
|
|
|
|
> 이 문서는 검토 이력을 보존한다. 결정 3의 "공개 path를 내부 고정 endpoint `/mcp`로 rewrite한다"는
|
|
> [ADR-0009](ADR-0009-container-handles-public-mcp-path.md)이 대체했고, 결정 4의 1:1 매핑은
|
|
> [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.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 검증 계층이 중복되므로 채택하지 않았다.
|