GitOps 이전까지 쓸 배포 파이프라인과 Portal 모드 Chart를 추가한다

GitOps 저장소도 ArgoCD Application도 아직 없어, 그때까지 이 저장소가
push 방식 파이프라인(.gitea/workflows/)을 임시로 소유한다. 무엇을
포기하는지와 넘길 때 할 일은 deploy/README.md에 적었다.

Chart는 portal과 bundles 두 배포 모델을 모두 렌더링한다. ADR-0013이
ADR-0007을 대체했으므로 운영은 portal이 기준이지만, bundles 경로를
언제 삭제할지는 아직 정하지 않았다.

- .gitea/workflows/ci.yaml, deploy-openshift.yaml
- deploy/ci/render-manifests.sh, deploy/examples/
- Chart: mode 분기, selectedDeployment/tier helper, imagePullSecrets,
  toolService.apiKeySecret 참조
- extension-points.md에 미결 항목 9~12 추가

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -0,0 +1,82 @@
+name: CI
+
+# main push와 PR에서 같은 검증을 돌린다. 이 워크플로는 배포하지 않는다.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  # 빌드·렌더링 도구는 러너에 설치하지 않고 컨테이너로 가져온다.
+  # 러너에 JDK나 helm이 깔려 있는지에 파이프라인이 의존하지 않게 하기 위해서다.
+  # 러너가 host 모드(docker가 러너 호스트에서 직접 도는 구성)라는 전제다.
+  # 현재 .gitea/workflows/deploy.yaml이 호스트의 docker compose 스크립트를 부르므로 그 전제가 성립한다.
+  JDK_IMAGE: eclipse-temurin:21-jdk
+  HELM_IMAGE: alpine/helm:3.14.4
+
+jobs:
+  verify:
+    runs-on: ubuntu
+    steps:
+      - uses: actions/checkout@v4
+
+      # 컨테이너를 러너 사용자로 돌린다. root로 돌면 build/ 산출물이 root 소유가 되어
+      # 다음 실행의 checkout이 그 디렉터리를 지우지 못한다.
+      # ideaFormatCheck는 IDEA_FORMATTER가 없으면 경고만 남기고 건너뛴다.
+      # 들여쓰기·줄바꿈은 CI에서 검증되지 않는다는 뜻이다(README).
+      - name: Gradle check
+        run: |
+          docker run --rm \
+            --user "$(id -u):$(id -g)" \
+            -v "$PWD":/workspace -w /workspace \
+            -e GRADLE_USER_HOME=/workspace/.gradle/ci-home \
+            "$JDK_IMAGE" ./gradlew check --no-daemon
+
+      # HelmDeploymentContractTest는 values와 template의 정적 규칙만 본다.
+      # helper 오류와 조건 분기 실수는 실제로 렌더링해야 드러난다.
+      - name: Helm lint and template
+        run: |
+          docker run --rm \
+            --user "$(id -u):$(id -g)" \
+            -v "$PWD":/workspace -w /workspace \
+            --entrypoint sh \
+            "$HELM_IMAGE" deploy/ci/render-manifests.sh
+
+      # GitOps 저장소가 생기기 전까지, 이 산출물이 "무엇이 배포되는가"를 확인할 수 있는 유일한 형태다.
+      - name: Upload rendered manifests
+        uses: actions/upload-artifact@v3
+        with:
+          name: rendered-manifests
+          path: build/rendered
+
+  image:
+    runs-on: ubuntu
+    needs: verify
+    if: github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t "ax-hub-mcp-server:${{ github.sha }}" .
+
+      # registry가 아직 확정되지 않았으면 빌드까지만 하고 멈춘다.
+      # 없는 secret 때문에 파이프라인 전체가 실패로 보이는 것을 막는다.
+      # TODO: 사내 registry 확정 시 저장소 secret에 REGISTRY_HOST·REGISTRY_USER·REGISTRY_PASSWORD·IMAGE_REPOSITORY를 등록한다.
+      - name: Push image
+        env:
+          REGISTRY_HOST: ${{ secrets.REGISTRY_HOST }}
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+          IMAGE_REPOSITORY: ${{ secrets.IMAGE_REPOSITORY }}
+          IMAGE_TAG: ${{ github.sha }}
+        run: |
+          if [ -z "$REGISTRY_HOST" ] || [ -z "$IMAGE_REPOSITORY" ]; then
+            echo "REGISTRY_HOST 또는 IMAGE_REPOSITORY secret이 없어 push를 건너뛴다."
+            echo "이미지는 러너 로컬에만 있다: ax-hub-mcp-server:$IMAGE_TAG"
+            exit 0
+          fi
+          echo "$REGISTRY_PASSWORD" | docker login "$REGISTRY_HOST" -u "$REGISTRY_USER" --password-stdin
+          docker tag "ax-hub-mcp-server:$IMAGE_TAG" "$IMAGE_REPOSITORY:$IMAGE_TAG"
+          docker push "$IMAGE_REPOSITORY:$IMAGE_TAG"
+          echo "배포에 쓸 tag: $IMAGE_TAG"

.gitea/workflows/deploy-openshift.yaml

@@ -0,0 +1,114 @@
+name: Deploy to OpenShift
+
+# GitOps 저장소와 ArgoCD Application이 아직 없어 CD를 push 방식으로 돌린다.
+# 파이프라인이 클러스터에 직접 helm upgrade를 건다.
+#
+# 이 방식의 대가를 숨기지 않는다.
+#   - 클러스터의 실제 상태가 저장소와 자동으로 맞춰지지 않는다. 누가 oc edit으로 고치면 그대로 남는다.
+#   - 배포 이력이 Helm release history에만 남는다. git revert로 되돌릴 수 없다.
+#   - 파이프라인이 클러스터 자격증명을 들고 있어야 한다.
+#
+# 그래서 자동 트리거를 두지 않고 사람이 값을 확인하고 실행한다.
+# GitOps 저장소가 준비되면 이 워크플로를 삭제하고, ArgoCD Application이 이 Chart를 당겨 가게 한다.
+# 그때까지의 인수인계 형태는 CI가 올리는 rendered-manifests 아티팩트다.
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 배포 환경 (dev | test | prod)
+        required: true
+        default: dev
+      mode:
+        description: 배포 모델 (portal | bundles)
+        required: true
+        default: portal
+      deploymentKey:
+        description: mode=bundles일 때 설치할 배포 key. portal이면 비워 둔다
+        required: false
+        default: ""
+      imageTag:
+        description: 배포할 이미지 tag. CI가 push한 commit sha를 그대로 넣는다
+        required: true
+
+env:
+  HELM_IMAGE: alpine/helm:3.14.4
+
+jobs:
+  deploy:
+    runs-on: ubuntu
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy
+        env:
+          ENVIRONMENT: ${{ github.event.inputs.environment }}
+          MODE: ${{ github.event.inputs.mode }}
+          DEPLOYMENT_KEY: ${{ github.event.inputs.deploymentKey }}
+          IMAGE_TAG: ${{ github.event.inputs.imageTag }}
+          IMAGE_REPOSITORY: ${{ secrets.IMAGE_REPOSITORY }}
+          OCP_SERVER: ${{ secrets.OCP_SERVER }}
+          OCP_TOKEN: ${{ secrets.OCP_TOKEN }}
+          # 사내 CA가 서명한 API 인증서일 때 PEM 전체를 넣는다. 비어 있으면 러너의 신뢰 저장소를 쓴다.
+          OCP_CA_CERT: ${{ secrets.OCP_CA_CERT }}
+          OCP_NAMESPACE_DEV: ${{ secrets.OCP_NAMESPACE_DEV }}
+          OCP_NAMESPACE_TEST: ${{ secrets.OCP_NAMESPACE_TEST }}
+          OCP_NAMESPACE_PROD: ${{ secrets.OCP_NAMESPACE_PROD }}
+        run: |
+          set -eu
+
+          CA_FILE=.ocp-ca.crt
+          trap 'rm -f "$CA_FILE"' EXIT
+
+          case "$ENVIRONMENT" in
+            dev) NAMESPACE=$OCP_NAMESPACE_DEV ;;
+            test) NAMESPACE=$OCP_NAMESPACE_TEST ;;
+            prod) NAMESPACE=$OCP_NAMESPACE_PROD ;;
+            *) echo "environment는 dev|test|prod여야 한다: $ENVIRONMENT" >&2; exit 1 ;;
+          esac
+
+          for required in OCP_SERVER OCP_TOKEN IMAGE_REPOSITORY; do
+            eval "value=\${$required}"
+            if [ -z "$value" ]; then
+              echo "$required secret이 없다. 플랫폼 담당자에게 발급받아 저장소 secret에 등록한다." >&2
+              exit 1
+            fi
+          done
+          if [ -z "$NAMESPACE" ]; then
+            echo "$ENVIRONMENT namespace secret이 없다." >&2
+            exit 1
+          fi
+
+          # release 이름은 mode가 정한다. portal은 배포가 하나이고, bundles는 배포 key마다 하나다.
+          if [ "$MODE" = "portal" ]; then
+            RELEASE=axhub-mcp
+            EXTRA=""
+          else
+            if [ -z "$DEPLOYMENT_KEY" ]; then
+              echo "mode=bundles에는 deploymentKey가 필요하다." >&2
+              exit 1
+            fi
+            RELEASE="$DEPLOYMENT_KEY-mcp"
+            EXTRA="--set deploymentKey=$DEPLOYMENT_KEY"
+          fi
+
+          # 사내 CA를 신뢰시키는 정상 경로다. TLS 검증을 끄는 스위치는 두지 않는다.
+          if [ -n "$OCP_CA_CERT" ]; then
+            printf '%s\n' "$OCP_CA_CERT" > "$CA_FILE"
+            EXTRA="$EXTRA --kube-ca-file /workspace/$CA_FILE"
+          fi
+
+          # token은 helm 인자로 들어간다. 컨테이너는 명령마다 새로 뜨고 바로 사라지지만,
+          # 러너를 여러 팀이 공유하게 되면 kubeconfig 파일 방식으로 바꾼다.
+          # --atomic: 실패하면 직전 revision으로 되돌린다. 반쯤 배포된 상태로 두지 않는다.
+          docker run --rm \
+            -v "$PWD":/workspace -w /workspace \
+            "$HELM_IMAGE" upgrade --install "$RELEASE" deploy/helm/mcp-server \
+              -f "deploy/helm/mcp-server/values-$ENVIRONMENT.yaml" \
+              --namespace "$NAMESPACE" \
+              --set "mode=$MODE" \
+              $EXTRA \
+              --set "image.repository=$IMAGE_REPOSITORY" \
+              --set "image.tag=$IMAGE_TAG" \
+              --kube-apiserver "$OCP_SERVER" \
+              --kube-token "$OCP_TOKEN" \
+              --atomic --timeout 10m

.gitignore

@@ -16,12 +16,15 @@ tmp/
 .claude/
 .idea/codeStyles/
 AGENTS.md
-docs/
 
 # 에이전트 작업 계획·산출물. 저장소 문서가 아니므로 반입 대상에 넣지 않는다.
 # 결정은 docs/decisions/의 ADR에, 규칙은 계약 테스트에 남긴다(AGENTS.md 4절).
 docs/superpowers/
 
+# 에이전트 도구가 로컬에 만드는 상태 파일. 개발자마다 달라지므로 공유하지 않는다.
+.ua/
+skills-lock.json
+
 # Local configuration and secrets
 .env
 .env.*

README.md

@@ -52,8 +52,9 @@ $env:MCP_LOCAL_TOOL_REGISTRY_FILE='file:C:/path/local-tools.json'
 
 ## 공개 계약
 
-- 공개 endpoint: `POST https://{global.mcpHost}{deployments.<key>.publicPath}`
-- 예: `https://mcp-dev.apps.example.internal/mcp/processing-critical`
+- 공개 endpoint: `POST https://{global.mcpHost}/mcp/{routeKey}`
+- 예: `https://mcp-dev.apps.example.internal/mcp/cus`
+- route key는 URI에서만 결정된다. route 없는 `/mcp` 호출은 거부한다
 - OpenShift Route는 공개 path로 MCP Service만 선택하고, 컨테이너가 같은 path를 직접 처리
 - Method: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`
 - Response: 항상 단일 `application/json` JSON-RPC response
@@ -70,9 +71,9 @@ Agent Builder는 공개 URL마다 별도 MCP로 등록하고 initialize한다. U
 | 환경 | Tool 원천 | Redis |
 |---|---|---|
 | `local` | local JSON fixture | 사용 안 함 |
-| 운영(`ocp`) | 이 배포가 보는 Tool Service 매니페스트를 주기적으로 pull | 성공 snapshot 공유와 warm start에만 사용 |
+| 운영(`ocp`) | Portal registry가 알려 준 route별 Tool Service 매니페스트를 주기적으로 pull | 성공 snapshot 공유와 Portal registry fallback에 사용 |
 
-요청 경로의 `tools/list`와 `tools/call`은 in-memory snapshot만 읽는다. 운영 refresh는 bundle별 last-good을 유지하고, 모든 bundle에 사용 가능한 성공본이 있을 때만 aggregate를 교체한다. 조회 실패만으로 Tool을 제거하지 않으며 정상 매니페스트에서 삭제가 확인될 때만 반영한다. 코드는 bundle N개 병합을 지원하지만 **운영 배포의 bundle은 항상 하나다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)).
+요청 경로의 `tools/list`와 `tools/call`은 in-memory snapshot만 읽는다. 운영 refresh는 bundle별 last-good을 유지하고, 그 route의 모든 bundle에 사용 가능한 성공본이 있을 때만 route의 aggregate를 교체한다. 조회 실패만으로 Tool을 제거하지 않으며 정상 매니페스트에서 삭제가 확인될 때만 반영한다. **한 route에는 Tool Service가 여럿 붙을 수 있고, 병합 단위는 route다**([ADR-0013](docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md)).
 
 Tool 실행 주소는 local `_meta.endpoint` 또는 운영 `baseEndpoint` 설정에서만 정한다. Agent Builder의 `arguments`와 Tool Service 매니페스트는 호출 대상을 바꿀 수 없다.
 
@@ -123,31 +124,19 @@ MDC는 사용하지 않는다. 로그에는 `guid`와 `x-request-id`만 남기
 readiness는 첫 Tool discovery 시도가 끝나고 usable in-memory snapshot이 있을 때만 UP이다. 원천 장애 중에도
 기존 memory 또는 Redis last-good이 있으면 서비스를 유지하고, 아무 성공본도 없으면 트래픽을 받지 않는다.
 
-**MCP 배포 하나는 Tool Service 하나만 본다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 bundle 목록을 늘리는 것이 아니라 배포를 하나 더 만드는 것이다. 외부에서는 같은 host의 고유 path로 각 배포를 노출하고 컨테이너가 그 path를 그대로 처리한다([ADR-0009](docs/decisions/ADR-0009-container-handles-public-mcp-path.md)). 배포는 업무 × 중요도 등급으로 나뉘며, 등급이 replica 수와 PodDisruptionBudget을 정한다.
+**route↔Tool Service 매핑의 원천은 Portal이다**([ADR-0013](docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md)). 배포 하나가 N개 route를 서비스하고, route key는 `/mcp/{routeKey}` URI에서만 결정된다. 매핑이 바뀌어도 재배포하지 않는다. 외부에서는 같은 host의 path로 route를 구분하고 컨테이너가 그 path를 그대로 처리한다([ADR-0009](docs/decisions/ADR-0009-container-handles-public-mcp-path.md)).
 
-배포 정의는 [Helm Chart](deploy/helm/mcp-server/) 하나뿐이다. 배포 토폴로지는 `values.yaml`이, 환경 차이는 `values-{dev,test,prod}.yaml`이 소유한다. 설치할 배포 하나는 `--set`으로 고른다.
+배포 정의는 [Helm Chart](deploy/helm/mcp-server/) 하나뿐이다. Chart는 배포 모델 둘을 `mode`로 고른다. `portal`이 현재 애플리케이션이 실제로 도는 경로이고, `bundles`는 ADR-0013이 대체한 1:1 구성([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md))이다.
 
 ```bash
-helm upgrade --install processing-critical-mcp deploy/helm/mcp-server -f deploy/helm/mcp-server/values-dev.yaml --set deploymentKey=processing-critical -n <namespace>
+helm upgrade --install axhub-mcp deploy/helm/mcp-server -f deploy/helm/mcp-server/values-dev.yaml -n <namespace>
 ```
 
-**MCP Server와 Tool Service는 같은 namespace에 배포한다.** 그래서 values에는 Tool Service의 이름만 적고 주소는 template이 조립한다. 환경마다 URL을 반복해 적지 않으므로 오타로 엉뚱한 곳을 호출할 수 없다.
+배포 토폴로지는 `values.yaml`이, 환경 차이는 `values-{dev,test,prod}.yaml`이 소유한다. 두 모드의 차이, 등급별 가용성, 확정 전 임시값은 [deploy/README.md](deploy/README.md)가 정본이다.
 
-```yaml
-deployments:
-  processing-critical:
-    name: processing-critical-mcp
-    service: processing-critical-tools   # ← 이름만. 주소는 template이 만든다
-    namePrefix: "processing."            # ← 업무 단위. 등급을 넣지 않는다
-    tier: critical
-    publicPath: /mcp/processing-critical # ← 같은 환경 host 안에서 유일
-```
+평문 manifest가 필요하면 `deploy/ci/render-manifests.sh`가 `helm template`으로 만든다. 별도 YAML을 저장소에 두지 않는다 — 두 벌은 반드시 어긋난다.
 
-배포가 10개든 20개든 파일 수는 늘지 않는다. 자세한 사용법은 [deploy/README.md](deploy/README.md)에 있다.
-
-평문 manifest가 필요하면 `helm template`으로 만든다. 별도 YAML을 저장소에 두지 않는다 — 두 벌은 반드시 어긋난다.
-
-빌드·이미지·배포 실행 방식은 사내 표준 CI/CD가 담당하며 이 저장소가 정하지 않는다. 배포 시 알아야 할 앱 제약은 [deploy/README.md](deploy/README.md)에 정리했다.
+빌드·이미지·배포 실행 방식은 원래 사내 표준 CI/CD가 담당한다. GitOps 저장소가 준비되기 전까지만 `.gitea/workflows/`가 임시로 그 역할을 하며, 그 방식이 무엇을 포기하는지와 넘길 때 할 일은 [deploy/README.md](deploy/README.md#gitops-저장소가-없는-동안의-우회)에 적었다. 배포 시 알아야 할 앱 제약도 같은 문서에 정리했다.
 
 ## 문서 R&R
 
@@ -157,8 +146,10 @@ deployments:
 | [architecture.md](docs/architecture.md) | 현재 코드 구조, 요청 흐름, 내부 책임과 장애 동작 |
 | [Agent Builder-MCP contracts](docs/contracts/agent-builder-mcp/README.md) | Agent Builder와의 HTTP/JSON-RPC wire 계약 |
 | [Tool Service-MCP contracts](docs/contracts/tool-service-mcp/README.md) | 매니페스트와 Tool 실행 wire 계약 |
+| [Portal-MCP contracts](docs/contracts/portal-mcp/README.md) | route별 Tool Server registry 조회 계약 |
 | [decisions](docs/decisions/README.md) | 결정 이유와 대안 이력 |
 | [extension-points.md](docs/extension-points.md) | 아직 미합의인 항목과 운영 보완 작업 |
+| [SBOM](docs/sbom/README.md) | 런타임 전이 의존·빌드 환경 목록과 라이선스 (CycloneDX 1.5) |
 | [codex-workflow.md](docs/codex-workflow.md) | 저장소 작업 규칙과 공개 정책 |
 
 Superseded/Rejected 문서는 이력일 뿐 현재 구현 근거가 아니다. 코드나 공개 계약을 변경할 때는 가까운 테스트와 해당 현재 계약을 함께 수정한다. 변경을 마치기 전에 실행할 검증 명령은 [AGENTS.md](AGENTS.md)의 완료 기준이 정본이다.

deploy/README.md

@@ -1,68 +1,72 @@
 # 배포 정의
 
-이 디렉터리는 **배포될 대상**을 정의한다. 빌드·이미지·배포 실행 방식은 사내 표준 CI/CD가 담당하며
-이 저장소가 정하지 않는다.
+이 디렉터리는 **배포될 대상**과, 그것을 클러스터에 올리는 **임시 경로**를 정의한다.
+빌드·배포 실행 방식의 정본은 원래 사내 표준 CI/CD이며 이 저장소가 정하지 않는다.
+지금 여기 파이프라인이 있는 이유는 [아래](#gitops-저장소가-없는-동안의-우회)에 적었다.
 
 ## Helm Chart
 
-[helm/mcp-server/](helm/mcp-server/)가 유일한 배포 정의다. values는 두 축으로 나뉜다.
+[helm/mcp-server/](helm/mcp-server/)가 유일한 배포 정의다.
+
+### 배포 모델이 두 가지다
+
+| mode | 무엇이 route↔Tool Service 매핑을 소유하는가 | 근거 |
+|---|---|---|
+| `portal` (기본값) | **Portal.** 배포 하나가 N개 route를 서비스하고 route key는 `/mcp/{routeKey}` URI에서만 온다 | [ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) |
+| `bundles` | **배포 정의.** 배포 하나가 Tool Service 하나만 보고 매핑을 배포 시점에 못박는다 | [ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md) |
+
+**현재 애플리케이션이 실제로 도는 경로는 `portal`이다.** `bundles`는 ADR-0013이 대체했지만 코드 경로가
+남아 있어 1:1 검증과 격리 배포에 쓸 수 있다. 어느 쪽을 운영에 쓸지는 아직 확정되지 않았고
+[extension-points.md](../docs/extension-points.md)에서 관리한다.
+
+`mode`를 바꾸면 ConfigMap의 Tool 원천이 통째로 바뀐다. 값 하나로 배포 성격이 달라지므로
+설치 명령에 항상 명시한다.
+
+### values는 두 축으로 나뉜다
 
 | 파일 | 소유하는 것 |
 |---|---|
-| `values.yaml` | **배포 토폴로지.** 어떤 MCP가 어떤 Tool Service를 보는가, 공개 path, 가용성 등급 |
-| `values-{dev,test,prod}.yaml` | **환경 차이.** namespace, 이미지, 공개 host·허용 CIDR, 등급별 replica·PDB, 리소스 |
+| `values.yaml` | **배포 토폴로지.** mode, portal 배포 정의, bundles 배포 목록, 등급 기준 |
+| `values-{dev,test,prod}.yaml` | **환경 차이.** namespace, 공개 host·허용 CIDR, Portal registry 주소, 등급별 replica·PDB, 리소스 |
 
-설치할 때 두 번째 축을 `-f`로, 첫 번째 축에서 고를 배포 하나를 `--set deploymentKey=`로 지정한다.
+환경 파일은 토폴로지를 갖지 않는다. `HelmDeploymentContractTest`가 그 경계를 고정한다.
 
 ```bash
-helm upgrade --install processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml --set deploymentKey=processing-critical -n <namespace>
+# portal 모드. 배포가 하나이므로 deploymentKey가 없다.
+helm upgrade --install axhub-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml -n <namespace>
+
+# bundles 모드. 설치할 배포 하나를 반드시 고른다.
+helm upgrade --install processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml \
+  --set mode=bundles --set deploymentKey=processing-critical -n <namespace>
 ```
 
-`deploymentKey`에는 기본값이 없다. 지정을 빠뜨리면 렌더링 단계에서 멈춘다.
-엉뚱한 배포가 조용히 설치되는 것보다 낫다.
+`deploymentKey`에는 기본값이 없다. `bundles`에서 지정을 빠뜨리면 렌더링 단계에서 멈춘다.
+엉뚱한 배포가 조용히 설치되는 것보다 낫다. 반대로 `portal`에서 `deploymentKey`를 주면 역시 멈춘다.
+route를 배포 정의에 적기 시작하면 Portal을 원천으로 둔 이유가 사라지기 때문이다.
 
-### 공유 host와 배포별 path
+### 공개 host와 path
 
-[ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md)에 따라 한 환경은 하나의 공개 host를 사용하고,
-각 Helm release는 고유 path의 OpenShift Route를 만든다. Route는 Service만 선택하고 공개 path를 그대로
-전달하며, 컨테이너가 같은 path를 직접 처리한다.
+한 환경은 하나의 공개 host를 사용한다([ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md)).
+Route는 Service만 선택하고 공개 path를 그대로 전달하며, 컨테이너가 같은 path를 직접 처리한다.
+
+`portal` 모드에서 Route path는 `/mcp` 하나다. OpenShift Route의 path는 prefix 매칭이므로
+`/mcp/{routeKey}` 전체가 이 Route로 들어오고, route 구분은 컨테이너가 한다.
+
+```text
+https://mcp-dev.apps.example.internal/mcp/cus -> axhub-mcp:8080/mcp/cus
+https://mcp-dev.apps.example.internal/mcp/sal -> axhub-mcp:8080/mcp/sal
+```
+
+`bundles` 모드에서는 Route가 배포마다 하나씩 생기고 path가 배포별로 다르다.
 
 ```text
 https://mcp-dev.apps.example.internal/mcp/processing-critical -> processing-critical-mcp:8080/mcp/processing-critical
-https://mcp-dev.apps.example.internal/mcp/information-standard -> information-standard-mcp:8080/mcp/information-standard
 ```
 
-공개 URL은 각각 독립된 MCP다. Agent Builder는 URL별로 등록하고 initialize하며, 한 Route나 MCP Pod의
-장애가 다른 path의 Deployment로 전파되지 않는다.
-
-### MCP 하나는 Tool Service 하나만 본다
-
-[ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md)의 결정이다. 대상을 늘리는 방법은
-bundle 목록을 늘리는 것이 아니라 **배포를 하나 더 만드는 것**이다.
-
-```yaml
-deployments:
-  processing-critical:
-    name: processing-critical-mcp
-    service: processing-critical-tools   # ← 이름만. 주소는 template이 만든다
-    namePrefix: "processing."            # ← 업무 단위. 등급을 넣지 않는다
-    tier: critical
-    publicPath: /mcp/processing-critical # ← 환경 host 안에서 유일
-```
-
-배포가 10개든 20개든 **파일 수는 늘지 않는다.** 전체 매핑을 한 화면에서 검토할 수 있고,
-`--set`으로 고르는 값 하나만 배포마다 달라진다.
-
-MCP Server와 Tool Service는 같은 namespace에 배포하므로 values에는 서비스 이름만 적고
-주소는 template이 조립한다. 환경마다 URL을 반복하지 않으므로 오타로 다른 대상을 호출할 수 없다.
-
-`identity`도 `{배포 이름}-{global.env}`로 template이 조립한다. 현재 Redis cache 구현이 이 값을
-사용하지만, key namespace와 공유 정책은 아직 확정되지 않았다.
+두 경우 모두 공개 URL은 각각 독립된 MCP다. Agent Builder는 URL별로 등록하고 initialize한다.
 
 ### 가용성 등급
 
-배포를 업무 × 중요도로 나누는 목적은 **중요 등급에만 비용을 쓰기 위해서**다.
-
 ```yaml
 tiers:
   critical: { replicas: 3, podDisruptionBudget: true, spreadAcrossNodes: true }
@@ -71,27 +75,74 @@ tiers:
 
 test와 prod의 `critical`은 **replica 2 이상, PodDisruptionBudget, 노드 분산 설정이 필수**다. replica가
 1이면 rolling update 중 반드시 공백이 생기고, PDB가 없으면 노드 drain이 마지막 Pod을 내릴 수 있다.
-`HelmDeploymentContractTest`는 values와 template의 정적 규칙을 검사한다. dev는 배포마다 Pod 1개로
-운영하므로 이 검사 대상이 아니다.
+dev는 배포마다 Pod 1개로 운영하므로 이 검사 대상이 아니다.
 
-정적 테스트는 Helm 렌더러를 실행하지 않는다. 실제 배포 파이프라인은 사용하는 환경과 등급별로
-`helm lint`와 `helm template`을 실행해 병합된 values와 생성 YAML을 확인해야 한다.
+**`portal` 모드에서 등급별 물리 분리는 성립하지 않는다.** 배포가 하나이므로 전 route가 같은
+프로세스·같은 replica set을 공유한다([ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) 전제 2).
+`tiers`는 그 하나의 배포에 어떤 가용성 기준을 적용할지만 정한다.
+
+### 렌더링 검증
+
+`HelmDeploymentContractTest`는 values와 template의 **정적 규칙**만 본다. helper 오류, 조건 분기 실수,
+들여쓰기는 실제로 렌더링해야 드러난다. 두 검사는 서로를 대신하지 못한다.
 
 ```bash
-helm lint helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-critical
-helm template processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-critical
-helm template processing-standard-mcp helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-standard
+deploy/ci/render-manifests.sh   # 환경 × 모드 전 조합 lint + template
 ```
 
-**나누는 것만으로 가용성이 생기지는 않는다.** 같은 노드 배치, namespace 쿼터, 공통 Redis·클러스터
-장애는 분할로 막히지 않는다. 남은 작업은 [extension-points.md](../docs/extension-points.md)의
-"운영 적용 전 필수 보완"에서 관리한다.
+CI가 매 push에서 같은 스크립트를 돌리고 결과를 `rendered-manifests` 아티팩트로 올린다.
 
-### dev에서 MCP에 연결되지 않을 때
+## GitOps 저장소가 없는 동안의 우회
+
+Chart를 어디에 둘지, 배포를 무엇이 실행할지는 아직 확정되지 않았다. GitOps 저장소도 ArgoCD
+Application도 없다. 그동안 파이프라인을 멈춰 두지 않기 위해 아래 형태로 돌린다.
+
+| 파일 | 트리거 | 하는 일 |
+|---|---|---|
+| `.gitea/workflows/ci.yaml` | main push, PR | `gradlew check`, Chart lint·template, 이미지 빌드·push |
+| `.gitea/workflows/deploy-openshift.yaml` | 수동 실행 | 고른 환경·모드로 `helm upgrade --install` |
+| `.gitea/workflows/deploy.yaml` | main push | 기존 VM docker compose 배포 |
+
+### 이 방식이 무엇을 포기하는가
+
+숨기지 않고 적는다. GitOps로 넘어가는 판단의 근거가 되기 때문이다.
+
+- **클러스터 상태가 저장소와 자동으로 맞춰지지 않는다.** 누가 `oc edit`으로 고치면 그대로 남는다.
+- **배포 이력이 Helm release history에만 남는다.** `git revert`로 되돌릴 수 없고 `helm rollback`을 써야 한다.
+- **파이프라인이 클러스터 자격증명을 들고 있어야 한다.** 러너를 신뢰 경계 안에 두어야 한다.
+- **어떤 이미지가 어느 환경에 떠 있는지 저장소만 봐서는 모른다.** 수동 실행 이력을 봐야 한다.
+
+이 때문에 OpenShift 배포에는 자동 트리거를 두지 않았다. 사람이 환경·모드·이미지 tag를 확인하고 실행한다.
+
+### GitOps 저장소가 생기면
+
+1. `deploy-openshift.yaml`을 삭제한다. 클러스터 자격증명 secret도 회수한다.
+2. ArgoCD Application이 이 Chart를 참조하게 하거나, Chart 자체를 배포 저장소로 옮긴다.
+3. CI의 `rendered-manifests` 아티팩트가 **인수인계 형태**다. 그 시점에 무엇이 배포되고 있었는지가
+   거기 그대로 있으므로, 옮긴 뒤 diff로 대조한다.
+4. `deploy.yaml`의 VM compose 배포를 계속 쓸지 결정한다. 스크립트가 저장소 밖(러너의
+   `/home/ubuntu/apps/prd-dap-gateway/deploy.sh`)에 있어 이 저장소가 내용을 모른다.
+
+### 아직 필요한 secret
+
+확정 전까지 CI는 이미지 빌드까지만 하고 push를 건너뛴다. 없는 secret 때문에 파이프라인 전체가
+실패로 보이지 않게 하기 위해서다.
+
+| secret | 쓰는 곳 | 없으면 |
+|---|---|---|
+| `REGISTRY_HOST`·`REGISTRY_USER`·`REGISTRY_PASSWORD`·`IMAGE_REPOSITORY` | CI 이미지 push | push 건너뜀 |
+| `OCP_SERVER`·`OCP_TOKEN` | OpenShift 배포 | 배포 실패 |
+| `OCP_CA_CERT` | API 인증서를 사내 CA가 서명했을 때 | 러너의 신뢰 저장소를 쓴다. 사내 CA면 TLS 검증 실패 |
+| `OCP_NAMESPACE_DEV`·`OCP_NAMESPACE_TEST`·`OCP_NAMESPACE_PROD` | OpenShift 배포 | 배포 실패 |
+
+## dev에서 MCP에 연결되지 않을 때
 
 **먼저 Tool Service가 떠 있는지 확인한다.** readiness가 usable snapshot을 요구하므로, Tool Service가
-없으면 MCP Pod은 Ready가 되지 못하고 Service endpoint에서 빠진다. dev는 배포마다 Pod 1개라
-그 순간 그 MCP로는 아예 연결되지 않는다. "MCP가 죽었다"가 아니라 "읽을 Tool이 없다"는 뜻이다.
+없으면 MCP Pod은 Ready가 되지 못하고 Service endpoint에서 빠진다.
+"MCP가 죽었다"가 아니라 "읽을 Tool이 없다"는 뜻이다.
+
+`portal` 모드에서는 Portal registry 조회부터 확인한다. registry를 못 읽으면 route 자체가 등록되지 않아
+`/mcp/{routeKey}` 호출이 route key 검증에서 거부된다.
 
 ```bash
 kubectl get pod -l app=<배포 이름>          # 0/1 Ready이면 이 경우다
@@ -99,14 +150,15 @@ kubectl describe pod <pod>                  # Readiness probe 실패 사유
 kubectl port-forward <pod> 9090:9090        # /actuator/toolBundles로 bundle 상태 확인
 ```
 
-Tool Service가 뜨면 다음 refresh 주기(기본 30초) 안에 스스로 Ready가 된다. 재기동할 필요가 없다.
+Tool Service가 뜨면 다음 refresh 주기 안에 스스로 Ready가 된다. 재기동할 필요가 없다.
 `/actuator/toolBundles`는 management 포트라 NetworkPolicy가 관제 namespace로 제한하므로,
 개발자는 위처럼 `port-forward`로 본다.
 
 ## 확정 전 임시값
 
-`values.yaml`의 Tool Service 이름·이미지 경로와 `values-{env}.yaml`의 namespace·공개 host·Route 허용 CIDR은 자리표시자다.
-각 파일의 `TODO` 주석을 참고해 확정 시 교체하고, 존재하지 않는 배포는 `deployments`에서 삭제한다.
+`values.yaml`의 이미지 경로와 Tool Service 이름, `values-{env}.yaml`의 namespace·공개 host·Route 허용
+CIDR·Portal registry 주소는 자리표시자다. 각 파일의 `TODO` 주석을 참고해 확정 시 교체하고,
+존재하지 않는 배포는 `deployments`에서 삭제한다.
 
 ## 배포 시 알아야 할 앱 제약
 
@@ -119,14 +171,14 @@ Tool Service가 뜨면 다음 refresh 주기(기본 30초) 안에 스스로 Read
 | `terminationGracePeriodSeconds`는 Spring drain보다 길어야 한다 | [architecture.md의 요청 시간 예산](../docs/architecture.md#요청-시간-예산) |
 | **NetworkPolicy는 필수다. 비활성화 스위치를 두지 않았다** | [ADR-0006](../docs/decisions/ADR-0006-no-authentication-in-mcp.md) |
 | 공개 path는 Route와 컨테이너 endpoint가 동일하게 사용한다 | [ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md) |
+| route↔Tool Service 매핑의 원천은 Portal이다 | [ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) |
+| Portal 응답 모양과 실패 처리 | [Portal-MCP 계약 v0.1](../docs/contracts/portal-mcp/protocol-v0.1-registry.md) |
 | Redis key·TTL·공유 정책은 확정 전이다 | [extension-points.md](../docs/extension-points.md#운영-적용-전-필수-보완) |
-| bundle은 정확히 하나다 | [ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md) |
 
 Route IP allowlist와 NetworkPolicy는 특히 중요하다. 이 서버는 인증·인가를 하지 않으므로 `/mcp`에
 도달할 수 있다는 것이 곧 인가다. Route는 Agent Builder 고정 egress CIDR만 받고, NetworkPolicy는 Route
 backend인 ingress controller와 명시한 Agent Builder namespace만 업무 포트에 허용한다.
 
-## 미확정 항목
-
-배포 정의를 이 저장소가 어디까지 소유하는지, namespace·registry 명명 규칙은 아직 확정되지 않았다.
-[docs/extension-points.md](../docs/extension-points.md)에서 관리한다.
+`portal` 모드는 여기에 하나를 더한다. **MCP는 Portal registry가 준 주소를 그대로 호출한다.** Portal이
+신뢰 경계 안에 있다는 전제가 깨지면 MCP의 outbound 대상이 통째로 바뀐다([ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) 전제 4).
+egress 제한은 아직 없으며 [extension-points.md](../docs/extension-points.md#운영-적용-전-필수-보완)에서 관리한다.

deploy/ci/render-manifests.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+# Chart를 실제로 렌더링해 배포될 YAML을 만든다.
+#
+# 존재 이유가 둘이다.
+#   1. 검증. HelmDeploymentContractTest는 values와 template의 정적 규칙만 본다.
+#      helper 오류, 잘못된 들여쓰기, 조건 분기 실수는 렌더링해야 드러난다.
+#   2. 인수인계. GitOps 저장소가 아직 없으므로 여기서 나온 YAML이 "지금 무엇이 배포되는가"의
+#      유일한 확인 가능한 형태다. 저장소가 생기면 이 산출물을 그대로 옮기면 된다.
+#
+# helm 바이너리가 PATH에 있어야 한다. CI는 helm 컨테이너 안에서 이 스크립트를 실행한다.
+set -eu
+
+CHART=deploy/helm/mcp-server
+OUT=${OUT_DIR:-build/rendered}
+
+# values.yaml의 deployments에서 배포 key 목록을 뽑는다.
+# 목록의 정본은 values.yaml 하나이며 여기에 복사해 두지 않는다.
+deployment_keys() {
+    sed -n '/^deployments:/,/^[a-z]/p' "$CHART/values.yaml" |
+        sed -n 's/^  \([a-z0-9-]*\):$/\1/p'
+}
+
+rm -rf "$OUT"
+mkdir -p "$OUT"
+
+keys=$(deployment_keys)
+if [ -z "$keys" ]; then
+    echo "values.yaml의 deployments에서 배포 key를 찾지 못했다. 형식이 바뀌었는지 확인한다." >&2
+    exit 1
+fi
+
+for env in dev test prod; do
+    values="$CHART/values-$env.yaml"
+    namespace="ax-hub-$env"
+
+    # portal 모드. 배포 하나가 전 route를 서비스한다(ADR-0013).
+    echo "== lint  $env / portal"
+    helm lint "$CHART" -f "$values"
+    echo "== render $env / portal"
+    helm template axhub-mcp "$CHART" -f "$values" \
+        --namespace "$namespace" \
+        >"$OUT/$env-portal.yaml"
+
+    # bundles 모드. 배포마다 Tool Service 하나(ADR-0007).
+    # 토폴로지 전체를 돌려야 등급별 replica·PDB·노드 분산 분기가 모두 렌더링된다.
+    for key in $keys; do
+        echo "== lint  $env / bundles / $key"
+        helm lint "$CHART" -f "$values" --set mode=bundles --set "deploymentKey=$key"
+        echo "== render $env / bundles / $key"
+        helm template "$key-mcp" "$CHART" -f "$values" \
+            --set mode=bundles --set "deploymentKey=$key" \
+            --namespace "$namespace" \
+            >"$OUT/$env-bundles-$key.yaml"
+    done
+done
+
+echo
+echo "렌더링 결과: $OUT"
+ls -1 "$OUT"

deploy/examples/axhub-mcp-dev-manual.template.yaml

@@ -0,0 +1,277 @@
+# AX HUB MCP 서버 개발계 수동 배포 샘플
+#
+# 주의:
+# - 이 파일은 Helm template이 아니라, AA와 값을 협의한 뒤 수동으로 적용할 Raw OpenShift YAML 샘플이다.
+# - "{{대문자_이름}}"은 확정되지 않은 값이다. 모든 자리표시자를 실제 값으로 교체한 뒤 적용한다.
+# - 비밀번호와 API Key를 담는 Secret 및 그 참조는 현재 사용하지 않으므로 포함하지 않았다.
+# - Harbor 인증이 필요하면 AA가 별도로 ServiceAccount에 image pull secret을 연결해야 한다.
+# - 이 파일은 임시 수동 배포용 예제이며, 배포 정의의 정본은 deploy/helm/mcp-server Chart다.
+#
+# AA와 협의할 값:
+# - {{DEV_NAMESPACE}}: MCP 서버를 배포할 개발계 namespace
+# - {{HARBOR_IMAGE_REPOSITORY}}: Harbor project를 포함한 이미지 경로. 예: harbor.example/axhub/axhub-mcp
+# - {{IMAGE_TAG}}: AA가 Podman으로 만들어 Push한 이미지 tag
+# - {{DEV_MCP_HOST}}: 개발계 OpenShift Route host
+# - {{AGENT_BUILDER_EGRESS_CIDR}}: Route 접근을 허용할 Agent Builder의 고정 egress CIDR
+# - {{AGENT_BUILDER_NAMESPACE}}: Agent Builder Pod이 있는 namespace
+# - {{DEV_PORTAL_REGISTRY_URL}}: 개발계 Portal registry API 주소
+# - {{REDIS_SERVICE_HOST}}: 개발계 Redis Service host 또는 FQDN
+# - {{CONFIG_VERSION}}: ConfigMap을 바꿀 때마다 증가시키는 값. 예: 1, 2, 3
+#
+# 적용 전 자리표시자 확인 예시(PowerShell):
+# Get-Content .\deploy\examples\axhub-mcp-dev-manual.template.yaml |
+#   Where-Object { $_ -notmatch '^\s*#' } |
+#   Select-String -Pattern '\{\{[A-Z0-9_]+\}\}'
+#
+# 적용 예시:
+# oc apply -f .\deploy\examples\axhub-mcp-dev-manual.template.yaml
+
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: axhub-mcp-config
+  namespace: "{{DEV_NAMESPACE}}"
+  labels:
+    app: axhub-mcp
+    app.kubernetes.io/name: axhub-mcp
+    app.kubernetes.io/instance: axhub-mcp-dev
+    app.kubernetes.io/component: mcp-server
+    app.kubernetes.io/part-of: ax-hub
+    ax-hub/mode: portal
+    ax-hub/tier: critical
+data:
+  # SPRING_PROFILES_ACTIVE=dev이므로 파일명도 application-dev.yml이어야 한다.
+  application-dev.yml: |
+    management:
+      server:
+        port: 9090
+      health:
+        redis:
+          enabled: false
+
+    mcp:
+      # 환경별 Redis key가 서로 겹치지 않도록 개발계 identity를 고정한다.
+      identity: axhub-mcp-dev
+
+      # Route가 경로를 변경하지 않고 그대로 전달하므로 Route path와 같아야 한다.
+      endpoint-path: "/mcp"
+
+      registry:
+        refresh-interval-seconds: 30
+        refresh-jitter-seconds: 5
+
+      discovery:
+        enabled: true
+
+      redis:
+        enabled: true
+        # Portal 조회 실패 시 사용하는 Redis fallback key다. Portal과 같은 key인지 확인한다.
+        portal-registry-key: "axhub:mcp:portal-registry"
+
+      portal:
+        enabled: true
+        registry-url: "{{DEV_PORTAL_REGISTRY_URL}}"
+        refresh-interval-seconds: 60
+
+      # Portal이 route와 Tool Server 주소를 제공하므로 정적 bundle은 두지 않는다.
+      bundles: []
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: axhub-mcp
+  namespace: "{{DEV_NAMESPACE}}"
+  labels:
+    app: axhub-mcp
+    app.kubernetes.io/name: axhub-mcp
+    app.kubernetes.io/instance: axhub-mcp-dev
+    app.kubernetes.io/component: mcp-server
+    app.kubernetes.io/part-of: ax-hub
+    ax-hub/mode: portal
+    ax-hub/tier: critical
+spec:
+  # 개발계 임시 테스트이므로 Pod 한 개로 구성한다.
+  replicas: 1
+  selector:
+    matchLabels:
+      app: axhub-mcp
+  template:
+    metadata:
+      labels:
+        app: axhub-mcp
+        app.kubernetes.io/name: axhub-mcp
+        app.kubernetes.io/instance: axhub-mcp-dev
+        app.kubernetes.io/component: mcp-server
+        app.kubernetes.io/part-of: ax-hub
+        ax-hub/mode: portal
+        ax-hub/tier: critical
+      annotations:
+        # Raw YAML은 Helm checksum을 자동 생성하지 못한다. ConfigMap 변경 시 이 값을 올리면 Pod이 재기동된다.
+        ax-hub/config-version: "{{CONFIG_VERSION}}"
+    spec:
+      terminationGracePeriodSeconds: 45
+      containers:
+        - name: mcp-server
+          image: "{{HARBOR_IMAGE_REPOSITORY}}:{{IMAGE_TAG}}"
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+            - name: management
+              containerPort: 9090
+              protocol: TCP
+          env:
+            - name: SPRING_PROFILES_ACTIVE
+              value: dev
+            # ConfigMap의 application-dev.yml을 JAR 내부 설정보다 우선 적용한다.
+            - name: SPRING_CONFIG_ADDITIONAL_LOCATION
+              value: file:/opt/app/config/
+            - name: REDIS_HOST
+              value: "{{REDIS_SERVICE_HOST}}"
+            - name: REDIS_PORT
+              value: "16379"
+            - name: MANAGEMENT_SERVER_PORT
+              value: "9090"
+          volumeMounts:
+            - name: config
+              mountPath: /opt/app/config
+              readOnly: true
+          readinessProbe:
+            httpGet:
+              path: /actuator/health/readiness
+              port: management
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /actuator/health/liveness
+              port: management
+            initialDelaySeconds: 20
+            periodSeconds: 20
+          resources:
+            requests:
+              cpu: 250m
+              memory: 512Mi
+            limits:
+              cpu: "1"
+              memory: 1Gi
+          securityContext:
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+            runAsNonRoot: true
+            seccompProfile:
+              type: RuntimeDefault
+      volumes:
+        - name: config
+          configMap:
+            name: axhub-mcp-config
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: axhub-mcp
+  namespace: "{{DEV_NAMESPACE}}"
+  labels:
+    app: axhub-mcp
+    app.kubernetes.io/name: axhub-mcp
+    app.kubernetes.io/instance: axhub-mcp-dev
+    app.kubernetes.io/component: mcp-server
+    app.kubernetes.io/part-of: ax-hub
+    ax-hub/mode: portal
+    ax-hub/tier: critical
+spec:
+  type: ClusterIP
+  selector:
+    app: axhub-mcp
+  ports:
+    - name: http
+      port: 8080
+      targetPort: http
+      protocol: TCP
+
+---
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  name: axhub-mcp
+  namespace: "{{DEV_NAMESPACE}}"
+  labels:
+    app: axhub-mcp
+    app.kubernetes.io/name: axhub-mcp
+    app.kubernetes.io/instance: axhub-mcp-dev
+    app.kubernetes.io/component: mcp-server
+    app.kubernetes.io/part-of: ax-hub
+    ax-hub/mode: portal
+    ax-hub/tier: critical
+  annotations:
+    haproxy.router.openshift.io/timeout: 300s
+    # 이 서버는 자체 인증을 하지 않으므로 반드시 실제 Agent Builder 고정 egress CIDR로 제한한다.
+    haproxy.router.openshift.io/ip_allowlist: "{{AGENT_BUILDER_EGRESS_CIDR}}"
+spec:
+  host: "{{DEV_MCP_HOST}}"
+  # /mcp/{routeKey} 요청도 prefix match로 이 Route에 들어온다. rewrite는 사용하지 않는다.
+  path: /mcp
+  to:
+    kind: Service
+    name: axhub-mcp
+    weight: 100
+  port:
+    targetPort: http
+  tls:
+    termination: edge
+    insecureEdgeTerminationPolicy: Redirect
+  wildcardPolicy: None
+
+---
+# MCP 서버는 자체 인증·인가를 하지 않으므로 NetworkPolicy를 제거하면 안 된다.
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: axhub-mcp-ingress
+  namespace: "{{DEV_NAMESPACE}}"
+  labels:
+    app: axhub-mcp
+    app.kubernetes.io/name: axhub-mcp
+    app.kubernetes.io/instance: axhub-mcp-dev
+    app.kubernetes.io/component: mcp-server
+    app.kubernetes.io/part-of: ax-hub
+    ax-hub/mode: portal
+    ax-hub/tier: critical
+spec:
+  podSelector:
+    matchLabels:
+      app: axhub-mcp
+  policyTypes:
+    - Ingress
+  ingress:
+    # OpenShift Route를 통과한 요청을 8080 포트로 허용한다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              policy-group.network.openshift.io/ingress: ""
+      ports:
+        - protocol: TCP
+          port: 8080
+
+    # 같은 클러스터 안에서 Agent Builder가 직접 호출하는 경우만 8080 포트로 허용한다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: "{{AGENT_BUILDER_NAMESPACE}}"
+      ports:
+        - protocol: TCP
+          port: 8080
+
+    # Actuator management 포트는 OpenShift 관제 namespace에서만 접근하도록 제한한다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: openshift-monitoring
+      ports:
+        - protocol: TCP
+          port: 9090

deploy/helm/mcp-server/Chart.yaml

@@ -4,6 +4,7 @@ description: AX HUB MCP Server - Agent Builder와 Tool Service 사이의 statele
 type: application
 
 # Chart 자체의 버전. 애플리케이션 버전과 따로 올린다.
-version: 0.1.0
+# 0.2.0에서 배포 모델이 두 가지(portal·bundles)가 되어 values 구조가 바뀌었다.
+version: 0.2.0
 # 기본 이미지 tag. 배포 시 values의 image.tag가 덮어쓴다.
 appVersion: "0.1.0"

deploy/helm/mcp-server/templates/_helpers.tpl

@@ -2,8 +2,27 @@
 설치 대상이 실제로 존재하는지 확인하고, 없으면 읽을 수 있는 메시지로 멈춘다.
 검사를 하지 않으면 오타가 "nil pointer" 같은 내부 오류로 나타나 원인을 찾기 어렵다.
 값을 반환하지 않으므로 각 template 파일의 첫 줄에서 한 번 부른다.
+
+required의 결과는 반드시 변수에 담는다. 그대로 두면 검사한 값이 렌더링 결과에 출력되어
+이름 앞에 host와 CIDR이 붙어 나온다. 검사는 통과 여부만 남기고 아무것도 출력하지 않아야 한다.
+
+mode에 따라 검사 대상이 다르다. portal 모드는 route 매핑을 Portal이 소유하므로(ADR-0013)
+deploymentKey가 없고 registryUrl이 필수다. bundles 모드는 그 반대다.
 */}}
 {{- define "mcp-server.validate" -}}
+{{- if not (has .Values.mode (list "portal" "bundles")) -}}
+{{- fail (printf "mode는 portal 또는 bundles여야 한다: %v" .Values.mode) -}}
+{{- end -}}
+{{- if eq .Values.mode "portal" -}}
+{{- $_ := required "mode=portal이면 portal.deployment.name을 지정해야 한다." .Values.portal.deployment.name -}}
+{{- $_ = required "mode=portal이면 portal.registryUrl에 Portal registry 주소를 지정해야 한다. 환경별 values-{env}.yaml이 소유한다." .Values.portal.registryUrl -}}
+{{- if not (index .Values.tiers .Values.portal.deployment.tier) -}}
+{{- fail (printf "values.yaml의 tiers에 '%s' 등급이 없다." .Values.portal.deployment.tier) -}}
+{{- end -}}
+{{- if .Values.deploymentKey -}}
+{{- fail "mode=portal에서는 deploymentKey를 쓰지 않는다. route는 /mcp/{routeKey} URI에서만 결정된다(ADR-0013)." -}}
+{{- end -}}
+{{- else -}}
 {{- $key := required "deploymentKey를 지정해야 한다. 예: --set deploymentKey=processing-critical" .Values.deploymentKey -}}
 {{- $deployment := index .Values.deployments $key -}}
 {{- if not $deployment -}}
@@ -12,20 +31,42 @@
 {{- if not (index .Values.tiers $deployment.tier) -}}
 {{- fail (printf "values.yaml의 tiers에 '%s' 등급이 없다. deployments의 tier와 tiers의 key가 어긋났다." $deployment.tier) -}}
 {{- end -}}
-{{- required "global.mcpHost에 환경별 공개 MCP host를 지정해야 한다." .Values.global.mcpHost -}}
-{{- required "route.sourceAllowlist에 Agent Builder의 고정 egress CIDR을 지정해야 한다." .Values.route.sourceAllowlist -}}
-{{- $publicPath := required (printf "deployments.%s.publicPath를 지정해야 한다." $key) $deployment.publicPath -}}
-{{- if not (regexMatch "^/mcp/[a-z0-9-]+$" $publicPath) -}}
-{{- fail (printf "deployments.%s.publicPath는 /mcp/<영문 소문자·숫자·하이픈> 형식이어야 한다: %s" $key $publicPath) -}}
+{{- end -}}
+{{- $_ := required "global.mcpHost에 환경별 공개 MCP host를 지정해야 한다." .Values.global.mcpHost -}}
+{{- $_ = required "route.sourceAllowlist에 Agent Builder의 고정 egress CIDR을 지정해야 한다." .Values.route.sourceAllowlist -}}
+{{- $publicPath := required "선택된 배포의 publicPath를 지정해야 한다." (include "mcp-server.selectedDeployment" . | fromYaml).publicPath -}}
+{{- if not (regexMatch "^/mcp(/[a-z0-9-]+)?$" $publicPath) -}}
+{{- fail (printf "publicPath는 /mcp 또는 /mcp/<영문 소문자·숫자·하이픈> 형식이어야 한다: %s" $publicPath) -}}
 {{- end -}}
 {{- end -}}
 
 {{/*
-리소스 이름. 하나의 namespace에 여러 MCP 배포가 들어가므로 배포마다 다른 이름을 쓴다.
+설치할 배포 하나를 dict로 돌려준다. mode가 그것을 어디서 읽는가의 차이만 여기서 흡수하고,
+나머지 template은 어느 모드인지 모른 채 같은 필드(name·tier·publicPath)를 쓴다.
+호출부는 `include ... | fromYaml`로 받는다. Helm helper는 문자열만 반환하기 때문이다.
+검사를 부르지 않는다. validate가 이 helper를 사용하므로 서로를 부르면 순환한다.
+*/}}
+{{- define "mcp-server.selectedDeployment" -}}
+{{- if eq .Values.mode "portal" -}}
+{{ toYaml .Values.portal.deployment }}
+{{- else -}}
+{{ toYaml (index .Values.deployments .Values.deploymentKey) }}
+{{- end -}}
+{{- end -}}
+
+{{/*
+리소스 이름. 하나의 namespace에 여러 MCP 배포가 들어갈 수 있으므로 배포마다 다른 이름을 쓴다.
 */}}
 {{- define "mcp-server.name" -}}
 {{- include "mcp-server.validate" . -}}
-{{- (index .Values.deployments .Values.deploymentKey).name -}}
+{{- (include "mcp-server.selectedDeployment" . | fromYaml).name -}}
+{{- end -}}
+
+{{/*
+선택된 배포의 가용성 등급 이름.
+*/}}
+{{- define "mcp-server.tier" -}}
+{{- (include "mcp-server.selectedDeployment" . | fromYaml).tier -}}
 {{- end -}}
 
 {{/*
@@ -38,12 +79,12 @@ Redis key namespace가 되는 식별자.
 {{- end -}}
 
 {{/*
-이 MCP가 보는 Tool Service의 host:port.
+이 MCP가 보는 Tool Service의 host:port. bundles 모드에서만 쓴다.
 MCP와 Tool Service는 같은 namespace이므로 서비스 이름만으로 FQDN이 완성된다.
 호출 대상 주소는 오직 이 설정에서만 온다(계약 v0.2 §1). 매니페스트 응답은 이 값을 바꿀 수 없다.
+portal 모드에서는 이 주소를 Portal registry가 소유하므로 이 helper를 부르지 않는다.
 */}}
 {{- define "mcp-server.toolServiceHost" -}}
-{{- include "mcp-server.validate" . -}}
 {{- $deployment := index .Values.deployments .Values.deploymentKey -}}
 {{- printf "%s.%s.svc.cluster.local:%v" $deployment.service .Release.Namespace .Values.toolService.port -}}
 {{- end -}}
@@ -54,7 +95,8 @@ app.kubernetes.io/name: {{ include "mcp-server.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 app.kubernetes.io/component: mcp-server
 app.kubernetes.io/part-of: ax-hub
-ax-hub/tier: {{ (index .Values.deployments .Values.deploymentKey).tier }}
+ax-hub/mode: {{ .Values.mode }}
+ax-hub/tier: {{ include "mcp-server.tier" . }}
 {{- end -}}
 
 {{- define "mcp-server.selectorLabels" -}}

deploy/helm/mcp-server/templates/configmap.yaml

@@ -1,9 +1,8 @@
 # 배포별로 달라지는 설정만 담는다.
 # 환경과 무관한 기본값(timeout, 상한, management 포트 등)은 jar 안의 application-ocp.yml이 소유하고,
-# 이 파일이 같은 이름으로 덮어써 identity와 bundle만 배포 시점에 결정한다.
+# 이 파일이 같은 이름으로 덮어써 identity와 Tool 원천만 배포 시점에 결정한다.
 {{- include "mcp-server.validate" . }}
-{{- $deployment := index .Values.deployments .Values.deploymentKey }}
-{{- $toolServiceHost := include "mcp-server.toolServiceHost" . }}
+{{- $deployment := include "mcp-server.selectedDeployment" . | fromYaml }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -19,19 +18,41 @@ data:
       endpoint-path: {{ $deployment.publicPath | quote }}
 
       registry:
-        refreshIntervalSeconds: {{ .Values.mcp.refreshIntervalSeconds }}
-        refreshJitterSeconds: {{ .Values.mcp.refreshJitterSeconds }}
+        refresh-interval-seconds: {{ .Values.mcp.refreshIntervalSeconds }}
+        refresh-jitter-seconds: {{ .Values.mcp.refreshJitterSeconds }}
 
       discovery:
         # 운영 profile은 Tool Service 매니페스트만 원천으로 쓴다.
         enabled: true
 
+      redis:
+        # Portal 조회가 실패한 cold start에서만 읽는 fallback key다.
+        # 포털이 쓰는 key와 반드시 같아야 한다.
+        portal-registry-key: {{ .Values.portal.registryRedisKey | quote }}
+{{- if eq .Values.mode "portal" }}
+
+      # route↔Tool Service 매핑의 원천은 Portal이다(ADR-0013).
+      # 배포 하나가 N개 route를 서비스하고, route key는 /mcp/{routeKey} URI에서만 결정된다.
+      # 매핑이 바뀌어도 이 ConfigMap을 고치지 않는다. 그것이 Portal을 원천으로 둔 이유다.
+      portal:
+        enabled: true
+        registry-url: {{ .Values.portal.registryUrl | quote }}
+        refresh-interval-seconds: {{ .Values.portal.refreshIntervalSeconds }}
+
+      # Portal이 주소를 소유하므로 정적 bundle을 선언하지 않는다.
+      bundles: []
+{{- else }}
+
+      portal:
+        enabled: false
+
       # MCP 배포 하나는 Tool Service 하나만 본다(ADR-0007).
       # 이 목록은 항상 한 항목이며, 늘리려면 배포를 하나 더 만든다.
       # 주소는 여기서 조립한다. values에 URL을 적기 시작하면 오타가 라우팅 사고가 된다.
       bundles:
         - id: {{ .Values.deploymentKey | quote }}
           namePrefix: {{ $deployment.namePrefix | quote }}
-          manifestUrl: http://{{ $toolServiceHost }}{{ .Values.toolService.manifestPath }}
-          baseEndpoint: http://{{ $toolServiceHost }}{{ .Values.toolService.basePath }}
+          manifestUrl: http://{{ include "mcp-server.toolServiceHost" . }}{{ .Values.toolService.manifestPath }}
+          baseEndpoint: http://{{ include "mcp-server.toolServiceHost" . }}{{ .Values.toolService.basePath }}
           enabled: true
+{{- end }}

deploy/helm/mcp-server/templates/deployment.yaml

@@ -1,5 +1,5 @@
 {{- include "mcp-server.validate" . }}
-{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+{{- $tier := index .Values.tiers (include "mcp-server.tier" .) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -17,12 +17,17 @@ spec:
       labels:
         {{- include "mcp-server.labels" . | nindent 8 }}
       annotations:
-        # ConfigMap이 바뀌면 Pod을 다시 굴린다. 이게 없으면 bundle 설정을 고쳐도
+        # ConfigMap이 바뀌면 Pod을 다시 굴린다. 이게 없으면 설정을 고쳐도
         # 기존 Pod이 옛 설정으로 계속 돌아 배포한 줄 알고 넘어가게 된다.
         checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
     spec:
       # 진행 중인 tools/call이 잘려 부작용만 남는 것을 줄인다.
       terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
+      {{- with .Values.image.pullSecrets }}
+      # 사내 registry가 인증을 요구할 때만 지정한다. 비워 두면 렌더링되지 않는다.
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
       {{- if $tier.spreadAcrossNodes }}
       affinity:
         podAntiAffinity:
@@ -57,10 +62,20 @@ spec:
               value: {{ .Values.redis.port | quote }}
             - name: MANAGEMENT_SERVER_PORT
               value: {{ .Values.ports.management | quote }}
+            {{- if .Values.toolService.apiKeySecret.name }}
+            # Tool Service 호출용 API key. 값은 Secret이 소유하고 Chart는 이름만 안다.
+            - name: TOOL_SERVER_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.toolService.apiKeySecret.name }}
+                  key: {{ .Values.toolService.apiKeySecret.key }}
+            {{- end }}
           volumeMounts:
             - name: config
               mountPath: /opt/app/config
               readOnly: true
+          # readiness는 첫 Tool 조회가 끝나고 usable snapshot이 있을 때만 UP이다.
+          # 원천이 늦게 뜨는 환경에서 Pod을 죽이지 않도록 liveness에는 그 조건이 들어가지 않는다.
           readinessProbe:
             httpGet:
               path: /actuator/health/readiness

deploy/helm/mcp-server/templates/poddisruptionbudget.yaml

@@ -1,10 +1,10 @@
 {{- include "mcp-server.validate" . }}
-{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+{{- $tier := index .Values.tiers (include "mcp-server.tier" .) }}
 {{- if $tier.podDisruptionBudget }}
 # 중요 등급 배포가 자발적 중단(노드 drain, 클러스터 업그레이드) 중에도 최소 1개를 남기게 한다.
 #
 # replica를 2 이상으로 올려도 PDB가 없으면 노드 drain이 두 Pod을 한꺼번에 내릴 수 있다.
-# 등급을 나눈 목적이 "중요 Tool은 다운이 없어야 한다"이므로 이 둘은 함께 가야 한다(ADR-0007).
+# 등급을 나눈 목적이 "중요 Tool은 다운이 없어야 한다"이므로 이 둘은 함께 가야 한다.
 #
 # NetworkPolicy와 달리 조건이 붙는다. 저쪽은 인가의 전제라 끌 수 없지만 이것은 가용성 정책이고,
 # replica 1인 dev에서는 PDB가 오히려 노드 drain을 영구히 막는다.

deploy/helm/mcp-server/templates/route.yaml

@@ -1,5 +1,7 @@
 {{- include "mcp-server.validate" . }}
-{{- $deployment := index .Values.deployments .Values.deploymentKey }}
+{{- $deployment := include "mcp-server.selectedDeployment" . | fromYaml }}
+# OpenShift Route의 path는 prefix 매칭이다. portal 모드에서 path가 "/mcp"이면
+# /mcp/{routeKey} 전체가 이 Route 하나로 들어오고, route 구분은 컨테이너가 한다(ADR-0013).
 apiVersion: route.openshift.io/v1
 kind: Route
 metadata:

deploy/helm/mcp-server/values-dev.yaml

@@ -1,10 +1,10 @@
 # dev 환경. 배포마다 Pod 1개로 구성한다.
 #
 # dev에서는 중요 등급도 replica 1이다. rolling update 중 수십 초 공백이 생기지만
-# dev는 가용성 목표 대상이 아니다. 중요 등급의 replica 하한과 PDB는 prod에서만 강제하며
+# dev는 가용성 목표 대상이 아니다. 중요 등급의 replica 하한과 PDB는 test·prod에서만 강제하며
 # HelmDeploymentContractTest가 그 사실을 고정한다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.
 
 global:
@@ -12,6 +12,11 @@ global:
   agentBuilderNamespace: ax-hub-agentbuilder-dev
   mcpHost: mcp-dev.apps.example.internal
 
+portal:
+  # TODO: 실제 dev Portal registry 주소로 확정한다. deploy/docker-compose.yml의 mock과 같은 응답을 준다.
+  registryUrl: https://axhub.devjun.net/api/portal/registry
+  refreshIntervalSeconds: 60
+
 route:
   # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
   sourceAllowlist: 192.0.2.0/24

deploy/helm/mcp-server/values-prod.yaml

@@ -1,16 +1,14 @@
 # prod 환경.
 #
-# replica는 배포 하나가 받는 트래픽 기준으로 잡는다. 업무 × 등급으로 나뉘어 있으므로
-# 배포 하나가 받는 몫은 전체를 하나로 묶었을 때의 일부다. 등급별 기준은 아래가 정본이다.
-#
-# 조회 부하 = replica 수 / 주기. 1:1이라 bundle 수는 항상 1이다(ADR-0007).
-#   중요 등급 3 replica / 30초 = 배포당 초당 0.1회. Tool Service 한 대가 받는 몫이 그대로 이 값이다.
+# replica는 이 배포가 받는 트래픽 기준으로 잡는다.
+# 매니페스트 조회 부하 = replica 수 × (route에 붙은 Tool Service 수) / 주기다.
+# portal 모드는 한 배포가 전 route를 서비스하므로 route가 늘면 이 값이 함께 는다(ADR-0013 전제 3).
 #
 # 중요 등급은 replica 2 이상과 PodDisruptionBudget이 필수다.
 # 1이면 rolling update 중 반드시 공백이 생기고, PDB가 없으면 노드 drain이 마지막 Pod을 내린다.
 # HelmDeploymentContractTest가 replica·PDB·노드 분산 values를 정적으로 검사한다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.
 
 global:
@@ -18,6 +16,11 @@ global:
   agentBuilderNamespace: ax-hub-agentbuilder-prod
   mcpHost: mcp.apps.example.internal
 
+portal:
+  # TODO: 실제 운영 Portal registry 주소로 교체한다.
+  registryUrl: https://axhub.apps.example.internal/api/portal/registry
+  refreshIntervalSeconds: 300
+
 route:
   # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
   sourceAllowlist: 192.0.2.0/24

deploy/helm/mcp-server/values-test.yaml

@@ -1,9 +1,9 @@
 # test 환경. 운영계에 앞서 중요 등급의 가용성 설정을 검증하는 단계다.
 #
-# 중요 등급을 prod와 같은 방식(replica 2 + PDB)으로 먼저 검증하는 자리다.
+# 중요 등급을 prod와 같은 방식(replica 2 + PDB + 노드 분산)으로 먼저 검증하는 자리다.
 # 여기서 확인하지 않으면 prod 배포 때 처음 겪게 된다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.
 
 global:
@@ -11,6 +11,11 @@ global:
   agentBuilderNamespace: ax-hub-agentbuilder-test
   mcpHost: mcp-test.apps.example.internal
 
+portal:
+  # TODO: 실제 test Portal registry 주소로 교체한다.
+  registryUrl: https://axhub-test.apps.example.internal/api/portal/registry
+  refreshIntervalSeconds: 300
+
 route:
   # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
   sourceAllowlist: 192.0.2.0/24

deploy/helm/mcp-server/values.yaml

@@ -1,36 +1,48 @@
 # 환경 공통 기본값과 배포 토폴로지. 환경별 차이는 values-{env}.yaml이 덮어쓴다.
 #
 # 이 Chart의 설계 원칙:
-#   1. MCP 배포 하나는 Tool Service 하나만 본다(ADR-0007).
-#      bundle 목록은 항상 한 항목이며 template이 만든다.
-#   2. 배포 대상 전체를 아래 deployments 한 곳에 적는다.
-#      설치할 때 --set deploymentKey=<key>로 하나를 고른다.
-#      배포가 10개든 20개든 파일 수가 늘지 않고, 전체 매핑을 한 화면에서 검토할 수 있다.
-#   3. 환경 축(namespace·이미지·등급별 replica)과 배포 축(어느 Tool Service를 보는가)을 섞지 않는다.
+#   1. 배포 모델이 두 가지다. mode가 그 축을 고른다.
+#      portal  — route↔Tool Service 매핑의 원천이 Portal이다(ADR-0013). 배포 하나가 N route를
+#                서비스하고 route key는 /mcp/{routeKey} URI에서만 온다. 현재 애플리케이션 코드의 경로다.
+#      bundles — 배포 하나가 Tool Service 하나만 보고 매핑을 배포 시점에 못박는다(ADR-0007).
+#                ADR-0013이 대체했지만 코드 경로가 남아 있어 1:1 검증·격리 배포에 쓸 수 있다.
+#   2. 환경 축(namespace·이미지·등급별 replica)과 배포 축(무엇을 보는가)을 섞지 않는다.
 #      values-{env}.yaml에는 deployments가 없고, deployments에는 환경 정보가 없다.
-#   4. identity는 "{배포 이름}-{global.env}"로 조립한다.
+#   3. identity는 "{배포 이름}-{global.env}"로 조립한다.
 #      Redis key namespace이므로 환경끼리 겹치면 서로 Tool snapshot을 덮어쓴다.
 #      사람이 손으로 적지 않게 해 실수를 구조적으로 막는다.
-#   5. 외부에서는 환경별 한 host 아래 publicPath로 구분한다. Route는 Service만 선택하고
-#      컨테이너가 같은 path를 직접 처리하므로 Registry의 1:1 경계는 바뀌지 않는다(ADR-0009).
+#   4. 공개 path는 Route와 컨테이너가 동일하게 사용하고 rewrite하지 않는다(ADR-0009).
 
-# 설치할 배포를 고르는 key. 반드시 --set으로 지정한다.
+# 배포 모델. portal | bundles
+# 기본값을 portal로 둔 이유는 현재 애플리케이션이 실제로 도는 경로이기 때문이다.
+mode: portal
+
+# ---------------------------------------------------------------------------
+# mode=portal 축
+# ---------------------------------------------------------------------------
+portal:
+  # 이 환경에 설치되는 단일 MCP 배포. route가 늘어도 배포는 늘지 않는다.
+  deployment:
+    name: axhub-mcp
+    tier: critical
+    # route key는 이 path 아래 URI segment에서 온다. 여기에 routeKey를 적지 않는다.
+    publicPath: /mcp
+  # Portal registry 조회 주소. 환경마다 다르므로 values-{env}.yaml이 소유한다.
+  # 기본값을 두지 않는 이유는, 빠뜨린 설치가 조용히 성공하는 것보다 렌더링 실패가 낫기 때문이다.
+  registryUrl: ""
+  refreshIntervalSeconds: 300
+  # Portal 조회가 실패한 cold start에서만 읽는 Redis fallback key.
+  # 포털이 registry를 써 넣는 key와 반드시 같아야 한다.
+  registryRedisKey: axhub:mcp:portal-registry
+
+# ---------------------------------------------------------------------------
+# mode=bundles 축
+# ---------------------------------------------------------------------------
+# 설치할 배포를 고르는 key. mode=bundles일 때 반드시 --set으로 지정한다.
 # 기본값을 두지 않는 이유는, 지정을 빠뜨렸을 때 엉뚱한 배포가 조용히 설치되는 것보다
 # 렌더링 실패가 낫기 때문이다.
 deploymentKey: ""
 
-global:
-  # 배포 환경. identity 접미사와 NetworkPolicy 판단에 쓰인다.
-  env: dev
-  # Agent Builder가 있는 namespace. Route를 우회한 Pod 직접 호출을 이 namespace로 제한한다.
-  # MCP와 Tool Service는 같은 namespace이므로 여기 적지 않는다.
-  # TODO: 실제 namespace 확정 시 교체한다.
-  agentBuilderNamespace: ax-hub-agentbuilder-dev
-  # Actuator management 포트에 접근할 관제 namespace.
-  monitoringNamespace: openshift-monitoring
-  # 환경별 공개 MCP host. 실제 OpenShift apps domain으로 교체한다.
-  mcpHost: mcp-dev.apps.example.internal
-
 # 배포 대상 전체. map의 key가 곧 bundle id가 된다.
 #
 #   name        Deployment/Service/ConfigMap/NetworkPolicy 이름. 같은 namespace에서 유일해야 한다
@@ -39,10 +51,6 @@ global:
 #   tier        가용성 등급. 아래 tiers의 key여야 한다
 #   publicPath  Agent Builder가 등록할 외부 MCP path. 전체 topology에서 유일해야 한다
 #
-# 같은 업무의 두 등급이 같은 namePrefix를 공유하는 것은 의도된 구성이다(ADR-0007).
-# 등급을 이름에 넣으면 Tool 재분류가 Tool name 변경이 되어 Agent Builder 재등록을 부른다.
-# 그 안에서 Tool 이름이 겹치지 않게 하는 것은 Tool Service 책임이다.
-#
 # TODO: Tool 목록이 확정되면 실제 Tool Service 이름으로 교체하고, 없는 배포는 삭제한다.
 deployments:
   processing-critical:
@@ -94,6 +102,20 @@ deployments:
     tier: standard
     publicPath: /mcp/hr-standard
 
+# ---------------------------------------------------------------------------
+# 모드 공통
+# ---------------------------------------------------------------------------
+global:
+  # 배포 환경. identity 접미사와 NetworkPolicy 판단에 쓰인다.
+  env: dev
+  # Agent Builder가 있는 namespace. Route를 우회한 Pod 직접 호출을 이 namespace로 제한한다.
+  # TODO: 실제 namespace 확정 시 교체한다.
+  agentBuilderNamespace: ax-hub-agentbuilder-dev
+  # Actuator management 포트에 접근할 관제 namespace.
+  monitoringNamespace: openshift-monitoring
+  # 환경별 공개 MCP host. 실제 OpenShift apps domain으로 교체한다.
+  mcpHost: mcp-dev.apps.example.internal
+
 # OpenShift Router와 MCP 컨테이너가 같은 publicPath를 사용한다. rewrite하지 않는다.
 route:
   # Agent Builder 최대 대기 시간과 맞춘 공개 HTTP 연결 timeout이다.
@@ -103,9 +125,9 @@ route:
 
 # 등급별 가용성 기준. 환경별 values가 덮어쓴다.
 #
-# 배포를 등급으로 나누는 목적이 여기에 있다. 나뉘어 있어야 중요 등급에만 비용을 쓸 수 있다.
 # 다만 나누는 것만으로 가용성이 생기지는 않는다. 같은 노드 배치, namespace 쿼터,
-# 공통 Redis·클러스터 장애는 분할로 막히지 않는다(ADR-0007).
+# 공통 Redis·클러스터 장애는 분할로 막히지 않는다.
+# portal 모드에서는 배포가 하나이므로 등급별 물리 분리가 성립하지 않는다(ADR-0013 전제 2).
 tiers:
   critical:
     replicas: 2
@@ -120,21 +142,28 @@ tiers:
 
 image:
   # TODO: 사내 컨테이너 registry 경로 확정 시 교체한다.
+  # CI가 --set image.tag=<commit sha>로 덮어쓴다.
   repository: image-registry.openshift-image-registry.svc:5000/ax-hub/ax-hub-mcp-server
   tag: "0.1.0"
   pullPolicy: IfNotPresent
+  # 사내 registry가 인증을 요구할 때만 채운다. 예: [{name: harbor-pull}]
+  pullSecrets: []
 
 mcp:
   # Tool Service 매니페스트 조회 주기(초).
-  # 1:1이라 bundle 수가 항상 1이므로 조회 부하는 (replica 수 / 주기)다.
   refreshIntervalSeconds: 30
   refreshJitterSeconds: 5
 
 toolService:
-  # MCP와 같은 namespace에 있으므로 서비스 이름 + 아래 값으로 주소가 완성된다.
+  # bundles 모드에서만 쓴다. MCP와 Tool Service가 같은 namespace라는 전제다.
   port: 8080
   manifestPath: /tool-manifest
   basePath: /mcp
+  # Tool Service 호출용 API key를 담은 Secret. name이 비어 있으면 환경변수를 주입하지 않고
+  # 애플리케이션 기본값을 쓴다. 운영에서는 반드시 채운다.
+  apiKeySecret:
+    name: ""
+    key: tool-server-api-key
 
 redis:
   host: redis

docs/architecture.md

@@ -0,0 +1,238 @@
+# AX HUB MCP Server 설계 설명
+
+## 책임 경계
+
+```text
+Agent Builder (판단, Tool 선택)
+  -> JSON-RPC 2.0 / Streamable HTTP
+OpenShift Route (공유 host, 배포별 public path로 Service 선택, rewrite 없음)
+  -> 배포별 MCP Service
+MCP HTTP Transport (transport/http: filter, controller, correlation, 오류 변환)
+  -> JSON-RPC Parser (envelope/method/params 정규화)
+  -> Handler Registry (method dispatch)
+  -> Execute Layer (metadata, validation, routing, flow control)
+  -> ToolClient (REST, timeout, header propagation)
+Tool Service (Business Rule, Legacy/MCI/EAI 연계)
+```
+
+MCP는 Agent Builder가 `tools/call`에 명시한 단일 Tool을 실행한다. Tool 추천, 사용자 의도 해석, 업무 데이터 재가공, LLM reasoning은 이 경계 밖이다.
+
+**인증과 인가도 이 경계 밖이다**([ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)). 외부 호출자 제한은 Route IP allowlist가, Pod 직접 접근 제한은 NetworkPolicy가, 사용자 인증과 Tool 권한은 Agent Builder가, 사원 식별자 복호화와 업무 권한은 Tool Service가 담당한다. MCP는 요청 형식과 `inputSchema`만 검증한다.
+
+## 전체 실행 흐름
+
+1. Agent Builder가 배포별 공개 URL `https://{host}{publicPath}`을 호출한다. OpenShift Route는 host와 path로 MCP Service만 선택하고 원래 path를 컨테이너에 전달한다([ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)). 요청 body·header·Tool 이름은 이 선택에 관여하지 않는다.
+2. 컨테이너의 `mcp.endpoint-path` 전용 `McpExchangeFilter`가 header를 검증/추출하고 요청 전체 deadline을 포함한 `McpRequestContext`를 만든다. 호출자 헤더 다섯 개(`guid`, `x-request-id`, `mcp-session-id`, `employee-no`, `virtual-employee-no`)는 모두 선택값이며, 응답과 downstream Tool 호출에 그대로 전파한다. `guid`는 요청 하나의 end-to-end 상관 값, `x-request-id`는 개별 HTTP 요청 식별자다.
+3. 같은 filter가 route key를 확정한다. `mcp.endpoint-path`가 `/mcp/core`처럼 route를 포함한 고정 배포면 그 설정값이 route이고, `/mcp`인 동적 배포면 `/mcp/{routeKey}`의 path segment가 route다. Portal 모드에서 route가 없거나(`route key is required`), `[A-Za-z0-9._-]{1,64}`를 벗어나거나(`route key is invalid`), registry snapshot에 없는 route(`route key is not registered`)는 `McpRouteKeyValidator`가 controller 진입 전에 JSON-RPC invalid request로 거부한다. 이 검사는 in-memory snapshot만 보고 Portal이나 Redis를 새로 호출하지 않는다. `mcp.portal.route-key` 설정은 선언되어 있으나 읽지 않는다. 자세한 계약은 [v0.3](contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md)에 있다.
+4. filter는 크기가 제한된 repeatable request body에서 `method`만 관찰용으로 읽고 `mcp_http_request_received` 로그를 남긴다. body, header 값, credential은 로그에 저장하지 않는다.
+5. `McpProtocolVersionValidator`가 `initialize`를 제외한 요청의 `MCP-Protocol-Version`을 supported versions와 대조한다. 누락·불일치는 Controller 진입 전 HTTP 400으로 종료한다.
+6. `JsonRpcRequestParser`가 envelope를 정규화하고 JSON-RPC 2.0, method, id, params shape를 최종 검증한다.
+   JSON-RPC version, 표준 오류 번호와 MCP method 이름은 MCP Java SDK 2.0 상수를 참조한다.
+7. `McpMethodHandlerRegistry`가 method를 명시적 handler에 연결한다.
+8. `tools/list`는 `ToolRegistryService`의 in-memory snapshot에서 실행 metadata를 얻는다. 요청 경로는 Redis를 호출하지 않으므로 Redis 장애·지연이 응답에 영향을 주지 않으며, snapshot이 비어 있는 기동 직후에만 Tool catalog provider를 한 번 조회한다. 이후 `ToolsListHandler`가 MCP SDK의 `Tool`과 `ListToolsResult`로 변환한다. local 기본 구성은 Tool Service 매니페스트를 먼저 조회하고, 최초 실패 시 bundle별 local manifest sample을 cold-start fallback으로 사용한다. 운영은 이 배포가 보는 Tool Service 매니페스트의 사용 가능한 성공본만 원천으로 사용한다.
+9. `tools/call`은 `ToolsCallHandler`가 표준 MCP의 `params.name`과 object인 `params.arguments`를 검증하고 추출한다.
+10. `ToolExecutionService`가 표준 Tool name으로 metadata를 확정하고 argument schema를 검증한다. `ToolRoutingService`는 snapshot에 저장된 정확한 Tool endpoint와 metadata timeout으로 HTTP 요청을 만든다. Agent Builder가 보낸 `arguments` 객체는 JSON raw body로 전달하며 MCP가 Tool을 대체 선택하지 않는다.
+11. `arguments`의 어떤 field도 outbound URL 선택에 사용하지 않는다. Portal registry는 Tool Server의 `serviceDomain`과 `manifestPath`만 제공하고, Tool별 실행 endpoint는 Tool Server manifest의 top-level `endpoint` 또는 `_meta.endpoint`에서 가져온다. manifest endpoint가 절대 HTTP(S) URL이면 Tool Server가 제공한 실행 주소 원천으로 허용하고, 상대 경로이면 Portal registry의 `serviceDomain` 뒤에 붙인다.
+12. `HttpToolClient`가 JDK 공유 HTTP client의 connection pool을 사용해 correlation 헤더와 함께 POST를 실행한다. arguments는 JSON body로 전달하며 Tool read timeout은 metadata timeout과 요청 전체 deadline의 남은 시간 이하로 제한한다. Authorization 전달은 설정으로 통제한다.
+13. Tool 응답은 요청 payload와 분리해 `response.data`만 사용한다. plain text는 그대로, JSON object/array는 compact JSON string으로 MCP SDK `CallToolResult`/`TextContent`의 `result.content[0].text`에 넣고 outer JSON serializer가 escaping을 처리한다. 호출 소요 시간(ms)은 `result.content[0]._meta.searchTime`으로 반환하고, 정상 결과에도 `isError: false`를 명시한다. Tool 실행·timeout·권한 오류는 JSON-RPC error가 아니라 `isError: true` result로 변환한다. JSON-RPC envelope/params/method 및 서버 구성 오류는 최상위 JSON-RPC `error`로 반환한다.
+14. local과 운영 모두 같은 `name` lookup, endpoint/timeout, inputSchema validation 경로를 사용한다.
+15. Agent Builder가 `Accept: application/json, text/event-stream`을 보내도 서버는 단일 `application/json` JSON-RPC response를 반환한다. filter는 status와 소요 시간을 `mcp_http_response_completed` 로그로 남기며 응답 body는 저장하지 않는다.
+16. 모든 예외는 `JsonRpcException`/`McpExceptionHandler`에서 표준 error로 변환하고, filter가 ThreadLocal을 반드시 정리한다.
+
+## 주요 클래스별 책임
+
+| 클래스 | 패키지 | 책임 |
+|---|---|---|
+| `McpServerApplication` | (루트) | Spring Boot 시작점. component scan·configuration properties·scheduler를 활성화해 나머지를 조립하며 요청을 직접 처리하지 않음 |
+| `McpProperties` | `config` | `mcp.*` 설정을 타입 안전한 불변 record로 묶고 기동 시 검증. 중첩 record가 서버·연동·cache·trace 정책을 분리 |
+| `HttpClientConfig` | `config` | manifest 조회와 Tool 실행이 쓰는 RestClient·JDK HttpClient Bean과 연결·timeout 기본값 구성 |
+| `McpController` | `transport/http` | `mcp.endpoint-path`의 단일 공개 endpoint, parser/handler 연결, notification 202와 initialize UUID header 선택 |
+| `McpRequestContextFactory` | `transport/http` | 호출자 헤더 5종 추출. correlation 값 형식 검증, 사원 식별자는 해석하지 않고 주입 위험 문자만 차단 |
+| `McpRequestContextHolder` | `context` | 요청 수명 ThreadLocal 저장; 세션 저장소가 아님 |
+| `JsonRpcRequestParser` | `jsonrpc` | JSON-RPC envelope shape 검증과 내부 request 정규화 |
+| `McpMethodHandlerRegistry` | `method` | `Handler` 전략과 method dispatch를 한 경계에서 관리 |
+| `ToolRegistryService` | `registry` | 요청 경로(memory 전용)와 배경 갱신 경로(provider 조회 후 memory→Redis 저장) 분리, single-flight refresh, 공유 cache warm start |
+| `InitializeHandler` | `method` | `initialize`에 서버 정보·capability·protocol version 응답. 세션 header 발급은 transport 책임 |
+| `InitializedNotificationHandler` | `method` | `notifications/initialized` 수신. 상태를 만들지 않고 controller가 202로 마무리 |
+| `ToolsListHandler` | `method` | 실행 metadata를 MCP 공개 Tool로 변환하고 `_meta` 제거. 공개 필드 목록은 [계약 v0.3](contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md#toolslist)이 정본 |
+| `ToolsCallHandler` | `method` | `tools/call`의 `params.name`·`params.arguments` 검증 후 실행 계층에 전달하고 `CallToolResult`로 변환. 요청 오류는 JSON-RPC error, Tool 실패는 `isError: true` |
+| `LocalFileToolRegistryClient` | `registry` | 매니페스트 조회를 끈 local profile에서 legacy JSON/manifest fixture를 읽어 테스트 Tool 목록을 제공 |
+| `ToolBundleDiscovery` | `registry` | 구현상 N개 Tool Service 매니페스트를 병렬 조회·검증하고 bundle별 last-good 상태를 유지. 최초 원격 조회 실패 시에만 설정된 local manifest fallback을 사용하며, 운영 배포는 1개 Bundle만 사용 |
+| `ToolBundleRegistryClient` | `registry` | 구현상 모든 bundle의 사용 가능한 성공본을 중복·총량 검증 후 하나의 snapshot으로 병합. 운영 배포에서는 단일 Bundle 결과를 채택 |
+| `PortalToolRegistryClient` | `registry` | Portal registry 응답을 Tool Server endpoint 원천으로 변환. route별 Tool Server 목록을 확보한 뒤 각 manifest를 조회하며, 한 route의 실패가 다른 route의 snapshot을 지우지 않는다 |
+| `RedisToolRegistryCache` | `registry` | best-effort Redis snapshot, 실제 read/write 실패를 cache miss로 격리 |
+| `RedisPortalRegistryCache` | `registry` | Portal registry JSON의 선택적 Redis fallback. 배경 preload/refresh에서만 사용하고 memory가 비어 있는 cold start에서만 읽는다 |
+| `ToolRegistryRefreshScheduler` | `registry` | 기동 preload와 주기 refresh; 실패 시 애플리케이션 생존 |
+| `ToolArgumentValidator` | `execute` | 기존 required/type 오류 계약을 보존하고 MCP SDK JSON Schema 2020-12 검증 적용 |
+| `ToolExecutionService` | `execute` | 이름 기반 metadata 해석, argument validation, 단일 Tool 실행, HTTP 경계 로그와 오류 mapping |
+| `ToolRoutingService` | `execute` | 단일 POST endpoint와 timeout 확정, 기본 URI 검증 |
+| `ToolClient` | `toolclient` | Tool 호출 port와 해당 경계의 `ToolRequest`/`ToolResponse`/실패 타입 소유 |
+| `HttpToolClient` | `toolclient` | HTTP 호출, headers, timeout, JSON/text 응답 처리 |
+| `ToolBundleStatusEndpoint` | `observability` | management port의 Actuator `toolBundles` 상태 조회 |
+| `ToolCatalogHealthIndicator` | `observability` | readiness group 판정. 첫 조회 시도가 끝나고 usable in-memory snapshot이 있을 때만 UP |
+| `McpExchangeFilter` | `transport/http` | 설정된 MCP endpoint 전처리, request 크기 제한, correlation, HTTP 요청·응답 경계 로그 |
+| `McpProtocolVersionValidator` | `transport/http` | `initialize` 이후 HTTP `MCP-Protocol-Version`의 지원 여부 검증; 서버 상태를 저장하지 않음 |
+| `McpRouteKeyValidator` | `transport/http` | route key가 현재 registry에 등록됐는지 확인하는 transport 전용 port. 구현은 `ToolRegistryService`이며 memory snapshot만 조회한다 |
+| `TraceLogger` | `observability` | context의 guid/requestId를 직접 포함하는 최소 key=value 경계 로그. 사원 식별자는 기록하지 않음 |
+| `McpExceptionHandler` | `transport/http` | JSON parse, JSON-RPC, 예상 밖 오류의 표준 response 변환 |
+
+Spring Boot 3.5가 관리하는 Jackson 2 databind 모델과 annotation API는 `com.fasterxml.jackson.*` namespace를 사용한다. Registry 응답의 unknown field 무시는 회귀 테스트로 검증한다.
+
+MCP Java SDK는 protocol 상수, 표준 result 모델과 JSON Schema validator에만 사용한다. SDK/Spring AI MCP
+Starter와 transport는 활성화하지 않으며 기존 `/mcp`, 보안, correlation, Registry, Tool 실행 경계를 유지한다.
+상세 도입 범위와 업그레이드 검증 기준은 [MCP Java SDK 선택적 도입 설계](mcp-java-sdk-adoption.md)를 따른다.
+
+## 소스 구성 원칙
+
+- Spring component, 외부 adapter, 교체 가능한 port 구현은 책임별 독립 파일로 유지한다.
+- 특정 서비스나 port에서만 의미가 있는 immutable record, enum, 예외는 소유 타입 안에 둔다.
+- `ToolClient`가 request/response/failure 타입을, `ToolExecutionService`가 실행 result를 소유한다.
+- `McpMethodHandlerRegistry`는 handler 계약을, `ToolRegistryClient`는 원천 목록 조회 port를 소유한다.
+- bean이나 동작을 제공하지 않는 빈 configuration class는 두지 않는다. Spring Boot auto-configuration과 application class의 scheduling 설정을 그대로 사용한다.
+- 파일 수를 줄이기 위해 서로 다른 서비스 책임을 합치지는 않는다. transport, Registry, execution, Tool client, observability 경계는 계속 분리한다.
+
+### 패키지 경계
+
+| 패키지 | 책임 |
+|---|---|
+| `transport/http` | HTTP로 들어오고 나가는 경계 전부. filter, controller, 본문 wrapper, protocol version 검증, context 생성, 오류 응답 변환 |
+| `context` | 요청 수명 동안 공유하는 값과 ThreadLocal holder. 전송 방식을 모른다 |
+| `jsonrpc` | JSON-RPC envelope 모델과 파싱·오류 코드 |
+| `method` | MCP method별 handler와 dispatch |
+| `execute` / `toolclient` | 단일 Tool 실행(응용 서비스)과 outbound port·adapter |
+| `registry` | Tool 목록의 원천 조회, 병합, 캐시 |
+| `observability` | 경계 로그, health indicator, Actuator 상태 endpoint |
+
+**`jakarta.servlet` 의존은 `transport` 패키지 안에서만 허용한다.** MCP는 stdio 등 다른 transport를 가질 수 있는
+프로토콜이므로, 서블릿 타입이 이 경계 밖으로 새면 전송 방식이 응용 계층에 굳어진다.
+이 규칙은 `PackageBoundaryContractTest`가 강제한다.
+
+## Stateless 보장
+
+- `HttpSession`/Spring Session 의존성이나 API를 사용하지 않는다.
+- `mcp-session-id`는 요청 context와 downstream correlation header에만 사용한다.
+- initialize 응답의 `Mcp-Session-Id`는 Agent Builder가 이후 요청에 전달하는 opaque correlation 값이다. 서버는 이를 발급했는지·notification을 받았는지·session readiness를 저장하거나 검증하지 않는다.
+- Tool metadata의 in-memory cache는 업무/사용자 세션 상태가 아닌 재구성 가능한 read-only snapshot이다.
+- replica가 달라져도 동일 요청 계약을 수행할 수 있다.
+- HTTP와 Tool 호출 경계 로그는 requestId/guid로 연결하지만 업무·세션 상태를 저장하지 않는다.
+
+## HTTP 경계 로그
+
+- 모든 MCP method(`initialize`, `notifications/initialized`, `tools/list`, `tools/call`)는 설정된 공개 path의 POST body에 있는 JSON-RPC `method`로 식별된다. Filter는 이 값과 HTTP status, 소요 시간만 요청·응답 경계 로그에 남긴다.
+- `guid`가 있으면 end-to-end 흐름 전체에 그대로 사용하고, 없으면 UUID를 생성한다. `x-request-id`도 있으면 그대로 사용하고 없으면 생성해 response header와 downstream Tool header에 전파한다.
+- MDC는 사용하지 않는다. `TraceLogger`가 `McpRequestContextHolder`에서 guid와 requestId를 읽어 각 메시지에 직접 포함한다.
+- Authorization/Cookie/API key, session 식별자, 요청·응답 body는 logger에 남기지 않는다.
+- **`employee-no`와 `virtual-employee-no`는 암호문이라도 로그에 남기지 않는다.** 개인 식별자이며, 암호화는 저장·전송 보호이지 로그 기록 허가가 아니다.
+- 수신 request body는 `mcp.trace.max-body-bytes`로 제한한다. 제한을 넘으면 Controller에 전달하지 않고 JSON-RPC `Invalid Request`로 종료한다. 이 설정은 로그 capture 크기가 아니라 입력 경계 보호 정책이다.
+- 현재 구현은 애플리케이션 로그만 제공하며 불변 감사 저장소가 아니다. 보존·위변조 방지·재처리가 필요한 규제 감사 요건이 확정되면 그때 별도 durable sink를 설계한다.
+- 응답을 쓰는 중 `IOException`이 나면 `mcp_http_response_undeliverable` event로 남긴다. 대개 Agent Builder가 먼저 연결을 끊은 경우이며, 이 로그가 없으면 결과 유실 자체를 관측할 수 없다.
+
+## 요청 시간 예산
+
+Agent Builder는 응답을 **300초**까지만 기다리고 연결을 끊는다. MCP의 예산은 그보다 짧아야 한다.
+같거나 길면 MCP가 응답을 완성해도 받을 상대가 이미 사라진 뒤다.
+
+| 계층 | 값 | 근거 |
+|---|---|---|
+| Agent Builder 대기 한도 | 300초 | 외부 제약. Agent가 MCP를 호출한 시점부터 잰다 ([ADR-0004](decisions/ADR-0004-execution-guardrails.md)) |
+| MCP 요청 전체 예산 `request-deadline-millis` | 270초 | 30초 여유. MCP 시계는 요청이 도착한 뒤 출발하므로 그만큼 더 안전하다 |
+| Tool 개별 timeout 상한 `maxToolTimeoutMillis` | **30초** | 매니페스트 선언값의 상한. **실질적으로 이 값이 요청 시간을 결정한다** |
+
+Tool 호출 직전마다 `remainingMillis()`로 남은 예산을 계산해 read timeout을 그 이하로 깎는다.
+따라서 Tool 하나가 자기 timeout을 다 써도 요청 전체 예산을 넘지 않는다.
+
+**270초는 실제로는 거의 도달하지 않는 backstop이다.** 한 요청은 Tool을 정확히 하나만 실행하고,
+그 Tool의 timeout은 30초로 상한이 걸려 있다. 따라서 정상 경로의 최대 소요는 연결 1초 + 읽기 30초
+수준이다. 270초가 의미를 갖는 것은 `maxToolTimeoutMillis`를 크게 올릴 때뿐이며,
+그때는 이 표 전체를 다시 계산해야 한다.
+
+이 관계 때문에 graceful shutdown 시간도 300초가 아니라 실질 상한(약 31초)에 맞춘다.
+`spring.lifecycle.timeout-per-shutdown-phase`(40초) < `terminationGracePeriodSeconds`(45초) 순서를 지켜,
+진행 중인 Tool 호출이 배포 중에 잘려 부작용만 남는 상황을 줄인다.
+
+연결이 이미 끊긴 뒤 Tool 결과가 도착하는 경우는 **완전히 막을 수 없다.** MCP는 결과를 저장했다가
+나중에 전달하지 않는다(stateless, [ADR-0001](decisions/ADR-0001-stateless-execution-boundary.md)).
+중복 실행 방지는 Tool Service의 책임이다. retry에서 같은 `guid`를 재사용해 멱등성 키로 삼을지는
+[미합의 항목](extension-points.md)이며, 합의 전에는 MCP가 이를 보장한다고 가정하지 않는다.
+
+## Protocol version 협상과 검증
+
+- 서버는 `mcp.protocol.supported-versions`와 `mcp.protocol.preferred-version`으로 지원 버전을 명시적으로 관리한다. preferred version은 반드시 supported versions에 포함되어야 한다.
+- `initialize` 응답은 요청의 JSON-RPC `id`를 그대로 반환하며, preferred version과 `serverInfo(name/title/version)`, `capabilities.tools.listChanged=true`를 제공한다.
+- 이 서버는 stateless이므로 협상 결과를 session에 저장하지 않는다. `initialize` 이후 Agent Builder는 모든 MCP HTTP 요청에 `MCP-Protocol-Version: <initialize 응답 protocolVersion>`을 포함해야 하며, 서버는 매 요청을 독립적으로 검증한다.
+- header가 누락되거나 지원하지 않는 값이면 JSON-RPC error가 아닌 HTTP `400 Bad Request`를 반환한다. 오류 body는 `error`, `message`, `supportedVersions`, `guid`를 포함해 호출자가 올바른 header를 진단할 수 있게 한다.
+
+## Initialize lifecycle correlation
+
+- `initialize`의 JSON-RPC result는 server protocol/capability 정보를 제공하고, HTTP response header `Mcp-Session-Id`에는 새 UUID를 제공한다.
+- Agent Builder는 이 값을 `notifications/initialized`, `tools/list`, `tools/call`의 `Mcp-Session-Id` header에 보낸다. 각 HTTP 요청은 별도 `x-request-id`를 유지한다.
+- Agent Builder는 MCP 2025-11-25 lifecycle에 따라 `notifications/initialized`를 보낸다. 서버는 이를 저장하거나 이후 요청의 readiness gate로 사용하지 않는다.
+- `InitializedNotificationHandler`는 id 없는 notification을 HTTP 202으로 수용한다. 이는 Tool 실행 준비 상태를 메모리에 세우는 동작이 아니므로 replica 간 affinity가 필요 없다.
+
+## Tool metadata 갱신 장애 시나리오
+
+요청 경로는 memory만 읽으므로 Redis 상태가 등장하지 않는다.
+
+| Memory | Tool Service aggregate | 결과 |
+|---|---|---|
+| hit | 무관 | memory 반환. **Redis를 호출하지 않는다** |
+| miss (기동 직후) | 확정 가능 | provider 직접 조회 후 memory 저장 |
+| miss (기동 직후) | 확정 불가 | Redis에 다른 replica의 snapshot이 있으면 채택, 없으면 `-32003 Tool registry unavailable` |
+
+readiness는 첫 discovery 시도 완료와 usable in-memory snapshot을 모두 요구한다. 원천 조회가 실패해도 기존
+memory 또는 Redis last-good을 채택했다면 UP이며, 둘 다 없어 `-32003`만 반환할 상태라면 DOWN이다. 따라서
+rolling update 중 새 Pod이 빈 catalog로 기존 정상 Pod을 대체하지 않는다. 정상 매니페스트가 빈 Tool 목록을
+반환한 경우에는 그 빈 목록도 성공적으로 확정된 전체 상태이므로 usable snapshot이다.
+
+배경 갱신 경로의 동작은 다음과 같다.
+
+| Tool Service aggregate | 기존 memory | Redis | 결과 |
+|---|---|---|---|
+| 확정 가능 | 무관 | 무관 | memory 갱신 후 Redis 저장(best-effort). **성공한 결과만 저장한다** |
+| 확정 불가 | hit | 무관 | 현재 memory 유지. 더 오래된 Redis 값으로 덮어쓰지 않는다 |
+| 확정 불가 | miss | hit | Redis의 공유 last-good snapshot으로 warm start |
+| 확정 불가 | miss | miss/장애 | `-32003`을 반환하고 다음 주기에 재시도 |
+
+각 bundle은 이번 성공본 또는 직전 성공본이 있어야 aggregate를 확정할 수 있다. 조회 실패는 Tool 삭제로 해석하지 않으며, 성공한 매니페스트에서 빠진 경우에만 삭제를 반영한다. 이름 충돌이나 총량 상한 초과도 전체 갱신 실패로 처리한다. 동시에 여러 refresh가 들어오면 single-flight로 하나의 원천 조회 결과를 공유한다.
+
+캐시에서 Tool을 찾지 못하면 stale snapshot 가능성을 고려해 원천을 한 번 더 조회한 뒤 `-32001`을 결정한다. 반대로 캐시에는 있던 Tool이 실행 시점에 upstream 404 또는 410을 반환하면 삭제된 Tool을 아직 들고 있는 stale snapshot 신호로 보고, 현재 요청은 Tool 실행 실패로 유지한 채 해당 route의 manifest refresh를 best-effort로 즉시 시도한다. 같은 route에서 삭제된 Tool 호출이 몰릴 때 Tool Server manifest 호출이 폭증하지 않도록 짧은 cooldown을 적용한다.
+Redis는 요청 경로의 의존성이 아닌 선택적인 warm-start cache다. Tool snapshot은 route별 key(`key-prefix:identity:v2:route:{routeToken}`)로 분리해 서로 다른 route의 Tool 목록이 섞이지 않게 하며, Portal registry fallback key와도 분리한다. key 형식, TTL, 공유 범위, 고가용성·보안 정책은
+아직 확정하지 않았으며 [extension-points.md](extension-points.md#운영-적용-전-필수-보완)에서 합의한다. 현재 구현값은
+운영 계약이나 장기 설계 결정이 아니다.
+
+## Local Tool manifest fallback
+
+로컬 Agent Builder 연동 검증도 실제 Tool Service와 같은 매니페스트 조회 흐름을 먼저 사용한다. `application-local.yml`의 bundle URL을 조회하고, **처음 조회가 실패했을 때만** `fallback-manifest-file`의 manifest sample을 snapshot으로 채택한다. 기본 sample은 프로젝트 루트의 `config/local-core-tools-manifest-sample-v1.json`이다. 원격 조회가 이후 성공하면 즉시 원격 목록으로 교체하며, 이미 확보한 원격 성공본은 local sample로 덮어쓰지 않는다.
+
+## Portal Registry and Tool manifest refresh
+
+로컬 검증에서는 `mcp.portal.registry-url`을 `file:./config/local-toolserver-info-sample-v1.json` 같은 Spring resource location으로 지정할 수 있다. 이 경우 MCP는 기동 preload와 주기 endpoint refresh에서 Portal HTTP API를 호출하지 않고 프로젝트 안의 registry JSON을 읽는다. 파일에서 확보한 endpoint 목록 이후의 Tool Server `tool-manifest` 주기 조회, route별 in-memory snapshot 갱신, Redis fallback 규칙은 Portal API를 사용할 때와 동일하다.
+
+Portal Registry를 사용하는 구성에서는 포털을 route별 Tool Server 목록의 원천으로만 사용한다. MCP는 기동 preload 때 포털 registry API를 먼저 호출해 `serviceDomain`과 `manifestPath`를 확보한 뒤 Tool Server `tool-manifest`를 조회한다. 이후에는 `mcp.registry.refresh-interval-seconds` 주기로 저장된 Tool Server 목록에 대해 manifest만 다시 조회하고, `mcp.portal.refresh-interval-seconds` 주기로 포털 registry만 별도로 갱신한다. 포털 `registryRevision`은 포털 응답 JSON 변경 로그와 Tool Server 목록 변경 진단에 사용하며, Tool Server 내부 tool/schema/revision/endpoint 변경 감지는 MCP의 manifest 주기 조회 결과를 route별 in-memory snapshot에 다시 병합하면서 처리한다. 요청 경로의 `tools/list`와 `tools/call`은 계속 in-memory snapshot만 읽는다. Portal API 조회가 실패하면 이미 확보한 in-memory Tool Server snapshot을 유지하며, cold start처럼 memory가 비어 있을 때만 `mcp.redis.portal-registry-key`의 Redis registry JSON을 fallback으로 읽는다. 이 Portal registry fallback은 route 목록과 Tool Server 목록 확보용이고, route별 Tool snapshot Redis key는 이미 알고 있는 route의 마지막 Tool 목록 fallback에만 사용한다. Redis fallback도 실패하면 Tool Server 원천을 확보하지 못한 것으로 처리하고 다음 주기에서 재시도한다.
+
+노출 대상 Tool은 그 파일이 정의한다. 목록을 이 문서에 옮겨 적지 않는다. 파일의 공개 필드는 그대로 보존하고 `_meta`와 `endpoint` 실행 정보만 제거해 `tools/list`에 내보낸다. fallback도 원격 매니페스트와 같이 top-level `endpoint` 또는 `_meta.endpoint`를 내부 실행 endpoint로 사용한다.
+
+이 fixture는 연동 확인용이며 실제 고객·계약·수납·지급 데이터를 담지 않는다.
+
+운영 profile에서는 `ToolBundleDiscovery`와 `ToolBundleRegistryClient`만 metadata 원천으로 활성화한다. MCP 배포별 `mcp.bundles`가 Tool Service의 매니페스트와 실행 주소를 선언한다. 운영 Helm 설정에는 fallback 파일을 넣지 않는다. Tool Service는 표준 `name`을 소유하고, MCP는 자기 Bundle 안에서 형식·설정된 `namePrefix`·중복을 검증하되 이름을 재작성하지 않는다. 서로 다른 MCP 배포 간 이름의 전역 유일성은 Tool Service·플랫폼의 변경 절차가 보장한다. Redis는 선택적인 공유 last-good cache일 뿐 Tool 목록의 원천이 아니다.
+
+**`mcp.bundles`는 N개를 지원하지만 운영 배포에서는 항상 한 항목이다.** MCP 배포 하나가 Tool Service 하나만 보기로 했기 때문이다([ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 이 목록을 늘리는 것이 아니라 MCP 배포를 하나 더 만드는 것이다. 그래야 등급이 다른 Tool Service의 조회 실패가 서로의 카탈로그 갱신을 막지 않는다. 다중 bundle 병합 코드는 유지하되 Helm Chart가 1개로 잠그고 `HelmDeploymentContractTest`가 그 사실을 검사한다.
+
+각 배포는 같은 환경 host의 고유 `publicPath`를 가진 OpenShift Route로 노출된다([ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)). Route는 path로 Service만 선택하고 컨테이너가 같은 값을 `mcp.endpoint-path`로 직접 처리한다. Java 애플리케이션에는 route table이나 다중 Registry를 추가하지 않는다. Deployment·snapshot·readiness·connection pool은 path별로 분리되고, 공유되는 장애 지점은 OpenShift ingress와 DNS다.
+
+운영 상태는 외부 ingress가 아니라 management port(기본 9090)의 `GET /actuator/toolBundles`로 확인한다.
+
+## 변경 시 검증 경계
+
+- MCP envelope/method 변경: adapter → handler registry → handler 직렬화 테스트
+- `tools/call` 변경: handler params → Registry metadata → argument validator → routing → Tool client → error mapping
+- Tool metadata 변경: 매니페스트 역직렬화·bundle 검증 → aggregate 확정 → memory/Redis fallback → refresh scheduler
+- correlation 변경: header extractor → filter/context 정리 → response/downstream header
+- 공개 path/배포 변경: topology의 path 유일성 → Route host/path/Service → ConfigMap endpoint → Controller·Filter → Agent Builder 등록 URL
+- 최종 확인: `.\gradlew.bat clean check`, `bootJar`, 실행 JAR의 initialize → notification → tools/list 흐름
+## Tool list change notification
+
+`initialize`는 `capabilities.tools.listChanged=true`를 선언한다. 배경 Registry refresh가 기존 route snapshot과 다른 Tool 목록을 성공적으로 확보하면 `ToolListChangedEvent`가 표준 `notifications/tools/list_changed` JSON-RPC notification envelope를 만든다. 현재 HTTP 단발 응답 transport는 notification을 직접 push하지 않으며, SSE/Streamable HTTP 전송 계층이 추가되면 이 이벤트를 route별 Agent 연결에 전달하고 Agent Builder가 `tools/list`를 다시 호출한다.
+
+
+- 임시 검증에서 Agent↔MCP와 MCP↔Tool Service payload를 확인해야 하면 `mcp.trace.payload-logging-enabled=true`를 켠다. 이 로그는 JSON 한 줄 형태로 요청·응답 본문을 남기므로 운영 기본값은 false이며, 검증 후 즉시 꺼야 한다.

docs/codex-workflow.md

@@ -0,0 +1,66 @@
+# Codex 활용 및 저장소 공개 정책
+
+## 목적과 책임
+
+| 항목 | 소비자 | 저장소 포함 |
+|---|---|---:|
+| `AGENTS.md` | Codex의 모든 작업 | 아니오 |
+| `.agents/skills/` | 조건에 맞는 Codex 작업 | 아니오 |
+| `.codex/config.toml` | 신뢰된 프로젝트에서의 Codex 실행 환경 | 아니오 |
+| `docs/` | 개발자와 리뷰어 | 예 |
+| `src/` | 애플리케이션 빌드와 테스트 | 예 |
+| `deploy/` | 배포 플랫폼 | Secret이 없을 때만 예 |
+| `samples/` | 개발자와 테스트 | 가짜 데이터일 때만 예 |
+
+루트의 `AGENTS.md`, `.agents/`, `.codex/`는 Codex의 표준 탐색 지점이다. 보기 좋게 다른 하위 폴더로 옮기지 않는다. 사람을 위한 설명은 이 문서와 `README.md`에 둔다.
+
+에이전트 지침(`AGENTS.md`, `.agents/`, `.codex/`)은 `.gitignore`가 제외한다. 에이전트 작업 산출물인 `docs/superpowers/`도 마찬가지다. 저장소 문서가 아니므로 반입 대상에 넣지 않는다.
+
+**`docs/` 자체는 제외하지 않는다.** `AgentBuilderContractExampleTest`, `ToolBundleContractExampleTest`, `ArchitectureDocumentContractTest`가 `docs/` 아래 계약 예제와 architecture 문서를 **입력으로 직접 읽기** 때문이다. 문서를 저장소 밖에 두면 clean clone에서 이 세 계약 테스트가 입력을 찾지 못한다. 문서와 코드가 함께 검증되도록 같은 저장소에 둔다.
+
+한때 `docs/`를 `.gitignore`에 넣은 적이 있고, 그 상태에서 계약 예제 16개와 `architecture.md`가 사라져 테스트 10건이 깨졌다. 에이전트 산출물만 좁게 제외하고 저장소 문서는 추적한다.
+
+## 일상 작업 흐름
+
+1. 일반 작업은 루트 `AGENTS.md` 규칙을 따른다.
+2. JSON-RPC, MCP method, Tool Registry, Tool 실행, trace log, Spring profile, OpenShift 배포를 변경할 때는 `$verify-mcp-server-change`를 명시적으로 호출한다.
+3. Skill은 코드와 관련 테스트를 읽고 영향 계약을 확인한 뒤 최소 변경과 Gradle 테스트를 요구한다.
+4. 반복 작업이 세 번 이상 안정적으로 반복되면 새 skill 후보로 검토한다. 임시 작업, 일회성 지침, 개인 메모는 skill로 만들지 않는다.
+5. 작업 중 발견한 규칙은 재현·검토된 뒤에만 `AGENTS.md`, skill reference, 또는 설계 문서에 반영한다.
+
+예시:
+
+```text
+$verify-mcp-server-change
+tools/call의 인자 검증을 변경하고 관련 테스트와 문서를 갱신해 줘.
+```
+
+## Codex 설정 정책
+
+개인 전역 Codex 설정에는 선호 모델, approval policy, sandbox mode, 개인 MCP 서버, 로컬 경로, 인증 정보를 둔다. 이 내용은 저장소에 올리지 않는다.
+
+프로젝트 `.codex/config.toml`은 다음 조건을 모두 충족할 때만 추가하고 Git에 포함한다.
+
+- 모든 팀원이 동일하게 적용해야 한다.
+- 프로젝트 고유의 설정이다.
+- 비밀정보, 개인 경로, 개인 권한 선호, 개인 MCP 연결이 없다.
+- 일반 코드 변경처럼 리뷰할 수 있다.
+
+현재 이 프로젝트는 위 조건에 해당하는 공유 Codex 실행 설정이 없으므로 `.codex/config.toml`을 사용하지 않는다. 프로젝트 설정이 필요한 시점에는 팀 검토 후 `.gitignore`의 해당 예외 규칙을 함께 변경한다.
+
+## GitHub 게시 전 점검
+
+1. 기본 공개 범위는 private로 한다. 공개 전환은 조직 정책, 내부 명칭, 배포 정보, 계약 문서, 샘플 데이터 검토 후 별도 결정한다.
+2. `AGENTS.md`, `.agents/skills/`, 소스, 테스트, 가짜 샘플, 비밀정보 없는 배포 명세와 문서는 커밋한다.
+3. `.env`, 인증서, keystore, Secret manifest, 실제 고객·운영 데이터, 개인 Codex 설정은 커밋하지 않는다.
+4. 첫 push 전에 Secret 검색을 실행하고, GitHub에서는 secret scanning, push protection, Dependabot, 기본 브랜치 보호를 활성화한다.
+5. 외부 공개가 확정되면 `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`와 공개용 샘플·문서를 추가한다.
+
+## 구조 확장 기준
+
+- `docs/decisions/`: 장기 설계 결정이 실제로 발생할 때 ADR을 추가한다.
+- `src/<subtree>/AGENTS.md`: 특정 하위 모듈의 명령이나 규칙이 루트와 달라질 때만 추가한다.
+- `.agents/skills/<name>/`: 반복되고 안정적인 작업 절차가 생길 때만 추가한다.
+- `.codex/hooks/`: 지침과 테스트로 보장할 수 없는 결정적 정책을 강제해야 할 때만 추가한다.
+
+빈 폴더나 자동 누적 `lessons.md`는 만들지 않는다.

docs/contracts/agent-builder-mcp/README.md

@@ -0,0 +1,18 @@
+# Agent Builder-MCP 계약 문서
+
+이 디렉터리는 현재 구현 계약과 목표 합의 기준선을 분리해 관리한다.
+
+| 문서 | 상태 | 용도 |
+|---|---|---|
+| [protocol-v0.3-streaming-policy.md](protocol-v0.3-streaming-policy.md) | Implemented | `text/event-stream` Accept를 수용하는 동기 JSON 현재 계약 |
+| [protocol-v0.2-agentbuilder.md](protocol-v0.2-agentbuilder.md) | Superseded | streaming 정책 도입 전 non-streaming 계약 |
+| [protocol-v1-agreement-baseline.md](protocol-v1-agreement-baseline.md) | Partial Agreement | 2026-07-10 협의에서 확정된 목표 원칙만 기록 |
+
+`protocol-v1-agreement-baseline.md`는 아직 실행 가능한 전체 wire contract가 아니다. Agent Builder의 전체 JSON 샘플과 미확정 항목이 승인되기 전까지 현재 구현을 변경하는 직접 근거로 사용하지 않는다.
+
+현재 구현 예시는 [examples/agentbuilder-v0.3](examples/agentbuilder-v0.3/)에서 관리한다. `initialize` 이후 요청에는 `MCP-Protocol-Version` HTTP header가 필요하다.
+현재 공개 주소는 환경별 host와 배포별 path를 합친 `https://{mcpHost}{publicPath}`이며, 각 URL을 독립 MCP로 등록한다. 컨테이너가 공개 path를 rewrite 없이 직접 처리하는 기준은 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)이 정본이다.
+
+`publicPath`가 `/mcp`인 Portal 구성에서는 URL의 path segment가 route를 정한다(`POST /mcp/{routeKey}`). 한 배포가 N개 route를 서비스하며 route 하나에 N개 Tool Service가 붙을 수 있고([ADR-0013](../../decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md)), 등록되지 않은 route는 controller 진입 전에 거부된다. 두 형태와 거부 조건은 [v0.3의 공개 URL과 route key](protocol-v0.3-streaming-policy.md#공개-url과-route-key)가 정본이다.
+
+Agent Builder가 실제 Tool을 호출하며 남긴 관찰용 JSON-RPC 로그는 [observed-samples/2026-07-13](observed-samples/2026-07-13/)에 분리해 보관한다. 이 로그는 구현 계약이나 자동화 테스트 fixture가 아니다.

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-request.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-11-25",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-response.json

@@ -0,0 +1,9 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-11-25",
+    "serverInfo": {},
+    "capabilities": {}
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialized-notification.json

@@ -0,0 +1,5 @@
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized",
+  "params": {}
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-execution-error-response.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "customer.search@1.0.0: timed out"
+      }
+    ],
+    "isError": true
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-request.json

@@ -0,0 +1,11 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "customer.search",
+    "arguments": {
+      "customerNo": "1234567890"
+    }
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-success-response.json

@@ -0,0 +1,16 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"customerName\":\"Hong\"}"
+      }
+    ],
+    "structuredContent": {
+      "customerName": "Hong"
+    },
+    "isError": false
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/initialize-response.json

@@ -0,0 +1,17 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-11-25",
+    "capabilities": {
+      "tools": {
+        "listChanged": true
+      }
+    },
+    "serverInfo": {
+      "name": "shl-axhub-mcp-server-external",
+      "title": "SHL AX HUB MCP Server (EXTERNAL)",
+      "version": "1.0.0"
+    }
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-execution-error-response.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "customer.search@1.0.0: timed out"
+      }
+    ],
+    "isError": true
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-invalid-params-response.json

@@ -0,0 +1,8 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "error": {
+    "code": -32602,
+    "message": "Invalid params: 'query' is required"
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-request.json

@@ -0,0 +1,12 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "processing",
+    "arguments": {
+      "query": "processing system information inquiry",
+      "category": "processing"
+    }
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-success-response.json

@@ -0,0 +1,16 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "processing complete",
+        "_meta": {
+          "searchTime": 976.1
+        }
+      }
+    ],
+    "isError": false
+  }
+}

docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json

@@ -0,0 +1,67 @@
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "tools": [
+      {
+        "name": "insurance.processing.test",
+        "title": "처리계 연계 점검",
+        "description": "처리계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 보험 업무 데이터는 처리하지 않습니다.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "requestId": {
+              "type": "string",
+              "description": "테스트 요청 식별자입니다."
+            }
+          }
+        },
+        "annotations": {
+          "readOnlyHint": true,
+          "destructiveHint": false,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "insurance.corebanking.test",
+        "description": "계정계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 계약·수납·지급 처리는 수행하지 않습니다.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "requestId": {
+              "type": "string",
+              "description": "테스트 요청 식별자입니다."
+            }
+          }
+        }
+      },
+      {
+        "name": "insurance.information.test",
+        "description": "정보계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 고객·계약 정보를 조회하지 않습니다.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "requestId": {
+              "type": "string",
+              "description": "테스트 요청 식별자입니다."
+            }
+          }
+        }
+      },
+      {
+        "name": "insurance.channel.test",
+        "description": "채널계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 고객 채널 업무를 수행하지 않습니다.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "requestId": {
+              "type": "string",
+              "description": "테스트 요청 식별자입니다."
+            }
+          }
+        }
+      }
+    ]
+  }
+}

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-response.json

@@ -0,0 +1,34 @@
+{
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "tools": {
+        "listChanged": true
+      },
+      "prompts": {
+        "listChanged": true
+      },
+      "resources": {
+        "listChanged": true
+      }
+    },
+    "serverInfo": {
+      "name": "exa-search-server",
+      "title": "Exa",
+      "version": "3.2.1",
+      "websiteUrl": "<https://exa.ai>",
+      "icons": [
+        {
+          "src": "<https://exa.ai/images/favicon-32x32.png>",
+          "mimeType": "image/png",
+          "sizes": [
+            "32x32"
+          ]
+        }
+      ]
+    }
+  },
+  "jsonrpc": "2.0",
+  "id": 1
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialized-notification.json

@@ -0,0 +1,5 @@
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-request.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "web_search_exa",
+    "arguments": {
+      "query": "most popular useless github repository stars useless repo",
+      "numResults": 10
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316.md

@@ -0,0 +1,183 @@
+# 관찰 로그 01 - exa / `web_search_exa`
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다.
+
+## 헤더 및 실행 메타데이터
+
+| 항목 | 원본 기록 값 |
+|---|---|
+| transport type | `mcp-http` |
+| request_id | `045992d3-9683-4409-9613-e355a3eb05e1` |
+| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` |
+| Tool version | `2.0` |
+| 실행 시각 | 2026-07-13 16:53:16 UTC |
+| 결과 | ok · 1896ms · truncated=False |
+| JSON-RPC 프레임 수 | 5 |
+| lifecycle | `initialize → notifications/initialized → tools/call` |
+
+### HTTP 헤더 기록 범위
+
+원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다.
+
+원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다.
+
+## JSON-RPC 통신 전문
+
+아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다.
+
+```text
+16:53:16 요청 → initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"method": "initialize",
+"params": {
+"protocolVersion": "2025-06-18",
+"capabilities": {},
+"clientInfo": {
+"name": "toolbox-executor",
+"version": "0.1.0"
+}
+}
+}
+16:53:16 ← 응답 initialize
+{
+"result": {
+"protocolVersion": "2025-06-18",
+"capabilities": {
+"tools": {
+"listChanged": true
+},
+"prompts": {
+"listChanged": true
+},
+"resources": {
+"listChanged": true
+}
+},
+"serverInfo": {
+"name": "exa-search-server",
+"title": "Exa",
+"version": "3.2.1",
+"websiteUrl": "<https://exa.ai>",
+"icons": [
+{
+"src": "<https://exa.ai/images/favicon-32x32.png>",
+"mimeType": "image/png",
+"sizes": [
+"32x32"
+]
+}
+]
+}
+},
+"jsonrpc": "2.0",
+"id": 1
+}
+16:53:16 요청 → notifications/initialized
+{
+"jsonrpc": "2.0",
+"method": "notifications/initialized"
+}
+16:53:17 요청 → tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"method": "tools/call",
+"params": {
+"name": "web_search_exa",
+"arguments": {
+"query": "most popular useless github repository stars useless repo",
+"numResults": 10.0
+}
+}
+}
+16:53:18 ← 응답 tools/call
+{
+"result": {
+"content": [
+{
+"type": "text",
+"text": "Title: btahir/uselesshooks\nURL: <https://github.com/btahir/uselesshooks\nPublished:
+> N/A\nAuthor: N/A\nHighlights:\n# btahir/us\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Open
+issues: 3\n- License: MIT License\n- Default branch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\n
+Title: Useless-Garbage-Institute/useless-garbage\nURL: <https://github.com/Useless-Garbage-Institute/
+useless-garbage\nPublished:> 2015-08-27T22:14:06.000Z\nAuthor: N/A\nHighlights:\n# Repository: Useles
+s-Garbage-Institute/useless-garbage\n...\nThe most profoundly useless javascript library ever invente
+d.\n...\n- Stars: 6\n- Forks: 1\n- Watchers: 6\n- Open issues: 1\n- Primary language: JavaScript\n- L
+anguages: JavaScript\n- Default branch: master\n- Created: 2015-08-27T22:14:06Z\n- Last push: 2015-09
+-01T01:14:37Z\n- Contributors: 2 (top: kriztynna, cgalbiati)\n...\nThe useless-garbage library is the
+only npm module that is guaranteed to have no redeemable functionality whatsoever. There are plenty o
+f helpful JavaScript libraries out there, and some that are of questionable utility, but none that ar
+e share our commitment to utter uselessness.\n\n---\n\nTitle: tomekw/whatever\nURL: <https://github.c
+om/tomekw/whatever\nPublished:> N/A\nAuthor: N/A\nHighlights:\n- Stars: 281\n- Forks: 115\n- Watcher
+s: 281\n- Open issues: 2\n- Default branch: master\n- Created: 2014-10-10T15:51:31Z\n\n---\n\nTitle:
+thecodersroom/the-button-that-does-nothing\nURL: <https://github.com/thecodersroom/the-button-that-do
+es-nothing\nPublished:> 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n# Repository: thecodersro
+om/the-button-that-does-nothing\n...\nthat looks important\n...\nliterally does nothing\n...\n- Star
+s: 21\n- Forks: 67\n- Watchers: 0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: Ja
+vaScript (45.4%), CSS (41.9%), HTML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfe
+st, hacktoberfest-accepted, html, javascript\n- Default branch: main\n- Homepage: <https://thecodersr
+oom.github.io/the-button-that-does-nothing/\n-> Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-0
+4T09:02:47Z\n- Contributors: 60 (top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith28
+55, kronpatel, ahmedrazabaloch, AhishRagav, Nl-T-lN, vanshikap21)\n...\nbuilt entirely with **\n\n---
+\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of software that serve no purpose o
+ther than waste your time. Forking is encouraged!\nURL: <https://github.com/niltok64/the-useless-coll
+ection\nPublished:> 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\n64/the\n...\nuseless-col
+lection\n...\n[\nStar\n1\n](<https://github.com/login?return_to=/niltok64/the-useless-collection>)\n*
+\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n
+[niltok64.github.io/the-useless-collection/](<https://niltok64.github.io/the-useless-collection/>)\n#
+## License\n...\nstar\n](<https://github.com/niltok64/the-useless-collection/stargazers>) [\n0
+\n...\n://github.com/niltok64/the-useless-collection/forks)\n...\n://github.com/niltok64/the-useless-
+collection/branches) [\n...\n://github.com/niltok64/the-useless-collection/tags) [\nActivity
+\n...\n://github.\n...\n/nilt\n...\nthe-useless-collection\n...\n[\n**1**\nstar\n](<https://github.co
+m/niltok64/the-useless-collection/stargazers>)\n...\n### Watchers\n\n---\n\nTitle: GitHub - needless-
+org/needless: The JavaScript library you never asked for, never needed, and probably shouldn't use. B
+ut here we are!\nURL: <https://github.com/needless-org/needless\nPublished:> 2023-09-05T14:04:16.000Z
+\nAuthor: needless-org\nHighlights:\nGitHub - needless-org/needless: The JavaScript library you never
+asked for, never needed, and probably shouldn't use. But here we are!\n...\n[Skip to\n...\nneedless-o
+rg/needless)\n...\nhttps://github\n...\ncom/login?return_to=/needless-org/needless)\n...\n[\nStar\n1
+\n](<https://github.com/login?return_to=/needless-org/needless>)\n*\nThe JavaScript library you never
+asked for, never needed, and probably shouldn't use. But here we are!\n...\n[\n1\nstar\n](<https://gi
+thub.com/needless-org/needless/stargazers>) [\n0\nforks\n](<https://github.com/needless-org/needless/
+forks>) [\nBranches\n](<https://github.com/needless-org/needless/branches>) [\nTags\n](<https://githu
+b.com/needless-org/needless/tags>) [\nActivity\n](<https://github.com/needless-org/needless/activity
+>)\n[\n...\nneedless-\n...\nneedless)\n...\nThe JavaScript library you never asked for, never needed,
+and probably shouldn't use. But here we are!\n...\n\"My project is running too\n...\nwish there was
+\n...\nadd some completely unnecessary\n...\nno further!\n...\nIntroducing `needless-js`, the world's
+first and foremost pointless library. We bring the \"Why?\" into \"Why is this even a thing?\".\n## F
+eatures\n...\n1. **Absolutely Useless**: Doesn't fix any problems because it doesn't know what proble
+ms are.\n2. **Hilariously Redundant**: Why have one function when you can have ten doing the same thi
+ng?\n3. **Zero Dependencies**: Mainly because no other library wants to be associated with us.\n4. **
+Eco-friendly**: Uses 0% CPU because it does absolutely nothing.\n## Installation\n...\n[\n**1**\nstar
+\n...\n](<https://github.com/needless-org/needless/stargazers>)\n\n---\n\nTitle: GitHub - terremoth/a
+wesome-hilarious-repos\nURL: <https://github.com/terremoth/awesome-hilarious-repos\nPublished:> N/A\n
+Author: N/A\nHighlights:\nAwesome Hilarious Github Repositories. Awesome license. GitHub contributor
+s. List of all (?) available and funniest Github repos. Contribute if you know others!\n\n---\n\nTitl
+e: SuavePirate/Xamarin.Yeet\nURL: <https://github.com/SuavePirate/Xamarin.Yeet\nPublished:> 2020-02-2
+2T21:16:23.000Z\nAuthor: N/A\nHighlights:\n# Repository: SuavePirate/Xamarin.Yeet\n...\nAn absolutely
+useless tool to yeet your components off the screen.\n...\n- Stars: 2\n- Forks: 1\n- Watchers: 1\n- O
+pen issues: 0\n- Primary language: C#\n- Languages: C#\n- License: MIT License (MIT)\n- Default branc
+h: master\n- Created: 2020-02-22T21:16:23Z\n- Last push: 2020-02-22T21:31:11Z\n- Contributors: 1 (to
+p: SuavePirate)\n...\nAn absolutely useless tool to yeet your components off the screen.\n\n---\n\nTi
+tle: nico-garnier/useless-repo\nURL: <https://github.com/nico-garnier/useless-repo\nPublished:> 2020-
+12-03T11:49:46.000Z\nAuthor: N/A\nHighlights:\n# Repository: nico-garnier/useless-repo\n...\n- Stars:
+1\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: main\n- Created: 2020-12-03T11:49:4
+6Z\n- Last push: 2020-12-03T14:16:57Z\n- Contributors: 2 (top: nico-garnier, eilenilec)\n...\n# usele
+ss-repo\n...\nFor github stat on top collaborators only.\n\n---\n\nTitle: elierotenberg/useless | Git
+Hub | Open Source Insights\nURL: <https://deps.dev/project/github/elierotenberg%2fuseless\nPublished:
+> N/A\nAuthor: N/A\nHighlights:\nelierotenberg/useless | GitHub | Open Source Insights\n...\n# eliero
+tenberg/useless\n...\n33 stars",
+"_meta": {
+"searchTime": 1071.9
+}
+}
+]
+},
+"jsonrpc": "2.0",
+"id": 3
+}
+```
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-response.json

@@ -0,0 +1,34 @@
+{
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "tools": {
+        "listChanged": true
+      },
+      "prompts": {
+        "listChanged": true
+      },
+      "resources": {
+        "listChanged": true
+      }
+    },
+    "serverInfo": {
+      "name": "exa-search-server",
+      "title": "Exa",
+      "version": "3.2.1",
+      "websiteUrl": "<https://exa.ai>",
+      "icons": [
+        {
+          "src": "<https://exa.ai/images/favicon-32x32.png>",
+          "mimeType": "image/png",
+          "sizes": [
+            "32x32"
+          ]
+        }
+      ]
+    }
+  },
+  "jsonrpc": "2.0",
+  "id": 1
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialized-notification.json

@@ -0,0 +1,5 @@
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-request.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "web_search_exa",
+    "arguments": {
+      "query": "site:github.com \"does nothing\" stars",
+      "numResults": 10
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324.md

@@ -0,0 +1,176 @@
+# 관찰 로그 02 - exa / `web_search_exa`
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다.
+
+## 헤더 및 실행 메타데이터
+
+| 항목 | 원본 기록 값 |
+|---|---|
+| transport type | `mcp-http` |
+| request_id | `536d9a7e-be3e-4847-8878-f71ae1d690ba` |
+| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` |
+| Tool version | `2.0` |
+| 실행 시각 | 2026-07-13 16:53:24 UTC |
+| 결과 | ok · 1768ms · truncated=False |
+| JSON-RPC 프레임 수 | 5 |
+| lifecycle | `initialize → notifications/initialized → tools/call` |
+
+### HTTP 헤더 기록 범위
+
+원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다.
+
+원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다.
+
+## JSON-RPC 통신 전문
+
+아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다.
+
+```text
+16:53:24 요청 → initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"method": "initialize",
+"params": {
+"protocolVersion": "2025-06-18",
+"capabilities": {},
+"clientInfo": {
+"name": "toolbox-executor",
+"version": "0.1.0"
+}
+}
+}
+16:53:24 ← 응답 initialize
+{
+"result": {
+"protocolVersion": "2025-06-18",
+"capabilities": {
+"tools": {
+"listChanged": true
+},
+"prompts": {
+"listChanged": true
+},
+"resources": {
+"listChanged": true
+}
+},
+"serverInfo": {
+"name": "exa-search-server",
+"title": "Exa",
+"version": "3.2.1",
+"websiteUrl": "<https://exa.ai>",
+"icons": [
+{
+"src": "<https://exa.ai/images/favicon-32x32.png>",
+"mimeType": "image/png",
+"sizes": [
+"32x32"
+]
+}
+]
+}
+},
+"jsonrpc": "2.0",
+"id": 1
+}
+16:53:24 요청 → notifications/initialized
+{
+"jsonrpc": "2.0",
+"method": "notifications/initialized"
+}
+16:53:24 요청 → tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"method": "tools/call",
+"params": {
+"name": "web_search_exa",
+"arguments": {
+"query": "site:github.com \"does nothing\" stars",
+"numResults": 10.0
+}
+}
+}
+16:53:25 ← 응답 tools/call
+{
+"result": {
+"content": [
+{
+"type": "text",
+"text": "Title: michaelb/do-nothing.vim\nURL: <https://github.com/michaelb/do-nothing.vim\nPu
+blished:> N/A\nAuthor: N/A\nHighlights:\nA vim plugin that does nothing. Because why not\n...\n- Star
+s: 121\n- Forks: 4\n- Watchers: 121\n- Open issues: 1\n- License: MIT License\n- Default branch: main
+\n- Created: 2021-07-06T07:35:05Z\n...\nThis plugin doesn't do anything.\n\n---\n\nTitle: silicakes/n
+ada-js\nURL: <https://github.com/silicakes/nada-js\nPublished:> N/A\nAuthor: N/A\nHighlights:\nA Libr
+ary that does nothing\n...\n- Stars: 32\n- Forks: 0\n- Watchers: 32\n- Open issues: 3\n- License: MIT
+License\n- Default branch: main\n- Created: 2019-05-29T22:52:59Z\n...\n### A Library that does nothin
+g in or for your project\n...\nNadaJS gives a single guarantee: Aside from taking space, it will do a
+bsolutely nothing.\nNo matter what kind of project, architecture or constraints you might have, nadaJ
+S always gets nothing done.\n\n---\n\nTitle: GitHub - azr/donothing: does nothing !\nURL: <https://gi
+thub.com/azr/donothing\nPublished:> 2012-10-25T16:10:49.000Z\nAuthor: azr\nHighlights:\nGitHub - az
+\n...\ndonothing: does nothing !\n...\n[\nStar\n1\n](<https://github.com/login?return_to=/azr/donothi
+ng>)\n...\n*\ndoes nothing !\n### License\n...\n[\n1\n...\nstar\n](<https://github.com/azr/donothing/
+stargazers>) [\n0\n...\n://github.com/azr/donothing/forks) [\n...\n://github.com/azr/donothing/branch
+es\n...\nTags\n](\n...\n://github.com/azr/donothing/tags\n...\n://github.com/azr/donothing/activity)
+\n...\n://github.com/\n...\n=/azr/donothing)\n...\ndoes nothing !\n...\n[\n**1**\nstar\n](<https://gi
+thub.com/azr/donothing/stargazers>)\n\n---\n\nTitle: imjakechapman/TheNothingApp\nURL: <https://githu
+b.com/imjakechapman/TheNothingApp\nPublished:> 2014-06-19T22:35:01.000Z\nAuthor: N/A\nHighlights:\nTh
+e app that does literally nothing.\n...\n- Stars: 19\n- Forks: 2\n- Watchers: 19\n- Open issues: 2\n-
+Primary language: Swift\n- Languages: Swift (71.3%), Java (28.7%)\n- Default branch: master\n- Homepa
+ge: thenothingapp.com\n- Created: 2014-06-19T22:35:01Z\n- Last push: 2015-06-22T22:07:41Z\n- Contribu
+tors: 2 (top: imjakechapman, thiagokimo)\n...\nThe app that does literally nothing, hackernews/design
+ernews/twitter approved best application for doing jack-diddley-squat.\n\n---\n\nTitle: thecodersroo
+m/the-button-that-does-nothing\nURL: <https://github.com/thecodersroom/the-button-that-does-nothing\n
+Published:> 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n- Stars: 21\n- Forks: 67\n- Watchers:
+0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: JavaScript (45.4%), CSS (41.9%), H
+TML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfest, hacktoberfest-accepted, htm
+l, javascript\n- Default branch: main\n- Homepage: <https://thecodersroom.github.io/the-button-that-d
+oes-nothing/\n-> Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-04T09:02:47Z\n- Contributors: 60
+(top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith2855, kronpatel, ahmedrazabaloch,
+AhishRagav, Nl-T-lN, vanshikap21)\n\n---\n\nTitle: seeschloss/nothing-to-see-here\nURL: <https://gith
+ub.com/seeschloss/nothing-to-see-here\nPublished:> N/A\nAuthor: N/A\nHighlights:\nAn NPM package whic
+h does nothing\n...\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- License: MIT License
+\n- Default branch: master\n- Created: 2015-01-21T08:32:44Z\n...\n## Usage ##\n\n var nothing = requi
+re('nothing-to-see-here');\n // Do nothing with nothing, since it does nothing at all.\n\n---\n\nTitl
+e: 10xly/do-nothing\nURL: <https://github.com/10xly/do-nothing\nPublished:> N/A\nAuthor: N/A\nHighlig
+hts:\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 202
+4-09-06T19:20:09Z\n- Fork: yes\n...\nDo nothing.\n...\nIt's just another noop\n\n---\n\nTitle: Search
+code, repositories, users, issues, pull requests...\nURL: <https://github.com/techsiddhi/does-nothing
+\nPublished:> 2025-07-22T16:46:01.000Z\nAuthor: techsiddhi\nHighlights:\n.com/\n...\n](https://
+\n...\n* [Notifications](<https://github.com/login?return_to=/techsiddhi/does-nothing>)You must be si
+gned in to change notification settings\n* [Fork0](<https://github.com/login?return_to=/techsiddhi/do
+es-nothing>)\n* [Star1](<https://github.com/login?return_to=/techsiddhi/does-nothing>)\n...\n[1star]
+(<https://github.com/techsiddhi/does-nothing/stargazers>)[0forks](<https://github.com/techsiddhi/does
+-nothing/forks>)[Branches](<https://github.com/techsiddhi/does-nothing/branches>)[Tags](<https://gith
+ub.com/techsiddhi/does-nothing/tags>)[Activity](<https://github.com/techsiddhi/does-nothing/activity
+>)\n...\n[Star](<https://github.com/login?return_to=/techsiddhi/does-nothing>)\n...\n/activity)
+\n...\n[**1**star](<https://github.com/techsiddhi/does-nothing/stargazers>)\n### Watchers\n[**0**watc
+hing](<https://github.com/techsiddhi/does-nothing/watchers>)\n\n---\n\nTitle: NicusorN5/DoNothing\nUR
+L: <https://github.com/NicusorN5/DoNothing\nPublished:> 2023-08-19T15:20:52.000Z\nAuthor: N/A\nHighli
+ghts:\nThis does nothing. Literally nothing.\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issu
+es: 0\n- Primary language: Assembly\n- Languages: Assembly\n- License: MIT License (MIT)\n- Topics: a
+ssembly, nothing\n- Default branch: main\n- Created: 2023-08-19T15:20:52Z\n- Last push: 2023-08-19T1
+5:29:03Z\n- Contributors: 1 (top: NicusorN5)\n- Releases: 1\n- Latest release: release (2023-08-19T1
+5:29:03Z)\n- Archived: true\n...\nThis does nothing. Literally nothing.\n\n---\n\nTitle: README.md\nU
+RL: <https://github.com/torahappy/does_nothing/blob/master/README.md\nPublished:> N/A\nAuthor: N/A\nH
+ighlights:\n# does_nothing : A library that does nothing\n...\n- `function a()`\n - Description: Does
+some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `function b()`\n - De
+scription: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `func
+tion c()`\n - Description: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothin
+g.\n...\nThough functions in this library are completely harmless and consume little cpu resource, no
+t telling users that the program sometimes does a meaningless calculation or computes inefficiently m
+ay result in a criminal prosecution as the program may be against users' intention. (in Japan)",
+"_meta": {
+"searchTime": 976.1
+}
+}
+]
+},
+"jsonrpc": "2.0",
+"id": 3
+}
+```
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-response.json

@@ -0,0 +1,34 @@
+{
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "tools": {
+        "listChanged": true
+      },
+      "prompts": {
+        "listChanged": true
+      },
+      "resources": {
+        "listChanged": true
+      }
+    },
+    "serverInfo": {
+      "name": "exa-search-server",
+      "title": "Exa",
+      "version": "3.2.1",
+      "websiteUrl": "<https://exa.ai>",
+      "icons": [
+        {
+          "src": "<https://exa.ai/images/favicon-32x32.png>",
+          "mimeType": "image/png",
+          "sizes": [
+            "32x32"
+          ]
+        }
+      ]
+    }
+  },
+  "jsonrpc": "2.0",
+  "id": 1
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialized-notification.json

@@ -0,0 +1,5 @@
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-request.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "web_search_exa",
+    "arguments": {
+      "query": "site:github.com \"useless\" \"stars\" \"forks\" repository useless",
+      "numResults": 10
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331.md

@@ -0,0 +1,178 @@
+# 관찰 로그 03 - exa / `web_search_exa`
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다.
+
+## 헤더 및 실행 메타데이터
+
+| 항목 | 원본 기록 값 |
+|---|---|
+| transport type | `mcp-http` |
+| request_id | `5720da6c-68cc-44f3-8a1f-73088bddc23d` |
+| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` |
+| Tool version | `2.0` |
+| 실행 시각 | 2026-07-13 16:53:31 UTC |
+| 결과 | ok · 2070ms · truncated=False |
+| JSON-RPC 프레임 수 | 5 |
+| lifecycle | `initialize → notifications/initialized → tools/call` |
+
+### HTTP 헤더 기록 범위
+
+원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다.
+
+원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다.
+
+## JSON-RPC 통신 전문
+
+아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다.
+
+```text
+16:53:31 요청 → initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"method": "initialize",
+"params": {
+"protocolVersion": "2025-06-18",
+"capabilities": {},
+"clientInfo": {
+"name": "toolbox-executor",
+"version": "0.1.0"
+}
+}
+}
+16:53:31 ← 응답 initialize
+{
+"result": {
+"protocolVersion": "2025-06-18",
+"capabilities": {
+"tools": {
+"listChanged": true
+},
+"prompts": {
+"listChanged": true
+},
+"resources": {
+"listChanged": true
+}
+},
+"serverInfo": {
+"name": "exa-search-server",
+"title": "Exa",
+"version": "3.2.1",
+"websiteUrl": "<https://exa.ai>",
+"icons": [
+{
+"src": "<https://exa.ai/images/favicon-32x32.png>",
+"mimeType": "image/png",
+"sizes": [
+"32x32"
+]
+}
+]
+}
+},
+"jsonrpc": "2.0",
+"id": 1
+}
+16:53:31 요청 → notifications/initialized
+{
+"jsonrpc": "2.0",
+"method": "notifications/initialized"
+}
+16:53:31 요청 → tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"method": "tools/call",
+"params": {
+"name": "web_search_exa",
+"arguments": {
+"query": "site:github.com \"useless\" \"stars\" \"forks\" repository useless",
+"numResults": 10.0
+}
+}
+}
+16:53:33 ← 응답 tools/call
+{
+"result": {
+"content": [
+{
+"type": "text",
+"text": "Title: gianmarco-mameli/uselessrepo\nURL: <https://github.com/gianmarco-mameli/usele
+ssrepo\nPublished:> 2023-04-17T12:26:41.000Z\nAuthor: N/A\nHighlights:\n# Repository: gianmarco-mamel
+i/uselessrepo\n...\nThis useless repo is created for versioning a version\n...\n- Stars: 3\n- Forks:
+2\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 2023-04-17T12:26:41Z\n- Last p
+ush: 2025-05-09T07:38:26Z\n- Contributors: 3 (top: gianmarco-mameli, s0ys4uc3, CrownKingClown)\n...\n
+# uselessrepo\n...\nThis useless repo is created for versioning a version\n\n---\n\nTitle: tinkerhub/
+useless_project_temp\nURL: <https://github.com/tinkerhub/useless_project_temp\nPublished:> N/A\nAutho
+r: N/A\nHighlights:\n# tinkerhub/useless_project_temp\n...\n- Stars: 15\n- Forks: 854\n- Watchers: 15
+\n- Open issues: 42\n- Default branch: main\n- Created: 2024-10-23T10:26:22Z\n\n---\n\nTitle: btahir/
+uselesshooks\nURL: <https://github.com/btahir/uselesshooks\nPublished:> N/A\nAuthor: N/A\nHighlight
+s:\n# btahir/uselesshooks\n...\nA Collection of U\n...\ness React Hooks to impress your coworkers
+\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Open issues: 3\n- License: MIT License\n- Default
+branch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\nTitle: dorktoast/turd\nURL: <https://github.c
+om/dorktoast/turd\nPublished:> N/A\nAuthor: N/A\nHighlights:\nThe Useless Repo (Duh)\n...\n- Stars: 2
+\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: master\n- Created: 2023-08-22T08:54:
+42Z\n\n##\n...\n# TURD: The Useless Repo (Duh)\n...\nThis is the most useless repo on github. Inside
+this repo you will find scripts that make your soul hurt.\n\n---\n\nTitle: elierotenberg/useless\nUR
+L: <https://github.com/elierotenberg/useless\nPublished:> 2020-05-10T09:53:12.000Z\nAuthor: N/A\nHigh
+lights:\n# Repository: elierotenberg/useless\n...\nUseless React hooks\n...\n- Stars: 33\n- Forks: 1
+\n- Watchers: 1\n- Open issues: 6\n- Primary language: TypeScript\n- Languages: TypeScript (68.7%), J
+avaScript (31.3%)\n- Default branch: master\n- Created: 2020-05-10T09:53:12Z\n- Last push: 2022-03-26
+T16:38:59Z\n- Contributors: 1 (top: elierotenberg)\n...\nThis is a library of useless hooks for commo
+n non-use-cases.\n\n---\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of software
+that serve no purpose other than waste your time. Forking is encouraged!\nURL: <https://github.com/ni
+ltok64/the-useless-collection\nPublished:> 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\nG
+itHub - niltok64/the-useless-collection: A collection of software that serve no purpose other than wa
+ste your time. Forking is encouraged!\n[Skip to content](#start-of-content)\n## Navigation Menu\nTogg
+le navigation\n...\n](<https://github>.\n...\n/\n**\n[the-useless-collection](<https://github.com/nil
+tok64/the-useless-collection>)\n**\nPublic\n* [Notifications\n](<https://github.com/login?return_to=/
+niltok64/the-useless-collection>) You must be signed in to change notification settings\n* [Fork\n0
+\n...\n](<https://github.com/login?return_to=/niltok64/the-useless-collection>)\n*\n...\n[\nStar\n1
+\n](<https://github.com/login?return_to=/niltok64/the-useless-collection>)\n*\nA collection of softwa
+re that serve no purpose other than waste your time. Forking is encouraged!\n[niltok64.github.io/the-
+useless-collection/](<https://niltok64.github.io/the-useless-collection/>)\n### License\n...\nstar\n]
+(<https://github.com/niltok64/the-useless-collection/stargazers>) [\n0\n...\nforks\n](<https://githu
+b.com/niltok64/the-useless-collection/forks>) [\nBranches\n](<https://github.com/niltok64/the-useless
+-collection/branches>) [\nTags\n](<https://github.com/niltok64/the-useless-collection/tags>) [\nActiv
+ity\n](<https://github.com/niltok64/the-useless-collection/activity>)\n[\n...\nA collection of softwa
+re that serve no purpose other than waste your time. Forking is encouraged!\n...\nRequires Python 3.9
+for building.\n## Usage\n...\nTo use on Unix-based systems run \"pyinstaller main.\n...\n--onefile
+\"\n...\nline in any of the folders. You can also use the executables in\n...\n`automated-build/` fol
+der to build all the programs at once.\n## About\nA collection of software that serve no purpose othe
+r than waste your time. Forking is encouraged!\n[niltok64.github.io/the-useless-collection/](<http
+s://niltok64.github.io/the-useless-collection/>)\n...\nuseless-collection/activity)\n...\n[\n**1**\ns
+tar\n](<https://github.com/niltok64/the-useless-collection/stargazers>)\n### Watchers\n...\n[\n**1**
+\n...\ncom/niltok64/the-useless-collection/watchers)\n...\n[\n**0**\nforks\n](<https://github.com/nil
+tok64/the-useless-collection/forks>)\n[\n\n---\n\nTitle: erikvorhes/Useless-JS\nURL: <https://github.
+com/erikvorhes/Useless-JS\nPublished:> N/A\nAuthor: N/A\nHighlights:\n# erikvorhes/Useless-JS\n...\nS
+cripts that do nothing or overcomplicate things.\n...\n- Stars: 8\n- Forks: 3\n- Watchers: 8\n- Open
+issues: 1\n- License: Do What The F*ck You Want To Public License\n- Default branch: master\n- Create
+d: 2011-08-19T14:09:26Z\n\n##\n...\n# Useless JS\n...\nThis is a collection of scripts that don't rea
+lly do anything useful.\n...\nI've created a couple script files to get us started. Please add your o
+wn!\n\n---\n\nTitle: stac47/libuseless\nURL: <https://github.com/stac47/libuseless\nPublished:> N/A\n
+Author: stac47\nHighlights:\n# stac47/libuseless\n...\nThe most useless C++ library in the world
+\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issues: 0\n- License: GNU General Public License
+v3.0\n- Default branch: main\n- Created: 2021-01-29T13:34:01Z\n...\nThe most useless C++ library in t
+he world\n\n---\n\nTitle: jeku/useless\nURL: <https://github.com/jeku/useless\nPublished:> 2012-08-02
+T14:05:01.000Z\nAuthor: jeku\nHighlights:\n# Repository: jeku/useless\n\nquite useless\n...\n- Stars:
+1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: master\n- Created: 2012-08-02T14:0
+5:01Z\n- Last push: 2012-08-02T14:05:01Z\n- Contributors: 1 (top: jeku)\n\n---\n\nTitle: barelyhuman/
+useless\nURL: <https://github.com/barelyhuman/useless\nPublished:> N/A\nAuthor: N/A\nHighlights:\n# b
+arelyhuman/useless\n...\nA set of useless utilities for javascript\n...\n- Stars: 6\n- Forks: 0\n- Wa
+tchers: 6\n- Open issues: 0\n- License: MIT License\n- Default branch: dev\n- Created: 2022-04-14T08:
+52:31Z\n\n## Languages\n...\n## README\n\n \n \n A set of useless utilities for javascript \n\n## Doc
+umentation\n...\nalready exist somewhere\n...\nand I'm just writing\n...\nto feel good about having m
+y own set of utilties.",
+"_meta": {
+"searchTime": 1216.7
+}
+}
+]
+},
+"jsonrpc": "2.0",
+"id": 3
+}
+```

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-response.json

@@ -0,0 +1,27 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "tools": {
+        "listChanged": true
+      },
+      "prompts": {
+        "listChanged": true
+      },
+      "resources": {
+        "listChanged": true
+      },
+      "logging": {}
+    },
+    "serverInfo": {
+      "name": "searchapi",
+      "title": "SearchAPI MCP Server",
+      "version": "1.0.0",
+      "websiteUrl": "<https://www.searchapi.io>"
+    },
+    "instructions": "Use the available tools to get real-time search results. Each tool corresponds to a specific use case, which may be a full search engine or a specialized feature of an engine."
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-request.json

@@ -0,0 +1,13 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "youtube_search",
+    "arguments": {
+      "q": "EBS 공식 유튜브 채널",
+      "gl": "KR"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-response-visible-transcript.txt

@@ -0,0 +1,12 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\n \"search_metadata\": {\n \"id\": \"search_Z18NJlvnOYI636jLXk3BOm7g\",\n \"status\": \"Success\",\n \"created_at\": \"2026-07-13T17:02:43Z\",\n \"request_time_taken\": 1.12,\n \"parsing_time_taken\": 0.04,\n \"total_time_taken\": 1.15,\n \"request_url\": \"<https://www.youtube.com/results?search_query=EBS+%EA%B3%B5%EC%8B%9D+%EC%9C%A0%ED%8A%9C%EB%B8%8C+%EC%B1%84%EB%84%90&gl=KR&hl=en\>"
+      }
+    ]
+  }
+}

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search.md

@@ -0,0 +1,174 @@
+# 관찰 로그 04 - searchapi / `youtube_search`
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다.
+
+## 헤더 및 실행 메타데이터
+
+| 항목 | 원본 기록 값 |
+|---|---|
+| transport type | `mcp-http` |
+| request_id | `2ab618c9-8f2f-4163-ad11-d7118bc4d3ae` |
+| tool_uid | `28553975-d471-4b67-a210-61cc636d537d` |
+| Tool version | `2.0` |
+| 실행 시각 | 2026-07-13 17:02:42 UTC |
+| 결과 | ok · 2200ms · truncated=False |
+| JSON-RPC 프레임 수 | 4 |
+| lifecycle | `initialize → tools/call` |
+
+### HTTP 헤더 기록 범위
+
+원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다.
+
+원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다.
+
+## JSON-RPC 통신 전문
+
+아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다.
+
+> 원본 PDF 자체가 `tools/call` 성공 응답의 끝부분을 `[+22537B]>`로 접어 표시한다. 따라서 이 문서는 PDF에 표시된 전문을 보존한 것이며, 접힌 22,537바이트의 원본 응답 데이터를 복원한 것은 아니다.
+
+```text
+17:02:42 요청 → initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"method": "initialize",
+"params": {
+"protocolVersion": "2025-06-18",
+"capabilities": {},
+"clientInfo": {
+"name": "toolbox-executor",
+"version": "0.1.0"
+}
+}
+}
+17:02:42 ← 응답 initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"result": {
+"protocolVersion": "2025-06-18",
+"capabilities": {
+"tools": {
+"listChanged": true
+},
+"prompts": {
+"listChanged": true
+},
+"resources": {
+"listChanged": true
+},
+"logging": {}
+},
+"serverInfo": {
+"name": "searchapi",
+"title": "SearchAPI MCP Server",
+"version": "1.0.0",
+"websiteUrl": "<https://www.searchapi.io>"
+},
+"instructions": "Use the available tools to get real-time search results. Each tool corresponds t
+o a specific use case, which may be a full search engine or a specialized feature of an engine."
+}
+}
+17:02:42 요청 → tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"method": "tools/call",
+"params": {
+"name": "youtube_search",
+"arguments": {
+"q": "EBS 공식 유튜브 채널",
+"gl": "KR"
+}
+}
+}
+17:02:44 ← 응답 tools/call
+{"jsonrpc": "2.0", "id": 3, "result": {"content": [{"type": "text", "text": "{\n \"search_metadata
+\": {\n \"id\": \"search_Z18NJlvnOYI636jLXk3BOm7g\",\n \"status\": \"Success\",\n \"created_
+at\": \"2026-07-13T17:02:43Z\",\n \"request_time_taken\": 1.12,\n \"parsing_time_taken\": 0.0
+4,\n \"total_time_taken\": 1.15,\n \"request_url\": \"<https://www.youtube.com/results?search_q
+uery=EBS+%EA%B3%B5%EC%8B%9D+%EC%9C%A0%ED%8A%9C%EB%B8%8C+%EC%B1%84%EB%84%90&gl=KR&hl=en\>",\n \"htm
+l_url\": \"<https://www.searchapi.io/api/v1/searches/search_Z18NJlvnOYI636jLXk3BOm7g.html\>",\n
+\"json_url\": \"<https://www.searchapi.io/api/v1/searches/search_Z18NJlvnOYI636jLXk3BOm7g\>"\n },\n
+\"search_parameters\": {\n \"engine\": \"youtube\",\n \"q\": \"EBS 공식 유튜브 채널\",\n \"hl
+\": \"en\",\n \"gl\": \"KR\"\n },\n \"search_information\": {\n \"total_results\": 6938629\n
+},\n \"channels\": [\n {\n \"position\": 1,\n \"id\": \"UCFCtZJTuJhE18k8IXwmXTYQ\",\n
+\"title\": \"EBS Documentary\",\n \"link\": \"<https://www.youtube.com/@EBSDocumentary\>",\n
+\"description\": \"EBS offers a wide range of high-quality documentaries\\ndealing with subjects, suc
+h as knowledge, science, culture and others.\",\n \"is_verified\": true,\n \"subscribers\":
+5410000.0,\n \"thumbnail\": {\n \"static\": \"<https://yt3.ggpht.com/JCoc_tttfLn5nzycdjiS
+Fwv0gg-AKMIU2pyLw_13CzftUAchPNt4pJ8sHymyp_PcpF9KqSH-yIQ=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"r
+ich\": \"<https://yt3.ggpht.com/JCoc_tttfLn5nzycdjiSFwv0gg-AKMIU2pyLw_13CzftUAchPNt4pJ8sHymyp_PcpF9Kq
+SH-yIQ=s176-c-k-c0x00ffffff-no-rj-mo\>"\n }\n },\n {\n \"position\": 2,\n \"id
+\": \"UC-swf20n5xdKW0waeLpXPFQ\",\n \"title\": \"EBS\",\n \"link\": \"<https://www.youtube.
+com/@EBS_story\>",\n \"description\": \"EBS 공식 유튜브 채널 EBS 입니다. 언제나 여러분 곁엔 EBS가 그리
+고 언제나 EBS 곁엔 여러분이!\",\n \"subscribers\": 698000,\n \"thumbnail\": {\n \"stati
+c\": \"<https://yt3.ggpht.com/k1Z1iQQcdGXiByVcoCCGEwQtx803bSIMOhDOEmLwAexwVmkd6EeZNg__BcDIZ8B_5-jURP_
+9bg=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.ggpht.com/k1Z1iQQcdGXiByVcoCCG
+EwQtx803bSIMOhDOEmLwAexwVmkd6EeZNg__BcDIZ8B_5-jURP_9bg=s176-c-k-c0x00ffffff-no-rj-mo\>"\n }\n
+},\n {\n \"position\": 4,\n \"id\": \"UCNjQBiTSdoj2tCQLBGXFksw\",\n \"title\": \"EB
+S 라디오 공식 채널\",\n \"link\": \"<https://www.youtube.com/@ebsradio\>",\n \"description\":
+\"책 읽어주는 라디오 + 외국어 라디오 (서울 수도권 104.5MHz) 한국교육방송 EBS 라디오 공식 운영 채널 입니다.\",\n
+\"subscribers\": 208000,\n \"thumbnail\": {\n \"static\": \"<https://yt3.googleuserconten
+t.com/ytc/AIdro_kWu2E5kc1Es_euuO3CNfx6R3-JBcB-eLaX1tAEd20yGew=s88-c-k-c0x00ffffff-no-rj-mo\>",\n
+\"rich\": \"<https://yt3.googleusercontent.com/ytc/AIdro_kWu2E5kc1Es_euuO3CNfx6R3-JBcB-eLaX1tAEd20yGe
+w=s176-c-k-c0x00ffffff-no-rj-mo\>"\n }\n },\n {\n \"position\": 6,\n \"id\": \"U
+CL44YGs2BXxtM4GZRH-wnrQ\",\n \"title\": \"EBS 지식채널e\",\n \"link\": \"<https://www.youtub
+e.com/@ebs_jisike\>",\n \"description\": \"우리 삶 속에서 잠깐, 5분 의미있는 순간으로 만드는 채널 공유하
+고 쌓여가는 지식 지식채널e 공식홈페이지 ...\",\n \"subscribers\": 147000,\n \"thumbnail\": {\n
+\"static\": \"<https://yt3.ggpht.com/_nK3ujZE56iSp3jf35MUMgCXIlFY9Gshi7VdHxNBoUNvT-8Jv1IgsGBlf3yNfR7J
+Qr-TxBScfg=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.ggpht.com/_nK3ujZE56iSp
+3jf35MUMgCXIlFY9Gshi7VdHxNBoUNvT-8Jv1IgsGBlf3yNfR7JQr-TxBScfg=s176-c-k-c0x00ffffff-no-rj-mo\>"\n
+}\n },\n {\n \"position\": 8,\n \"id\": \"UCiFYUP4_TI70yCkkVJAlxoA\",\n \"title
+\": \"EBS Collection - Nature\",\n \"link\": \"<https://www.youtube.com/@ebs.science\>",\n
+\"description\": \"Chosen among more than 310,000 digitalized sources from EBS archive, EBS Collectio
+n gives you exclusive access to intriguing ...\",\n \"subscribers\": 1340000.0,\n \"thumbna
+il\": {\n \"static\": \"<https://yt3.googleusercontent.com/ytc/AIdro_m_xD2UFIA7qn07UeYtPAly1eP
+mRdspeKkwIqhgdLjflwM=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.googleusercon
+tent.com/ytc/AIdro_m_xD2UFIA7qn07UeYtPAly1ePmRdspeKkwIqhgdLjflwM=s176-c-k-c0x00ffffff-no-rj-mo\>"\n
+}\n },\n {\n \"position\": 9,\n \"id\": \"UCl_tB4AqPkkxuYcJQHz6dMw\",\n \"title
+\": \"EBSCulture (EBS 교양)\",\n \"link\": \"<https://www.youtube.com/@EBSCulture\>",\n \"d
+escription\": \"Knowledge and information are becoming more important in all areas of today's societ
+y. EBS provides the information to make ...\",\n \"is_verified\": true,\n \"subscribers\":
+3020000.0,\n \"thumbnail\": {\n \"static\": \"<https://yt3.googleusercontent.com/ytc/AIdr
+o_nRo84wHIX9NhlqcW4f8Z4XptXjuHQD-xp3U_Dibgvxpn4=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\":
+\"<https://yt3.googleusercontent.com/ytc/AIdro_nRo84wHIX9NhlqcW4f8Z4XptXjuHQD-xp3U_Dibgvxpn4=s176-c-k
+-c0x00ffffff-no-rj-mo\>"\n }\n },\n {\n \"position\": 10,\n \"id\": \"UCbeZPOz8u
+aHstEIbkqBOnGg\",\n \"title\": \"EBS 세계테마기행\",\n \"link\": \"<https://www.youtube.com/@
+ebstheme\>",\n \"description\": \"EBS 세계테마기행 공식 유튜브 채널 : <https://bit.ly/WorldTravel_EB
+S> (구독하기) ⛵세계를 여행하며 만나는 다양한 문화와 풍경!\",\n \"subscribers\": 162000,\n \"thumb
+nail\": {\n \"static\": \"<https://yt3.ggpht.com/s9JbLvTmFQuY-jP9R_2uRdkWz_YgEK3LYGLa5mdgldqhW
+npGrLJMVJCgQOL_VCfBqb-T7_IWgA=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.ggph
+t.com/s9JbLvTmFQuY-jP9R_2uRdkWz_YgEK3LYGLa5mdgldqhWnpGrLJMVJCgQOL_VCfBqb-T7_IWgA=s176-c-k-c0x00ffffff
+-no-rj-mo\>"\n }\n },\n {\n \"position\": 11,\n \"id\": \"UCuuA38hvvuipqXFIP3BfL
+EA\",\n \"title\": \"EBS 지식\",\n \"link\": \"<https://www.youtube.com/@EBSKnowledge\>",\n
+\"description\": \"일상 속 지식 한 스푼! 각 분야의 전문가로 구성된 연사들의 강연까지! EBS의 고품격 지식·강연 프로
+그램 속 다양한 지식들을 큐레이팅 ...\",\n \"subscribers\": 298000,\n \"thumbnail\": {\n
+\"static\": \"<https://yt3.ggpht.com/E2hBI06f7Y9cWzG5EcQOzPGtLmhj_2IH3AGcqdTj4OI7Jiz8dUwtQOZyHA5kqIbG
+cxw9hr08dQ=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.ggpht.com/E2hBI06f7Y9cW
+zG5EcQOzPGtLmhj_2IH3AGcqdTj4OI7Jiz8dUwtQOZyHA5kqIbGcxw9hr08dQ=s176-c-k-c0x00ffffff-no-rj-mo\>"\n
+}\n },\n {\n \"position\": 13,\n \"id\": \"UC2dDb6up1sIc-5geTvNtgHA\",\n \"title
+\": \"EBS 최고의 요리비결\",\n \"link\": \"<https://www.youtube.com/@EBS_best.cooking.secrets
+\>",\n \"description\": \"이 채널은 \\\"EBS 최고의 요리비결\\\" 공식 유튜브 채널입니다. EBS 최고의 요리비
+결은 지난 20년 동안 요리의 대가들이 출연하여 누구나 ...\",\n \"subscribers\": 104000,\n \"thumbnai
+l\": {\n \"static\": \"<https://yt3.googleusercontent.com/ytc/AIdro_mpiFqITW0McZ_0lY7r80ltEfM3
+hz5srioAQjdI0Jxizw=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich\": \"<https://yt3.googleuserconte
+nt.com/ytc/AIdro_mpiFqITW0McZ_0lY7r80ltEfM3hz5srioAQjdI0Jxizw=s176-c-k-c0x00ffffff-no-rj-mo\>"\n
+}\n },\n {\n \"position\": 14,\n \"id\": \"UC2DBKKki_gtyrrgT7HYU1CA\",\n \"title
+\": \"EBS 국제다큐영화제 공식 채널\",\n \"link\": \"<https://www.youtube.com/@EIDFOFFICIAL\>",\n
+\"description\": \"EBS국제다큐영화제 EIDF 공식 Youtube 채널입니다. This is the official YouTube EIDF Chan
+nel.\",\n \"subscribers\": 10100.0,\n \"thumbnail\": {\n \"static\": \"<https://yt3.
+googleusercontent.com/ytc/AIdro_nglXasX2K52bUhcEmGgttfBh7no_eQcDperw-a5E8sJ6U=s88-c-k-c0x00ffffff-no-
+rj-mo\>",\n \"rich\": \"<https://yt3.googleusercontent.com/ytc/AIdro_nglXasX2K52bUhcEmGgttfBh7
+no_eQcDperw-a5E8sJ6U=s176-c-k-c0x00ffffff-no-rj-mo\>"\n }\n },\n {\n \"position\": 1
+5,\n \"id\": \"UCN3RfsR18gsH8PLI6R6PYSQ\",\n \"title\": \"EBS뉴스\",\n \"link\": \"<ht
+tps://www.youtube.com/@EBSNewsG\>",\n \"description\": \"한국교육방송공사 EBS 뉴스 채널입니다. EBS 뉴
+스의 TV 방송시간은 월~금 낮 12시, 저녁 6시 10분입니다. Republic of Korea's ...\",\n \"subscribers\": 5
+9900.0,\n \"thumbnail\": {\n \"static\": \"<https://yt3.ggpht.com/J5dpRSp4ROHG5T0zUdZPvl2
+SrNXUyObe68rfiVid5i6XnN7zF43M36qekBESigoXqhN-hoA9dA=s88-c-k-c0x00ffffff-no-rj-mo\>",\n \"rich
+\": \"<https://yt3.ggpht.com/J5dpRSp4ROHG5T0zUdZPvl2SrNXUyObe68rfiVid5i6XnN7zF43M36qekBESigoXqhN-ho…
+[+22537B]>
+```

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "toolbox-executor",
+      "version": "0.1.0"
+    }
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-response.json

@@ -0,0 +1,30 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {
+      "experimental": {},
+      "logging": {},
+      "prompts": {
+        "listChanged": true
+      },
+      "resources": {
+        "subscribe": false,
+        "listChanged": true
+      },
+      "tools": {
+        "listChanged": true
+      },
+      "extensions": {
+        "io.modelcontextprotocol/ui": {}
+      }
+    },
+    "serverInfo": {
+      "name": "langconnect-rag-mcp",
+      "version": "3.3.1"
+    },
+    "instructions": "This server provides RAG tools over document collections. Call list_collections() first: it returns collections you can access plus per-collection role and allowed_tools (derived from RBAC scopes). Use search_documents/search_documents_batch/search_documents_with_context for retrieval. Use list_documents to inspect documents. Use add_document_text to add text. Use delete_document/delete_collection only when allowed_tools includes them. Call get_user_info() to get the current user's email and display name."
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialized-notification.json

@@ -0,0 +1,5 @@
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-request.json

@@ -0,0 +1,10 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "list_collections",
+    "arguments": {}
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-response.json

@@ -0,0 +1,40 @@
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"data\":[{\"name\":\"test\",\"id\":\"1caf198a-444b-4a89-a235-23e82bc3d68a\",\"metadata\":{\"description\":\"col\"},\"role\":0,\"allowed_tools\":[\"add_document_text\",\"delete_collection\",\"delete_document\",\"list_documents\",\"search_documents\",\"search_documents_batch\",\"search_documents_with_context\"],\"document_count\":2,\"chunk_count\":119}],\"success\":true,\"error\":null,\"request_id\":\"b3fa0787-dce3-449b-aff0-51a8d882e81d\"}"
+      }
+    ],
+    "structuredContent": {
+      "data": [
+        {
+          "name": "test",
+          "id": "1caf198a-444b-4a89-a235-23e82bc3d68a",
+          "metadata": {
+            "description": "col"
+          },
+          "role": 0,
+          "allowed_tools": [
+            "add_document_text",
+            "delete_collection",
+            "delete_document",
+            "list_documents",
+            "search_documents",
+            "search_documents_batch",
+            "search_documents_with_context"
+          ],
+          "document_count": 2,
+          "chunk_count": 119
+        }
+      ],
+      "success": true,
+      "error": null,
+      "request_id": "b3fa0787-dce3-449b-aff0-51a8d882e81d"
+    },
+    "isError": false
+  }
+}
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections.md

@@ -0,0 +1,140 @@
+# 관찰 로그 05 - langconnect / `list_collections`
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다.
+
+## 헤더 및 실행 메타데이터
+
+| 항목 | 원본 기록 값 |
+|---|---|
+| transport type | `mcp-http` |
+| request_id | `ac3d3c06-882e-4416-be34-a20c5f91662f` |
+| tool_uid | `636e8cd0-3114-467f-b305-14e2c9cda744` |
+| Tool version | `1.0` |
+| 실행 시각 | 2026-07-13 17:08:46 UTC |
+| 결과 | ok · 346ms · truncated=False |
+| JSON-RPC 프레임 수 | 5 |
+| lifecycle | `initialize → notifications/initialized → tools/call` |
+
+### HTTP 헤더 기록 범위
+
+원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다.
+
+원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다.
+
+## JSON-RPC 통신 전문
+
+아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다.
+
+```text
+17:08:46 요청 → initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"method": "initialize",
+"params": {
+"protocolVersion": "2025-06-18",
+"capabilities": {},
+"clientInfo": {
+"name": "toolbox-executor",
+"version": "0.1.0"
+}
+}
+}
+17:08:46 ← 응답 initialize
+{
+"jsonrpc": "2.0",
+"id": 1,
+"result": {
+"protocolVersion": "2025-06-18",
+"capabilities": {
+"experimental": {},
+"logging": {},
+"prompts": {
+"listChanged": true
+},
+"resources": {
+"subscribe": false,
+"listChanged": true
+},
+"tools": {
+"listChanged": true
+},
+"extensions": {
+"io.modelcontextprotocol/ui": {}
+}
+},
+"serverInfo": {
+"name": "langconnect-rag-mcp",
+"version": "3.3.1"
+},
+"instructions": "This server provides RAG tools over document collections. Call list_collections
+() first: it returns collections you can access plus per-collection role and allowed_tools (derived f
+rom RBAC scopes). Use search_documents/search_documents_batch/search_documents_with_context for retri
+eval. Use list_documents to inspect documents. Use add_document_text to add text. Use delete_documen
+t/delete_collection only when allowed_tools includes them. Call get_user_info() to get the current us
+er's email and display name."
+}
+}
+17:08:46 요청 → notifications/initialized
+{
+"jsonrpc": "2.0",
+"method": "notifications/initialized"
+}
+17:08:46 요청 → tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"method": "tools/call",
+"params": {
+"name": "list_collections",
+"arguments": {}
+}
+}
+17:08:47 ← 응답 tools/call
+{
+"jsonrpc": "2.0",
+"id": 3,
+"result": {
+"content": [
+{
+"type": "text",
+"text": "{\"data\":[{\"name\":\"test\",\"id\":\"1caf198a-444b-4a89-a235-23e82bc3d68a\",\"meta
+data\":{\"description\":\"col\"},\"role\":0,\"allowed_tools\":[\"add_document_text\",\"delete_collect
+ion\",\"delete_document\",\"list_documents\",\"search_documents\",\"search_documents_batch\",\"search
+_documents_with_context\"],\"document_count\":2,\"chunk_count\":119}],\"success\":true,\"error\":nul
+l,\"request_id\":\"b3fa0787-dce3-449b-aff0-51a8d882e81d\"}"
+}
+],
+"structuredContent": {
+"data": [
+{
+"name": "test",
+"id": "1caf198a-444b-4a89-a235-23e82bc3d68a",
+"metadata": {
+"description": "col"
+},
+"role": 0,
+"allowed_tools": [
+"add_document_text",
+"delete_collection",
+"delete_document",
+"list_documents",
+"search_documents",
+"search_documents_batch",
+"search_documents_with_context"
+],
+"document_count": 2,
+"chunk_count": 119
+}
+],
+"success": true,
+"error": null,
+"request_id": "b3fa0787-dce3-449b-aff0-51a8d882e81d"
+},
+"isError": false
+}
+}
+```
+

docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/README.md

@@ -0,0 +1,30 @@
+# Agent Builder Tool 호출 관찰 로그
+
+- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf`
+- 원본 생성 시각: 2026-07-13 17:10:33 UTC
+- 목적: Agent Builder 솔루션이 실제 Tool을 호출하며 남긴 JSON-RPC 흐름을 샘플별로 보존
+- 성격: 관찰 기록. 현재 구현 계약, 목표 계약 또는 자동화 테스트 fixture로 사용하지 않는다.
+
+원본 PDF는 시크릿 및 인증 header를 `[REDACTED]` 처리했다고 명시한다. 개별 HTTP request/response header 자체는 제공하지 않으므로, 각 문서에는 원본에 기록된 실행 메타데이터와 header 기록 범위를 분리해 표시한다.
+
+| # | 서버 | Tool | 시각(UTC) | 프레임 | 결과 | 파일 |
+|---:|---|---|---|---:|---|---|
+| 1 | exa | `web_search_exa` | 16:53:16 | 5 | ok · 1896ms | [01](01-exa-web-search-exa-165316.md) |
+| 2 | exa | `web_search_exa` | 16:53:24 | 5 | ok · 1768ms | [02](02-exa-web-search-exa-165324.md) |
+| 3 | exa | `web_search_exa` | 16:53:31 | 5 | ok · 2070ms | [03](03-exa-web-search-exa-165331.md) |
+| 4 | searchapi | `youtube_search` | 17:02:42 | 4 | ok · 2200ms | [04](04-searchapi-youtube-search.md) |
+| 5 | langconnect | `list_collections` | 17:08:46 | 5 | ok · 346ms | [05](05-langconnect-list-collections.md) |
+
+## JSON 프레임 파일
+
+각 요청과 응답은 아래의 독립 JSON 파일로 분리했다. PDF의 시각적 줄바꿈을 제거한 뒤 JSON 문법 검증을 통과한 프레임만 원래 JSON-RPC 구조로 저장했다.
+
+- [01 Exa](01-exa-web-search-exa-165316-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답
+- [02 Exa](02-exa-web-search-exa-165324-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답
+- [03 Exa](03-exa-web-search-exa-165331-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답
+- [04 SearchAPI](04-searchapi-youtube-search-initialize-request.json): `initialize` 요청·응답, `tools/call` 요청, `tools/call` 응답의 PDF 표시 전사본
+- [05 LangConnect](05-langconnect-list-collections-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답
+
+SearchAPI의 `tools/call` 응답은 원본 PDF가 마지막 22,537바이트를 접어 표시하므로,
+[visible transcript](04-searchapi-youtube-search-tools-call-response-visible-transcript.txt)로 저장했다.
+끝부분이 없는 전사본이므로 실행 가능한 JSON-RPC 응답이나 `.json` fixture로 취급하지 않는다.

docs/contracts/agent-builder-mcp/protocol-v0.2-agentbuilder.md

@@ -0,0 +1,44 @@
+# Agent Builder-MCP 이전 non-streaming 계약 v0.2
+
+> 상태: v0.3으로 대체됨. 이 문서는 streaming 정책 도입 전 계약 기록이며, 신규 연동에는 사용하지 않는다.
+
+- 상태: Superseded
+- 기준일: 2026-07-16
+- 구현 endpoint: `POST /mcp`
+- JSON-RPC: `2.0`
+- protocolVersion: `2025-11-25`
+
+> 이 문서는 교체된 고정 endpoint 시점의 이력이다. 현재 공개 URL과 path 처리는 [v0.3](protocol-v0.3-streaming-policy.md)과 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)을 따른다.
+
+이 계약은 Agent Builder에서 받은 JSON-RPC/MCP 호출·응답 예시를 현재 stateless MCP 실행 계층에 반영한 범위다. 서버는 `mcp-session-id`를 요청 correlation에만 사용하며 `Mcp-Session-Id`를 발급하거나 세션 상태를 저장하지 않는다.
+
+## 범위와 HTTP 정책
+
+- 이 버전은 non-streaming 요청에 한정한다. 호출 클라이언트는 `Accept: application/json`을 사용한다.
+- 기존 NDJSON streaming 구현과 progress frame은 변경하지 않았다. streaming의 SSE/재개/cancel 계약은 별도 승인 후 반영한다.
+- `Content-Type: application/json` 또는 `application/json-rpc`을 사용한다.
+- `notifications/initialized`는 Agent Builder가 stateless 서버에 대해 생략할 수 있다. 전송될 경우 표준 lifecycle을 수용하고 HTTP `202 Accepted`와 빈 body를 반환한다.
+
+## initialize
+
+Agent Builder는 연결 초기화 시 [요청 예시](examples/agentbuilder-v0.2/initialize-request.json)를 전송한다. 응답은 [응답 예시](examples/agentbuilder-v0.2/initialize-response.json)처럼 `jsonrpc`, `id`, `result.protocolVersion`만 의미 있는 값을 가진다. `serverInfo`와 `capabilities`는 빈 객체다.
+
+서버는 protocol version으로 `2025-11-25`을 반환한다. 현재 `MCP-Protocol-Version` HTTP 헤더의 수신·검증은 범위 밖이다.
+
+## notifications/initialized
+
+초기화 완료 notification의 body는 [예시](examples/agentbuilder-v0.2/initialized-notification.json)와 같다. JSON-RPC notification에는 `id`가 없으며, 서버는 실행 결과 JSON-RPC body를 만들지 않는다. Agent Builder가 stateless 정책으로 notification을 보내지 않아도 Tool 호출은 가능하다.
+
+## tools/list
+
+`tools/list` handler는 계속 제공한다. Agent Builder가 사전 등록한 Tool만 사용할 때는 이 호출을 생략할 수 있다. 현재 pagination과 `listChanged` notification은 제공하지 않는다.
+
+## tools/call
+
+호출 request는 [예시](examples/agentbuilder-v0.2/tools-call-request.json)처럼 `params.name`과 object 형식의 `params.arguments`를 사용한다. version은 Agent Builder가 보내지 않는다. 서버는 Registry에서 같은 name의 활성 version이 정확히 하나일 때만 이를 해소해 실행한다. 두 개 이상이면 임의 version을 선택하지 않고 오류로 처리한다.
+
+성공 응답은 [예시](examples/agentbuilder-v0.2/tools-call-success-response.json)처럼 `content`, 선택적 `structuredContent`, `isError: false`를 반환한다. Tool endpoint 실행·timeout·권한 오류는 [예시](examples/agentbuilder-v0.2/tools-call-execution-error-response.json)처럼 HTTP/JSON-RPC transport error 대신 `result.isError: true`로 반환한다. 잘못된 JSON-RPC envelope, 알 수 없는 method, 잘못된 name/arguments는 기존 JSON-RPC `error`를 사용한다.
+
+## 호환성 메모
+
+- UID execution key 검토안은 [ADR-0005](../../decisions/ADR-0005-standard-tool-name.md)에서 폐기되었다. 신규 계약은 표준 MCP `name`을 실행 식별자로 사용한다.

docs/contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md

@@ -0,0 +1,104 @@
+# Agent Builder-MCP 동기 JSON 계약 v0.3
+
+- 상태: Implemented
+- 기준일: 2026-07-16
+- 공개 endpoint: `POST https://{mcpHost}{publicPath}`
+- 컨테이너 endpoint: 공개 URL과 동일한 `POST {publicPath}`
+- JSON-RPC: `2.0`
+- protocolVersion: `2025-11-25`
+
+이 계약의 현재 구현은 stateless MCP 실행 계층의 transport를 동기 JSON으로 고정한다. 현재 in-memory snapshot의 표준 Tool name metadata를 조회해 확정된 endpoint로 POST하며, `Mcp-Session-Id`는 lifecycle correlation 값일 뿐 서버는 initialize 성공 시 이를 발급하지만 대화·readiness 상태를 저장하지 않는다.
+
+한 환경은 공개 host를 공유하지만 path마다 독립된 MCP Deployment와 Tool Service에 연결된다. Agent Builder는 각 공개 URL을 별도 MCP로 등록하고 initialize한다. URL 사이에는 session ID, Tool 목록, lifecycle 상태를 공유하지 않는다. Route는 path를 바꾸지 않으며 컨테이너가 같은 path를 처리한다. 이 매핑은 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)이 정본이며 JSON-RPC payload에는 영향을 주지 않는다.
+
+## 공개 URL과 route key
+
+배포는 두 형태 중 하나다. 어느 쪽이든 `publicPath`가 Agent Builder 등록 URL의 정본이고, JSON-RPC payload는 route 선택에 관여하지 않는다.
+
+| 형태 | `mcp.endpoint-path` | 호출 URL | route 결정 |
+|---|---|---|---|
+| 고정 endpoint | `/mcp/core`처럼 route 포함 | `POST {publicPath}` | 설정된 path 자체가 route다 |
+| 동적 route | `/mcp` | `POST /mcp/{routeKey}` | URL path segment가 route다 |
+
+동적 route 배포에서 `routeKey`는 Portal registry가 선언한 route를 가리킨다. 다음 경우는 controller에 닿기 전에 JSON-RPC `error`(`-32600` Invalid Request)로 거부한다.
+
+| 상황 | `message` |
+|---|---|
+| Portal 모드인데 `/mcp`처럼 route가 없음 | `route key is required` |
+| route에 `/`가 있거나 `[A-Za-z0-9._-]{1,64}`를 벗어남 | `route key is invalid` |
+| 형식은 맞지만 registry snapshot에 없는 route | `route key is not registered` |
+| 고정 endpoint 배포인데 뒤에 segment를 더 붙임 | `route key is not allowed for fixed endpoint path` |
+
+미등록 route 검사는 in-memory snapshot만 조회하며 요청 경로에서 Portal이나 Redis를 새로 호출하지 않는다. 따라서 Portal 장애 중에도 이미 확보한 route는 계속 응답하고, 존재하지 않는 route는 Tool 실행 계층에 닿지 않는다.
+
+`mcp.portal.route-key` 설정은 선언되어 있으나 현재 구현이 읽지 않는다. route는 URL에서만 결정되며, 설정 기본값으로 보정하면 잘못된 단일 진입점 호출이 조용히 성공하기 때문이다.
+
+## HTTP 선택 정책
+
+- Agent Builder는 `Accept: application/json, text/event-stream`을 보낸다.
+- 서버는 항상 `Content-Type: application/json`과 단일 JSON-RPC response를 반환한다.
+- `Accept`는 수용 가능 형식의 선언이며, `text/event-stream`이 포함되어도 응답 transport를 바꾸지 않는다.
+- 독립적인 server-push SSE channel은 제공하지 않으므로 공개 endpoint의 `GET`은 `405 Method Not Allowed`다.
+- `initialize` 요청에는 `MCP-Protocol-Version` header를 요구하지 않는다.
+- `initialize` 이후 `notifications/initialized`, `tools/list`, `tools/call` 요청에는 정확히 `MCP-Protocol-Version: 2025-11-25`이 필수다. `version` 등 임의 header는 대체하지 않는다. header가 없거나 지원하지 않는 값이면 server는 JSON-RPC body 대신 HTTP `400 Bad Request`와 `error`, `message`, `supportedVersions`, `guid`를 가진 JSON 오류 body를 반환한다.
+
+## 호출자 식별 header
+
+`MCP-Protocol-Version` 외에 Agent Builder가 보내는 header는 다섯 개이며 **모두 선택값**이다.
+
+| header | 형식 | 서버 동작 |
+|---|---|---|
+| `guid` | UUID | 없으면 서버가 생성한다. 응답 header와 오류 body에 되돌려준다 |
+| `x-request-id` | 안전 문자 1~128자 | 없으면 서버가 생성한다. 응답 header에 되돌려준다 |
+| `mcp-session-id` | 안전 문자 1~128자 | initialize lifecycle 상관 값. 서버는 저장하지 않는다 |
+| `employee-no` | 암호화된 사원번호 | 해석하지 않는다 |
+| `virtual-employee-no` | 암호화된 가상사원번호 | 해석하지 않는다 |
+
+사원 식별자 둘은 **불투명 값**이다. MCP는 복호화·검증·저장하지 않고 Tool Service로 그대로 전달한다.
+값의 의미는 보지 않되, 개행이나 공백이 섞여 downstream 요청 header를 조작하는 것은 거부한다
+(출력 가능 문자 1~2048자가 아니면 `-32600`).
+
+암호화된 값이라도 **로그에 남기지 않는다.** 로그에 나가는 상관 값은 `guid`와 `x-request-id`뿐이다.
+
+## initialize와 notification
+
+`initialize`는 [v0.2 요청 예시](examples/agentbuilder-v0.2/initialize-request.json)를 그대로 사용하며, 응답은 [v0.3 응답 예시](examples/agentbuilder-v0.3/initialize-response.json)처럼 원 요청 `id`, `protocolVersion: 2025-11-25`, `serverInfo(name/title/version)`, `capabilities.tools.listChanged: false`를 반환한다. HTTP response header에는 새 UUID `Mcp-Session-Id`가 포함된다. Agent Builder는 응답 version을 이후 모든 HTTP 요청의 `MCP-Protocol-Version` header에 사용하고, session ID를 `notifications/initialized` 및 이후 Tool 요청의 correlation header로 보낸다. MCP 2025-11-25 lifecycle에 따라 Agent Builder는 `notifications/initialized`를 반드시 보내고 두 header를 포함한다. 서버는 notification을 HTTP `202 Accepted`와 빈 body로 수용하되 stateless 원칙상 수신 여부를 저장하거나 이후 요청을 차단하는 readiness gate로 사용하지 않는다.
+
+## tools/list
+
+`tools/list`는 `result.tools`에 현재 snapshot의 공개 Tool 필드(`name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`)를 반환한다. `_meta`의 version, endpoint, HTTP method, timeout, cache 설정은 실행·운영 metadata이므로 MCP 공개 응답에 포함하지 않는다.
+
+현재 `tools/call`은 `structuredContent`를 반환하거나 Tool 응답을 `outputSchema`로 검증하지 않는다. 따라서 `outputSchema`를 가진 Tool 정의를 그대로 노출하는 동작은 현재 코드의 사실이지만 MCP 2025-11-25의 구조화 출력 계약을 완전히 충족하지 않는다. 운영 Tool은 구조화 출력 지원이 도입되기 전까지 `outputSchema`를 생략해야 한다.
+
+원천은 profile이 정한다. local은 Tool Service 매니페스트를 먼저 조회하고 최초 실패 시 `config/local-core-tools-manifest-sample-v1.json` fallback을 사용한다(파일이 곧 목록이므로 여기에 Tool 이름을 옮겨 적지 않는다). 운영은 설정된 Tool Service 매니페스트뿐이다.
+
+## 동기 Tool 호출
+
+기본 Tool 호출은 [요청 예시](examples/agentbuilder-v0.3/tools-call-request.json)처럼 `params.name`과 object `params.arguments`를 사용한다. name은 `tools/list`와 실행 사이의 유일한 식별자다. MCP는 snapshot metadata에서 endpoint를 확정하고 arguments 전체를 JSON body로 전달한다. 성공 및 Tool 실행 실패는 각각 [성공 응답](examples/agentbuilder-v0.3/tools-call-success-response.json), [실행 실패 응답](examples/agentbuilder-v0.3/tools-call-execution-error-response.json)처럼 `application/json` JSON-RPC response로 반환한다.
+
+성공 응답은 Tool의 plain text를 `result.content[0].text`, 소요 시간(ms)을 `result.content[0]._meta.searchTime`, 성공 여부를 `result.isError: false`에 넣는다. JSON object/array 응답은 compact JSON 문자열로 `text`에 보존하며, outer JSON serializer가 올바른 quote escaping을 수행한다. 실행·timeout·권한 실패는 `result.isError: true`이며, JSON-RPC envelope/params/method 오류는 기존 JSON-RPC `error`다. Registry의 `inputSchema`는 모든 `tools/call`에서 Tool 호출 전에 검증한다.
+
+## tools/call 성공·오류 응답 기준
+
+Agent Builder는 HTTP 상태만으로 성공 여부를 판단하지 않고 JSON-RPC body의 최상위 `result` 또는 `error`를 확인해야 한다. 일반적인 JSON-RPC 요청 오류는 HTTP `200 OK`와 함께 최상위 `error`로 반환될 수 있다. `-32602`의 `error.message`는 `Invalid params: <상세 원인>` 형식이며, 예를 들어 필수 `query`가 없으면 `Invalid params: 'query' is required`를 반환한다. 선택적인 `error.data`에는 `guid`와 상세 원인을 추가로 담을 수 있다. 단, `MCP-Protocol-Version` 누락·미지원처럼 HTTP transport 단계에서 거부된 요청은 HTTP `400 Bad Request`다.
+
+| 상황 | HTTP 상태 | JSON-RPC body | `isError` | 현재 구현의 처리 주체 |
+|---|---:|---|---|---|
+| Tool 정상 완료 | 200 | `result.content` | 반드시 `false` | `ToolsCallHandler` |
+| Tool Service timeout, upstream 4xx/5xx, downstream 권한 거부 | 200 | `result.content` | 반드시 `true` | `ToolsCallHandler` |
+| Tool이 실행된 뒤 업무 검증·업무 규칙으로 실패 | 200 | `result.content` | 반드시 `true` | Tool Service 또는 실행 계층 |
+| JSON 문법 오류 | 200 | 최상위 `error` (`-32700`) | 없음 | `McpExceptionHandler` |
+| JSON-RPC envelope 오류 | 200 | 최상위 `error` (`-32600`) | 없음 | `JsonRpcRequestParser` |
+| 알 수 없는 MCP method 또는 Tool | 200 | 최상위 `error` (`-32601` 또는 Tool 조회 오류) | 없음 | method/registry 계층 |
+| `params.name` 누락, `params.arguments` 형식 오류, 공개된 inputSchema의 필수 값 누락 | 200 | 최상위 `error` (`-32602`) | 없음 | Adapter/parameter/schema validator |
+| 서버 설정·Registry 장애 등 서버가 Tool 호출을 시작할 수 없는 경우 | 200 | 최상위 `error` (`-32603` 또는 서버 정의 오류) | 없음 | transport/execute 계층 |
+| `MCP-Protocol-Version` 누락 또는 미지원 | 400 | transport 오류 body | 없음 | `McpProtocolVersionValidator` |
+
+모든 routing은 공통 `name`/`arguments` 형식과 선택된 Tool의 `inputSchema`를 실행 전에 검증한다. Tool Service가 반환한 HTTP 400은 검증을 통과해 Tool 실행을 시작한 뒤의 실패이므로 `result.isError: true`로 반환한다.
+
+실행 가능한 응답 형태는 [성공 예시](examples/agentbuilder-v0.3/tools-call-success-response.json), [Tool 실행 실패 예시](examples/agentbuilder-v0.3/tools-call-execution-error-response.json), [잘못된 인자 예시](examples/agentbuilder-v0.3/tools-call-invalid-params-response.json)를 따른다.
+
+## 호환성 메모
+
+- v0.2의 일반 JSON 요청·응답 형식은 그대로 호환된다.
+- Agent Builder의 기존 `Accept: application/json, text/event-stream` header는 계속 수용한다.

docs/contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md

@@ -0,0 +1,56 @@
+# Agent Builder-MCP 목표 계약 v1 합의 기준선
+
+- 상태: Partial Agreement
+- 합의 기준일: 2026-07-10
+- 목적: 확정된 목표 제약만 기록하고 미확정 payload의 추측 구현을 방지
+
+## Normative 합의 사항
+
+### 책임 경계
+
+- Agent Builder가 Tool을 선택한다.
+- MCP Server는 요청에 명시된 Tool만 검증·실행한다.
+- MCP Server는 stateless하며 `mcp-session-id`를 대화 상태로 사용하지 않는다.
+
+### Tool 노출과 호출 단위
+
+- Agent Builder가 LLM에 노출하는 Tool은 최대 50개다.
+- Agent Builder-MCP 목표 호출은 요청 하나당 Tool 하나다.
+
+### Tool 식별
+
+- 표준 MCP Tool `name`을 `tools/list`와 `tools/call` 사이의 시스템 간 실행 key로 사용한다.
+- Tool Service가 전체 MCP 범위에서 고유한 namespaced name을 선언하고 MCP Server는 이를 재작성하지 않는다.
+- Agent Builder UID는 Agent Builder 내부 관리에만 사용하고 MCP wire contract에 포함하지 않는다.
+
+### 실행 가드레일
+
+- 전체 상호작용 상한은 300초다.
+- MCP Server는 3만 자 기준으로 원문 응답을 임의 절단하지 않는다.
+- idempotency가 확인되지 않은 write/update Tool은 자동 retry하지 않는다.
+
+## 아직 Normative가 아닌 항목
+
+다음 항목은 목표 v1의 일부로 구현하면 안 된다.
+
+- 최종 method 이름 (`tool/call`, `tools/call` 또는 별도 vendor method)
+- 최종 Tool Call parameter와 result field 이름
+- `initialize` 전체 request/response
+- Tool name 변경·폐기 시 rolling 호환 기간과 Agent Builder 내부 mapping lifecycle
+- 사원 식별자 header를 언젠가 필수로 승격할지 여부 (현재 계약에서는 선택값이며 MCP는 검증하지 않는다)
+- HTTP status와 JSON-RPC/업무 error code 매핑
+- read retry 조건과 idempotency key
+- 300초 timeout budget과 cancellation protocol
+- 대용량 response의 최대 크기와 continuation 방식
+- streaming media type과 framing
+
+## 요청·응답 규격 처리 원칙
+
+목표 v1의 확정 JSON 예시는 아직 제공하지 않는다. 미확정 field를 임의로 채운 JSON은 사실상 새로운 계약 결정이 되기 때문이다.
+
+Agent Builder의 전체 payload와 위 미확정 항목이 승인되면 다음 순서로 갱신한다.
+
+1. 이 문서 상태를 `Approved`로 변경한다.
+2. 목표 v1 JSON example과 schema를 추가한다.
+3. 관련 ADR을 추가하거나 기존 ADR의 구현 보류 조건을 해제한다.
+4. 코드와 테스트 변경을 별도 작업으로 수행한다.

docs/contracts/portal-mcp/README.md

@@ -0,0 +1,36 @@
+# Portal-MCP 계약 문서
+
+이 디렉터리는 포털과 MCP Server 사이의 Tool Server registry 조회 계약을 관리한다.
+
+```text
+Portal ──[portal-mcp 계약]──▶ MCP Server ──[tool-service-mcp 계약]──▶ Tool Server
+                                   ▲
+                                   └──[agent-builder-mcp 계약]── Agent Builder
+```
+
+| 문서 | 상태 | 용도 |
+|---|---|---|
+| [protocol-v0.1-registry.md](protocol-v0.1-registry.md) | Implemented | route별 Tool Server 목록 조회 계약. 응답 형태, 필드, 실패 동작, 갱신 주기 |
+
+## 현재 원칙
+
+- 포털은 **route가 무엇이고 그 route에 어떤 Tool Server가 있는가**만 소유한다. `serviceDomain`과 `manifestPath`까지다.
+- Tool 목록과 Tool 실행 endpoint는 포털이 아니라 Tool Server 매니페스트에서 온다([ADR-0010](../../decisions/ADR-0010-tool-service-manifest-owns-execution-endpoint.md)).
+- registry 응답은 그 시점의 전체 상태다. 증분은 없다.
+- 조회 실패는 route 삭제가 아니다. 성공한 registry가 route를 제외했을 때만 제거를 반영한다.
+- route 조회는 서로 독립이지만, 한 route 안에서는 전부 아니면 전무다. 부분 목록으로 snapshot을 만들지 않는다.
+- MCP는 요청 경로에서 포털을 호출하지 않는다. route key 검증도 in-memory snapshot만 본다.
+
+## 관련 문서
+
+- 요청 URL의 route key 규약: [Agent Builder 계약 v0.3](../agent-builder-mcp/protocol-v0.3-streaming-policy.md#공개-url과-route-key)
+- 매니페스트 조회·실행 계약: [Tool Service 계약 v0.2](../tool-service-mcp/protocol-v0.2-bundle-discovery.md)
+
+## 운영 적용 전 확정할 항목
+
+1. 포털 API의 인증 방식과 MCP → 포털 방향 NetworkPolicy
+2. `registryRevision`의 형식과 변경 통지 방식
+3. route 추가·폐기 시 rolling 호환 기간
+4. 저장소 샘플(`config/local-toolserver-info-sample-v1.json`, `deploy/portal-registry.json`)을 이 계약에 맞추는 시점
+
+상세 필드와 장애 처리는 [v0.1 계약](protocol-v0.1-registry.md)을 따른다.

docs/contracts/portal-mcp/protocol-v0.1-registry.md

@@ -0,0 +1,117 @@
+# Portal-MCP Tool Server Registry 계약 v0.1
+
+- 상태: **Implemented** (MCP 서버 측 구현 완료, 포털 측 합의 대기)
+- 기준일: 2026-08-22
+- 조회 위치: `mcp.portal.registry-url` — HTTP(S) Portal API 또는 `file:`/`classpath:` 로컬 리소스
+- 활성 조건: `mcp.portal.enabled=true`
+- 구현: `PortalToolRegistryClient`
+
+## 1. 계약 범위와 원칙
+
+포털은 **route별로 어떤 Tool Server가 있는가**만 알려 준다. Tool 목록과 Tool 실행 주소는 포털이 아니라 각 Tool Server의 매니페스트에서 온다([Tool Service-MCP Bundle 조회 계약 v0.2](../tool-service-mcp/protocol-v0.2-bundle-discovery.md), [ADR-0010](../../decisions/ADR-0010-tool-service-manifest-owns-execution-endpoint.md)).
+
+| 원칙 | 내용 |
+|---|---|
+| MCP가 가져온다 | 포털은 registry를 제공만 한다. MCP에 push하지 않는다 |
+| 포털은 route와 Tool Server만 소유 | `serviceDomain`과 `manifestPath`까지다. Tool 목록·실행 endpoint는 매니페스트가 정한다 |
+| registry는 전체 상태 | 응답은 그 시점 route 전체다. 증분 없음 |
+| route 단위 격리 | 한 route의 manifest 조회 실패가 다른 route의 snapshot을 지우지 않는다 |
+| 요청 경로는 조회하지 않는다 | `tools/list`·`tools/call`과 route key 검증은 in-memory snapshot만 본다 |
+
+## 2. 응답 형태
+
+두 가지를 모두 받는다. `routes`가 배열이면 집계형으로, 아니면 단일 route로 해석한다.
+
+**집계형** — 한 번의 호출로 모든 route를 받는다. 운영에서 사용한다.
+
+```json
+{
+  "registryRevision": "portal-registry-2026-08-22-01",
+  "routes": [
+    {
+      "routeKey": "cus",
+      "toolServices": [
+        {
+          "serviceKey": "was-cus",
+          "serviceDomain": "https://tool-cus.devjun.net",
+          "manifestPath": "/tool-manifest",
+          "namePrefix": "",
+          "status": "ACTIVE"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**단일 route형** — `routes` 없이 최상위에 `routeKey`와 `toolServices`를 둔다.
+
+```json
+{
+  "routeKey": "cus",
+  "toolServices": [ { "serviceKey": "was-cus", "serviceDomain": "https://tool-cus.devjun.net", "manifestPath": "/tool-manifest", "status": "ACTIVE" } ]
+}
+```
+
+## 3. 필드
+
+| 필드 | 위치 | 필수 | MCP 처리 |
+|---|---|---|---|
+| `routes[]` | 최상위 | 선택 | 배열이면 집계형. 없으면 최상위를 단일 route로 읽는다 |
+| `routeKey` | route | **필수** | 정규화 후 route 식별자. 요청 URL `/mcp/{routeKey}`와 대조한다 |
+| `toolServices[]` | route | **필수** | 이 route가 보는 Tool Server 목록 |
+| `serviceKey` | service | **필수** | bundle id로 사용. 매니페스트의 `bundleId`와 일치해야 한다 |
+| `serviceDomain` | service | **필수** | Tool Server 주소. 후행 `/`는 제거한다. 매니페스트의 **상대** endpoint를 절대 URL로 바꾸는 기준이 된다 |
+| `manifestPath` | service | **필수** | 매니페스트 경로. `serviceDomain + manifestPath`가 조회 주소다 |
+| `status` | service | 선택 | 기본 `ACTIVE`. 대소문자 무시하고 `ACTIVE`가 아니면 그 서비스를 건너뛴다 |
+| `namePrefix` | service | 선택 | 기본 `""`. Tool 이름 접두사 검증에 사용한다 |
+| `registryRevision` | 최상위 | 선택 | 변경 진단·로그용. 호출 대상 결정에는 쓰지 않는다 |
+
+**MCP가 읽지 않는 필드가 있다.** 현재 구현은 `executeBasePath`, `displayName`, `toolEndpoints`를 무시한다. 응답에 있어도 오류가 아니지만 동작에 영향을 주지 않으므로, 포털이 이를 근거로 실행 주소를 통제할 수 있다고 가정하면 안 된다.
+
+## 4. 실패 동작
+
+| 상황 | MCP 동작 |
+|---|---|
+| registry 조회 실패 | 이미 확보한 in-memory endpoint 목록 유지. memory가 비어 있으면 `mcp.redis.portal-registry-key`의 Redis fallback을 읽는다 |
+| Redis fallback도 실패 | 원천 미확보로 처리하고 다음 주기에 재시도 |
+| route에 ACTIVE 서비스가 하나도 없음 | `Portal registry has no active Tool Service`로 그 route 조회 실패 |
+| 한 Tool Server의 매니페스트에 사용 가능한 성공본이 없음 | 그 route 전체를 실패 처리. 부분 목록을 채택하지 않는다 |
+| route 간 Tool name 중복 또는 `maxToolsTotal` 초과 | 같은 이유로 실패 처리 |
+| registry에서 사라진 route | 다음 갱신에 in-memory snapshot에서도 제거 |
+
+route 단위 격리와 catalog 교체 규칙은 Tool Service 계약 v0.2 §7과 같은 원칙을 따른다. 조회는 route마다 독립이지만, 한 route 안에서는 전부 아니면 전무다.
+
+## 5. 갱신 주기
+
+- `mcp.portal.refresh-interval-seconds` (기본 300초): 포털 registry만 다시 읽는다.
+- `mcp.registry.refresh-interval-seconds`: 이미 확보한 Tool Server 목록의 매니페스트만 다시 읽는다.
+
+기동 preload는 포털 registry를 먼저 호출한 뒤 매니페스트를 조회한다. 두 주기는 독립이다.
+
+## 6. 로컬 검증
+
+`registry-url`에 `file:` 또는 `classpath:` 리소스를 지정하면 포털 서버 없이 같은 계약으로 읽는다. 이후 매니페스트 조회·route별 snapshot 갱신·Redis fallback 규칙은 HTTP API를 쓸 때와 동일하다.
+
+```yaml
+mcp:
+  portal:
+    enabled: true
+    registry-url: file:./config/local-toolserver-info-sample-v1.json
+    refresh-interval-seconds: 15
+```
+
+## 7. 저장소의 샘플 파일
+
+두 샘플이 있고, 현재 서로 다르다. 이 계약을 정본으로 삼고 맞춰야 한다.
+
+| 파일 | 용도 | 이 계약과의 차이 |
+|---|---|---|
+| `config/local-toolserver-info-sample-v1.json` | 로컬 검증용 | MCP가 읽지 않는 `displayName`을 포함 |
+| `deploy/portal-registry.json` | 배포 참고용 | MCP가 읽지 않는 `executeBasePath`를 포함하고 `registryRevision`이 없다 |
+
+## 8. 열린 항목
+
+- 포털 API의 인증 방식은 이 계약이 정하지 않는다. MCP는 인증·인가를 하지 않으므로([ADR-0006](../../decisions/ADR-0006-no-authentication-in-mcp.md)) 네트워크 경계에서 통제한다.
+- `registryRevision`의 형식을 문자열로 고정할지 정하지 않았다. 현재 구현은 값을 로그·진단에만 쓰므로 형식에 의존하지 않는다.
+- 즉시 refresh 알림: 주기 반영으로 부족하다는 운영 근거가 생길 때 검토한다.

docs/contracts/tool-service-mcp/README.md

@@ -0,0 +1,39 @@
+# Tool Service-MCP 계약 문서
+
+이 디렉터리는 Tool Service와 MCP Server 사이의 metadata 조회·실행 계약을 관리한다.
+
+```text
+Agent Builder ──[agent-builder-mcp 계약]──▶ MCP Server ──[tool-service-mcp 계약]──▶ Tool Service
+```
+
+| 문서 | 상태 | 용도 |
+|---|---|---|
+| [protocol-v0.2-bundle-discovery.md](protocol-v0.2-bundle-discovery.md) | Implemented | Tool Service Bundle의 매니페스트 조회·실행 계약. 구현은 N개 Bundle을 지원하지만 운영 배포는 1개로 고정 |
+| [tool-list-loading-guide.md](tool-list-loading-guide.md) | Guide | Tool 개발 파트가 현재 최초 적재·memory snapshot·`tools/list` 변환 흐름을 이해하기 위한 안내. 규범 내용은 담지 않고 v0.2를 가리킨다 |
+
+push 등록 방식(v0.1)은 채택하지 않았다. 그 이유는
+[v0.2 §2](protocol-v0.2-bundle-discovery.md#2-왜-조회-방식인가-왜-기동-시-1회가-아닌가)에 있다.
+
+## 현재 원칙
+
+- 운영 Tool metadata의 유일한 원천은 각 Tool Service의 매니페스트다.
+- `local` profile은 Tool Service 매니페스트를 먼저 조회하고, 최초 실패 시 `config/local-core-tools-manifest-sample-v1.json` fallback을 사용한다.
+- 표준 MCP `name`이 `tools/list`와 `tools/call`의 실행 식별자다. Agent Builder UID는 이 계약에 포함하지 않는다.
+- Tool Service는 표준 MCP `name`을 선언한다. MCP는 자기 Bundle 안에서 형식·접두사·중복을 검증하며, 서로 다른 MCP 배포 간 전역 유일성은 Tool Service·플랫폼의 변경 절차로 보장한다.
+- MCP는 요청 경로에서 in-memory snapshot만 읽는다. Redis는 선택적인 공유 last-good cache다.
+- 조회 실패는 Tool 삭제가 아니다. 성공한 매니페스트가 Tool을 제외했을 때만 삭제를 반영한다.
+- 불완전한 aggregate, 중복 name, 총량 상한 초과는 현재 snapshot을 교체하지 않는다.
+
+## 예제와 검증
+
+[examples/bundle-v0.2](examples/bundle-v0.2/)의 매니페스트, MCP 설정, Actuator 상태 응답을 계약 테스트가 직접 읽는다.
+예제와 구현은 같은 변경에서 함께 수정한다.
+
+운영 적용 전에 Tool 개발 파트와 다음 항목을 확정한다.
+
+1. MCP → Tool 방향 NetworkPolicy와 매니페스트 인증 방식
+2. Tool name 변경·폐기 시 rolling 호환 기간
+3. `namePrefix`, Tool 수, 매니페스트 크기 상한
+4. Tool Service별 timeout과 권한 scope
+
+상세 필드와 장애 처리는 [v0.2 계약](protocol-v0.2-bundle-discovery.md)을 따른다.

docs/contracts/tool-service-mcp/examples/bundle-v0.2/bundle-status-response.json

@@ -0,0 +1,54 @@
+{
+  "bundles": [
+    {
+      "bundleId": "insurance-processing",
+      "enabled": true,
+      "status": "healthy",
+      "revision": "sha256:9f2c4a17b83e5d06c1f9a2e7b45d8c30ff1a6b92e4c7d5083a1b6e9f2c4d7a850",
+      "toolCount": 2,
+      "consecutiveFailures": 0,
+      "lastSuccessAt": "2026-07-29T02:29:45Z",
+      "lastFailureReason": null
+    },
+    {
+      "bundleId": "insurance-corebanking",
+      "enabled": true,
+      "status": "degraded",
+      "revision": "sha256:1d70e6b4c2a89f35e0b7d4816c3a92f5088b1e7d6a4c93520fb8e1d7a6c40395",
+      "toolCount": 5,
+      "consecutiveFailures": 1,
+      "lastSuccessAt": "2026-07-29T02:29:15Z",
+      "lastFailureReason": "ResourceAccessException"
+    },
+    {
+      "bundleId": "insurance-payment",
+      "enabled": true,
+      "status": "degraded",
+      "revision": "sha256:7e4c81b0f90f4a2c31e7d1086aa9cd31b2f14403e1f0c6633ca2b424e6d4a812",
+      "toolCount": 3,
+      "consecutiveFailures": 4,
+      "lastSuccessAt": "2026-07-29T02:10:00Z",
+      "lastFailureReason": "ResourceAccessException"
+    },
+    {
+      "bundleId": "insurance-claim",
+      "enabled": true,
+      "status": "unreachable",
+      "revision": null,
+      "toolCount": 0,
+      "consecutiveFailures": 2,
+      "lastSuccessAt": null,
+      "lastFailureReason": "IllegalStateException"
+    },
+    {
+      "bundleId": "insurance-channel",
+      "enabled": false,
+      "status": "disabled",
+      "revision": null,
+      "toolCount": 0,
+      "consecutiveFailures": 0,
+      "lastSuccessAt": null,
+      "lastFailureReason": null
+    }
+  ]
+}

docs/contracts/tool-service-mcp/examples/bundle-v0.2/manifest-response.json

@@ -0,0 +1,97 @@
+{
+  "bundleId": "insurance-processing",
+  "revision": "sha256:9f2c4a17b83e5d06c1f9a2e7b45d8c30ff1a6b92e4c7d5083a1b6e9f2c4d7a850",
+  "tools": [
+    {
+      "name": "processing.contract.inquiry",
+      "title": "계약 조회",
+      "description": "계약번호로 계약의 기본 정보를 조회합니다. 사용자가 특정 계약의 상태, 보험료, 계약일을 물어볼 때 사용합니다. 테스트 전용이며 실제 고객 계약 데이터는 처리하지 않습니다.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "contractNo": {
+            "type": "string",
+            "description": "조회할 계약번호입니다.",
+            "minLength": 1
+          }
+        },
+        "required": ["contractNo"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "title": "계약 조회",
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_meta": {
+        "version": "1.2.0",
+        "endpoint": "/mcp/processing.contract.inquiry",
+        "timeoutMillis": 3000,
+        "enabled": true
+      }
+    },
+    {
+      "name": "processing.payment.history",
+      "title": "수납 이력 조회",
+      "description": "계약번호로 수납 이력을 조회합니다. 사용자가 납입 내역이나 미납 여부를 물어볼 때 사용합니다.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "contractNo": {
+            "type": "string",
+            "description": "조회할 계약번호입니다.",
+            "minLength": 1
+          },
+          "months": {
+            "type": "integer",
+            "description": "조회할 최근 개월 수입니다.",
+            "minimum": 1,
+            "maximum": 36
+          }
+        },
+        "required": ["contractNo"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_meta": {
+        "version": "1.0.1",
+        "endpoint": "/mcp/processing.payment.history",
+        "timeoutMillis": 5000,
+        "enabled": true
+      }
+    },
+    {
+      "name": "processing.notice.send",
+      "title": "안내 발송",
+      "description": "계약자에게 안내 메시지를 발송합니다. 사용자가 명시적으로 발송을 요청한 경우에만 사용합니다.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "contractNo": { "type": "string", "minLength": 1 },
+          "template": { "type": "string", "enum": ["PAYMENT_DUE", "CONTRACT_EXPIRY"] }
+        },
+        "required": ["contractNo", "template"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false
+      },
+      "_meta": {
+        "version": "0.9.0",
+        "endpoint": "/mcp/processing.notice.send",
+        "timeoutMillis": 10000,
+        "enabled": false
+      }
+    }
+  ]
+}

docs/contracts/tool-service-mcp/examples/bundle-v0.2/mcp-bundle-config.yaml

@@ -0,0 +1,51 @@
+# MCP Server의 bundle 조회 설정 예시 (protocol-v0.2-bundle-discovery.md 3절)
+#
+# 이 파일은 계약 예시이며 실제 적용 설정이 아니다.
+# 운영에서는 ConfigMap으로 주입하고 MCP Server마다 다른 bundle 목록을 갖는다.
+#
+# 키 이름은 구현된 McpProperties와 1:1로 맞춰 두었다. Spring relaxed binding이
+# camelCase와 kebab-case를 모두 받으므로 이 문서는 읽기 쉬운 camelCase를 쓴다.
+
+mcp:
+  # 이 MCP Server의 식별자. Redis key namespace에 사용한다.
+  identity: mcp-insurance-core
+
+  registry:
+    # 조회 주기와 첫 scheduled refresh 쏠림을 줄이는 지연 jitter. 기동 preload는 즉시 실행한다.
+    refreshIntervalSeconds: 30
+    refreshJitterSeconds: 5
+
+  discovery:
+    # 운영 profile에서는 true이고 아래 Tool Service 매니페스트만 원천으로 사용한다.
+    # false는 local profile의 테스트 JSON에만 사용한다.
+    enabled: true
+
+    connectTimeoutMillis: 1000
+    readTimeoutMillis: 3000
+
+    # 상한. 초과 시 처리는 계약 7절을 따른다.
+    maxToolsPerBundle: 100
+    maxToolsTotal: 200
+    maxManifestBytes: 1048576
+
+    # 매니페스트가 선언한 Tool timeout의 상한. 초과분은 절삭한다.
+    # Tool이 과도한 timeout을 선언해 MCP 스레드를 점유하는 것을 막는다.
+    maxToolTimeoutMillis: 30000
+
+  # 스키마는 N개를 허용하지만 운영 배포에서는 항상 한 항목이다.
+  # MCP 배포 하나가 Tool Service 하나만 보기 때문이다(ADR-0007).
+  # 대상을 늘리려면 이 목록이 아니라 MCP 배포를 하나 더 만든다.
+  bundles:
+    - id: insurance-processing
+      # 매니페스트 조회 주소 (MCP -> Tool)
+      manifestUrl: http://tool-processing.ax-hub.svc.cluster.local:8080/tool-manifest
+      # 매니페스트의 상대 endpoint를 절대 URL로 바꿀 때 쓰는 기준 주소.
+      # Pod IP가 아니라 Service URL을 사용한다.
+      # Tool 실행 주소 자체는 매니페스트의 endpoint 또는 _meta.endpoint가 정한다(ADR-0010).
+      # 매니페스트가 절대 URL을 쓰면 해석에는 쓰이지 않지만, 그때도 절대 HTTP(S)여야 한다.
+      baseEndpoint: http://tool-processing.ax-hub.svc.cluster.local:8080/mcp
+      # Tool Service가 선언한 표준 MCP name이 따라야 할 접두사.
+      # 업무 단위이며 중요도 등급을 넣지 않는다. 등급이 이름에 들어가면
+      # Tool 재분류가 Tool name 변경이 되어 Agent Builder 재등록을 부른다.
+      namePrefix: "processing."
+      enabled: true

docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md

@@ -0,0 +1,355 @@
+# Tool Service-MCP Bundle 조회 계약 v0.2
+
+- 상태: **Implemented** (MCP 서버 측 구현 완료, Tool Service 측 합의 대기)
+- 기준일: 2026-07-30
+- 대체 대상: push 등록 방식(v0.1). 채택하지 않은 이유는 §2
+- 조회 endpoint: `GET {manifestUrl}` — Tool Service가 제공
+- 실행 endpoint: Tool Service manifest의 top-level `endpoint` 또는 `_meta.endpoint` — 현재 구현
+
+## 1. 계약 범위와 원칙
+
+Tool Service는 여러 Tool을 함께 배포하는 하나의 프로젝트이며, 이 계약에서 **bundle**이라 부른다.
+MCP Server는 자기 설정에 선언된 bundle의 매니페스트를 **주기적으로 조회**해 Tool 목록을 구성한다.
+
+| 원칙 | 내용 |
+|---|---|
+| MCP가 가져온다 | Tool Service는 매니페스트를 제공만 한다. MCP에 등록 요청을 보내지 않는다 |
+| 조회 대상은 설정이 정한다 | 어떤 bundle이 이 MCP에 속하는지는 배포 시점 YAML로 확정된다 |
+| **Tool Server domain은 포털이, Tool endpoint는 Tool Service가 소유한다** | 포털은 Tool Server의 `serviceDomain`과 `manifestPath`만 제공하고, 개별 Tool 실행 endpoint는 Tool Service manifest의 top-level `endpoint` 또는 `_meta.endpoint`에서 온다 |
+| 매니페스트는 전체 상태 | 응답은 그 bundle의 Tool 전체 목록이다. 증분 없음 |
+| 조회 성공이 생존 신호 | 별도 heartbeat·TTL 장치가 없다 |
+| bundle 단위 조회 격리 | 한 bundle의 조회 실패가 다른 bundle의 조회를 중단시키지 않는다 |
+| aggregate는 전부 아니면 전무 | 단, 직전 성공본조차 없는 bundle이 하나라도 있으면 카탈로그 전체를 교체하지 않는다 |
+
+세 번째 원칙이 이 계약의 신뢰 경계다. 매니페스트는 **무엇을 노출하는가**와 **어디로 호출할 것인가**를
+함께 말한다. MCP는 endpoint의 scheme(HTTP(S))과 host 존재만 형식 검사하고 도메인 허용목록을 두지
+않으므로, 매니페스트 원천의 신뢰성이 그대로 outbound 대상의 신뢰성이 된다. 따라서 §4의 "매니페스트
+endpoint를 MCP Server namespace에서만 접근 가능하게 한다"는 요구는 선택적 강화가 아니라 이 계약의
+전제 조건이다([ADR-0010](../../decisions/ADR-0010-tool-service-manifest-owns-execution-endpoint.md)).
+
+마지막 두 원칙은 층이 다르다. **조회**는 bundle마다 독립이고 실패해도 직전 성공본이 남으므로
+평소에는 한 bundle의 장애가 다른 bundle을 건드리지 않는다. 그러나 **카탈로그 교체**는 전부 아니면
+전무다. 한 번도 성공한 적 없는 bundle이 남아 있으면 그 상태로 목록을 확정하지 않는다.
+일부만 담긴 목록은 "필요한 Tool이 조용히 사라진 상태"를 만들기 때문이다(§7, §11 W11).
+
+> **운영 배포에서 bundle은 항상 하나다.** MCP 배포 하나가 Tool Service 하나만 보기로 했기 때문이다
+> ([ADR-0007](../../decisions/ADR-0007-one-mcp-per-tool-service.md)). 따라서 여러 bundle을 전제로 한
+> 규칙(§7의 4·6번, `maxToolsTotal`)은 운영에서 발동하지 않는다. 계약과 구현은 N개를 계속 지원하지만
+> 배포 정의가 1개로 잠그며, 그 사실은 `HelmDeploymentContractTest`가 검사한다.
+
+## 2. 왜 조회 방식인가, 왜 기동 시 1회가 아닌가
+
+### push를 채택하지 않은 이유
+
+Tool Service가 MCP로 등록을 보내는 방식은 **MCP Server가 재기동되면 카탈로그를 복구할 방법이 없다.**
+Tool Service는 이미 등록을 마쳤으므로 다시 보내지 않고, MCP는 빈 상태로 서비스한다.
+재기동 빈도는 오히려 MCP 쪽이 높다(배포·스케일·노드 이동).
+
+조회 방식은 MCP가 스스로 물어보므로 이 문제가 성립하지 않는다.
+또한 MCP에 쓰기 endpoint를 열지 않아도 된다.
+
+### 기동 시 1회로 끝내지 않는 이유
+
+조회 방식이라도 기동 시 1회만 하면 아래를 따라가지 못한다.
+
+| 상황 | 기동 시 1회만 | 주기적 조회 |
+|---|---|---|
+| MCP 재기동 | ✅ 다시 조회하므로 복구 | ✅ |
+| Tool이 Tool 목록·schema 변경 | ❌ MCP 재기동 전까지 모름 | ✅ 다음 주기 반영 |
+| Tool Service 장애 | ❌ 계속 노출 | ✅ 직전 성공본 유지, 정상 응답에서 삭제 확인 시 제거 |
+| MCP 기동 시점에 Tool이 배포 중이라 응답 실패 | ❌ **영구 누락** | ✅ 다음 주기 복구 |
+
+마지막 항목이 가장 위험하다. 조회는 반드시 주기적이어야 한다.
+
+## 3. MCP 설정 (YAML)
+
+조회 대상과 라우팅 주소를 선언한다. 예시는
+[mcp-bundle-config.yaml](examples/bundle-v0.2/mcp-bundle-config.yaml)에 있다.
+
+```yaml
+mcp:
+  identity: mcp-insurance-core
+  registry:
+    refreshIntervalSeconds: 30
+  discovery:
+    enabled: true
+    connectTimeoutMillis: 1000
+    readTimeoutMillis: 3000
+    maxToolsPerBundle: 100
+    maxToolsTotal: 200
+    maxManifestBytes: 1048576
+    maxToolTimeoutMillis: 30000
+  bundles:
+    # 운영 배포에서 이 목록은 항상 한 항목이다(ADR-0007). 스키마는 N개를 허용한다.
+    - id: insurance-processing
+      manifestUrl: http://tool-processing.ax-hub.svc.cluster.local:8080/tool-manifest
+      baseEndpoint: http://tool-processing.ax-hub.svc.cluster.local:8080/mcp
+      namePrefix: "processing."
+      # local 검증에서만 사용. 최초 원격 조회 실패 때만 읽으며 운영 Helm에는 넣지 않는다.
+      fallbackManifestFile: file:./config/local-process-tools-manifest-sample-v1.json
+      enabled: true
+```
+
+| 항목 | 설명 |
+|---|---|
+| `discovery.enabled` | 운영에서는 `true`이며 bundle 매니페스트를 원천으로 사용한다. `false`는 legacy local JSON fixture에만 사용한다 |
+| `manifestUrl` | 매니페스트 조회 주소 |
+| `baseEndpoint` | 매니페스트의 **상대** endpoint를 절대 URL로 바꿀 때 쓰는 기준 주소. Pod IP가 아니라 Service URL을 사용한다. Tool 실행 주소 자체는 매니페스트가 정한다 |
+| `namePrefix` | 이 bundle이 사용할 수 있는 Tool 이름 접두사 |
+| `fallbackManifestFile` | 선택. 최초 원격 조회 실패 때만 읽을 local manifest 파일. 운영 Helm에는 설정하지 않는다 |
+| `enabled` | `false`면 조회하지 않는다. Actuator 상태에는 `status: "disabled"`로 나타난다 |
+
+`manifestUrl`과 `baseEndpoint`를 나눈 이유는 매니페스트 제공 경로와 실행 경로가 다를 수 있기 때문이다.
+같아도 무방하다. 매니페스트가 절대 URL을 선언하면 `baseEndpoint`는 해석에 쓰이지 않지만, 그때도
+`baseEndpoint`는 절대 HTTP(S)여야 한다. MCP가 endpoint 종류와 무관하게 먼저 검사하므로 값이 잘못되면
+그 bundle 전체가 거부된다.
+
+원격 매니페스트와 legacy local JSON fixture는 **배타적**이다. `ToolRegistryClient` 구현은
+`discovery.enabled`로 선택된다. 다만 local profile에서 원격 조회를 켠 경우에는 bundle별
+`fallbackManifestFile`을 둘 수 있다. 이는 **최초 원격 조회가 실패했을 때만** 읽는 같은 매니페스트 형식의
+cold-start fallback이며, 원격 정상 목록이나 직전 성공본을 덮어쓰지 않는다.
+
+| profile | `discovery.enabled` | 등록되는 원천 | 결과 |
+|---|:---:|---|---|
+| `local` | `false` | `LocalFileToolRegistryClient` | legacy JSON fixture만 사용 |
+| `local` | `true` | `ToolBundleRegistryClient` | 원격 우선, 설정 시 local manifest fallback |
+| `local` 아님(`ocp` 등) | `true` | `ToolBundleRegistryClient` | 정상. 운영 |
+| `local` 아님 | `false` | 없음 | **기동 실패** |
+
+원천이 하나도 없으면 `ToolRegistryService`가 주입받을 bean이 없어 기동 단계에서 멈춘다.
+빈 Tool 목록으로 조용히 뜨는 것보다 낫지만, 오류 메시지가 Spring의 bean 해석 실패이므로
+원인을 바로 알기 어렵다. 두 profile YAML이 이미 올바른 값을 고정하고 있으므로
+(`application-local.yml`과 `application-ocp.yml`은 `true`; legacy local fixture만 쓸 때에만 `false`)
+새 profile을 추가할 때만 주의하면 된다.
+
+### 조회 주기와 jitter
+
+주기는 기존 `mcp.registry.refreshIntervalSeconds`를 사용한다. replica가 동시에 기동할 때
+조회 쏠림을 줄이기 위해 첫 **scheduled refresh**에만 `refreshJitterSeconds` 범위의 bounded jitter를 더한다.
+ApplicationReady 직후 warm start와 원천 preload는 빈 목록 구간을 줄이기 위해 jitter 없이 즉시 실행한다.
+
+### 기동 시 검증
+
+아래를 위반하면 **기동에 실패한다.** 잘못된 설정이 운영 중 엉뚱한 라우팅으로 나타나는 것보다 낫다.
+
+| 규칙 | 이유 |
+|---|---|
+| `discovery.enabled=true`이면 `bundles`가 비어 있을 수 없다 | 이 상태로 뜨면 `tools/list`가 영구히 빈다 |
+| `id`는 중복될 수 없다 | 상태 추적 단위가 겹친다 |
+| `namePrefix`는 중복될 수 없고 다른 prefix의 접두사도 될 수 없다 | `a.`와 `a.b.`가 함께 있으면 `a.b.search`의 소속이 확정되지 않는다 |
+
+## 4. Tool Service가 제공할 endpoint
+
+```text
+GET {manifestUrl}
+Accept: application/json
+If-None-Match: "<직전 revision>"   # 선택
+```
+
+매니페스트 조회는 사용자 요청이 아니라 **배경 갱신**이다. 특정 호출자의 요청 context가 없으므로
+correlation·사원 식별자 header를 붙이지 않는다.
+
+응답:
+
+```text
+200 OK
+Content-Type: application/json
+ETag: "sha256:9f2c..."             # 선택. revision과 같은 값
+```
+
+응답 예시는 [manifest-response.json](examples/bundle-v0.2/manifest-response.json)을 따른다.
+
+`If-None-Match`가 현재 `revision`과 같으면 `304 Not Modified`를 본문 없이 반환해도 된다.
+MCP는 이 경우 직전 매니페스트를 그대로 유지한다. **선택 기능이며 구현하지 않아도 계약을 만족한다.**
+
+이 endpoint는 인증을 요구하지 않아도 되지만, **NetworkPolicy로 MCP Server에서만 접근 가능하도록
+제한한다.** Tool 이름·설명·schema는 내부 시스템 구조를 드러내므로 클러스터 전체에 공개하지 않는다.
+
+## 5. 매니페스트 스키마
+
+### 최상위 필드
+
+| 필드 | 필수 | 설명 |
+|---|:---:|---|
+| `bundleId` | 예 | MCP 설정의 `id`와 일치해야 한다. 다르면 그 응답을 버린다 |
+| `revision` | 아니오 | 매니페스트 버전. 변경 감지·로그·ETag에만 쓰인다 |
+| `tools` | 예 | 이 bundle이 노출하는 Tool 전체. 빈 배열은 "노출할 Tool 없음"이다 |
+
+Tool 실행 endpoint는 각 Tool의 top-level `endpoint` 또는 `_meta.endpoint`에 넣는다. 상대 경로를 쓰면 포털 registry의 `serviceDomain` 뒤에 붙고, 절대 URL을 쓰면 Tool Service manifest가 제공한 실행 주소 원천으로 그대로 사용한다. HTTP(S)가 아닌 scheme은 거부한다.
+
+### `tools[]` 필드
+
+| 필드 | 필수 | 설명 |
+|---|:---:|---|
+| `name` | 예 | MCP 표준에 맞춘 `[A-Za-z0-9_./-]{1,64}`이며 bundle의 `namePrefix`로 시작해야 한다 |
+| `title` | 아니오 | 표시용 이름 |
+| `description` | 예 | 에이전트가 Tool 선택에 사용한다. 언제 쓰는 도구인지 명확히 쓴다 |
+| `inputSchema` | 예 | JSON Schema 2020-12 |
+| `endpoint` 또는 `_meta.endpoint` | 예 | Tool 실행 주소. top-level `endpoint`를 먼저 읽고 없으면 `_meta.endpoint`를 쓴다. 둘 다 없으면 Bundle 전체를 거부한다 |
+| `outputSchema` | 아니오 | `structuredContent` 응답 구조. 현재 MCP는 구조화 출력을 만들지 않으므로 운영에서는 사용하지 않는다 |
+| `annotations` | 아니오 | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` |
+| `_meta.version` | 예 | Tool 버전 |
+| `_meta.timeoutMillis` | 아니오 | MCP 설정의 `maxToolTimeoutMillis`로 상한을 건다 |
+| `_meta.enabled` | 아니오 | 기본 `true`. `false`면 `tools/list`에 노출하지 않는다 |
+
+`name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`는 MCP가 `tools/list`로
+그대로 공개한다. `_meta`와 `endpoint`는 내부 실행 정보이므로 공개본에서 제거한다.
+
+현재 MCP의 `tools/call`은 `content[0].text`만 반환하고 `structuredContent` 생성·응답 schema 검증은 하지 않는다.
+MCP 2025-11-25에서 `outputSchema`를 선언한 서버는 이에 맞는 구조화 결과를 제공해야 하므로, Tool Service는
+구조화 출력 지원이 별도 계약으로 반영되기 전까지 운영 매니페스트에서 `outputSchema`를 생략한다.
+
+## 6. MCP의 조회 동작
+
+| 항목 | 권장값 | 근거 |
+|---|---|---|
+| 주기 | `30초` | 변경 반영 지연의 상한 |
+| 첫 scheduled refresh jitter | `0~5초` | 반복 조회 주기가 replica마다 같은 시점에 고정되는 것을 방지 |
+| 연결 timeout | `1초` | |
+| 읽기 timeout | `3초` | |
+| 기동 시 | **즉시 1회 조회하되 기동을 막지 않는다** | Tool 장애가 MCP 기동 실패로 번지지 않게 |
+| readiness | **첫 조회 시도 완료 + usable snapshot이면 ready** | 원천 또는 Redis last-good이 있어 실제 요청을 처리할 수 있을 때만 트래픽을 받는다 |
+
+usable snapshot은 원천 조회 성공본, 최초 원격 조회 실패 때 채택한 local fallback, 또는 Redis에서 채택한 last-good이다. 정상 매니페스트가 반환한 빈 Tool
+목록도 유효한 전체 상태다. 반대로 첫 조회가 끝났더라도 memory와 Redis에 성공본이 하나도 없으면 readiness는
+DOWN을 유지하고 다음 주기 조회를 기다린다.
+
+### 동시 조회
+
+bundle N개를 **동시에** 조회한다. 순차 조회하면 소요 시간이 합산되어 기동과 갱신이 지연된다.
+
+개별 조회 실패는 **예외가 아니라 결과값**으로 다룬다. 하나의 실패가 전체 조회를 중단시키면
+나머지 성공분까지 버려진다.
+
+### 실패 판정과 유예
+
+| 조회 결과 | 처리 |
+|---|---|
+| 성공 + 검증 통과 | 새 매니페스트 채택 |
+| 성공 + 검증 실패 | 직전 성공본 유지. 실패 횟수 증가 |
+| timeout / 연결 실패 / 5xx | 직전 성공본 유지. 실패 횟수 증가 |
+| `304 Not Modified` | 직전 성공본 유지. 실패 횟수 **초기화** |
+
+`304`는 **아직 구현하지 않았다.** §4에서 선택 기능으로 둔 항목이므로 `If-None-Match`를 보내지 않고,
+Tool Service가 `304`를 반환할 일도 없다. 매번 전체 매니페스트를 받아 채택한다.
+
+구현상 실패는 **예외가 아니라 결과값**이다. 조회 작업이 예외를 그대로 올리면 `Future` 하나가 깨지면서
+나머지 bundle의 성공분까지 함께 버려지기 때문이다. bundle별 작업이 자기 예외를 잡아 실패 결과로 바꾸고,
+그 바깥에 예상 밖의 오류까지 흡수하는 2차 방어선을 둔다.
+
+## 7. 병합 규칙
+
+1. **이름 검증** — `namePrefix`로 시작하지 않는 Tool은 그 bundle 전체를 거부한다
+2. **`enabled: false` 제외** — 등록은 하되 `tools/list`에 노출하지 않는다
+3. **상한 검사** — `maxToolsPerBundle` 초과 시 그 bundle 거부, `maxToolsTotal` 초과 시 전체 aggregate 거부
+4. **정렬** — `(bundleId, name)` 오름차순으로 정렬한다
+5. **`timeoutMillis` 상한** — `maxToolTimeoutMillis`를 넘는 값은 상한으로 절삭한다
+6. **bundle 간 이름 충돌** — 어느 Tool도 임의 선택하지 않고 전체 aggregate를 거부한다
+
+1번은 Tool 하나가 규칙을 어겨도 **bundle 전체를 거부**한다는 뜻이다. 필수 필드 누락, `bundleId` 불일치,
+매니페스트 내부 이름 중복도 같다. 일부만 반영된 카탈로그는 "필요한 Tool이 조용히 사라진 상태"를 만들어,
+직전 성공본을 유지하는 것보다 나쁘다.
+
+6번을 정렬 **뒤에** 두는 이유는 1번과 같다. 정렬 전에 처리하면 어느 쪽이 살아남는지가
+동시 조회의 응답 순서에 좌우되어 replica마다 달라진다.
+
+정렬이 없으면 동시 조회 응답 순서에 따라 `tools/list` 순서가 매번 달라진다.
+Agent Builder 쪽 프롬프트가 매 호출 달라져 캐시 적중률이 떨어지므로 반드시 정렬한다.
+
+`maxToolsTotal`은 [ADR-0002](../../decisions/ADR-0002-tool-exposure-and-single-call.md)의
+Tool 노출 상한과 함께 검토한다. 운영 배포는 bundle이 하나이므로(ADR-0007) 이 상한은
+`maxToolsPerBundle`과 같은 층에서 동작하며, 50개 노출 상한은 한 Agent가 **여러 MCP에서 가져온
+Tool의 합계**에 적용된다. MCP를 나눈다고 상한이 늘지 않는다.
+
+## 8. Tool을 찾지 못했을 때의 재확인
+
+`tools/call` 요청의 Tool이 현재 스냅샷에 없으면, **해당 bundle을 즉시 1회 재조회한 뒤**
+그래도 없으면 `-32001 Tool not found`로 응답한다.
+
+MCP replica마다 조회 시점이 달라 스냅샷이 일시적으로 어긋날 수 있기 때문이다(§11 W2).
+
+구현은 해당 bundle 하나가 아니라 **전체를 한 번 재조회**한다. 재조회 대상은 병렬이고 timeout이 짧아
+비용 차이가 작은 반면, "어느 bundle에 속한 Tool인가"를 이름만으로 되짚는 경로를 따로 두지 않아도 된다.
+계약이 요구하는 것(한 번 더 확인한 뒤 판정)은 그대로 만족한다.
+
+## 9. 운영 상태 조회
+
+```text
+GET /actuator/toolBundles
+```
+
+management port(운영 기본 9090)에서 MCP가 알고 있는 bundle의 조회 상태를 반환한다. 외부 ingress에는
+노출하지 않는다. 응답 예시는
+[bundle-status-response.json](examples/bundle-v0.2/bundle-status-response.json)에 있다.
+
+설정에 선언되어 있으나 한 번도 조회에 성공하지 못한 bundle도 반환한다.
+**설정에 기대값이 있으므로 누락 감지가 가능하다.**
+
+| `status` | 의미 |
+|---|---|
+| `healthy` | 마지막 조회 성공 |
+| `fallback` | 최초 원격 조회에 실패해 local manifest sample을 사용 중 |
+| `degraded` | 최근 조회는 실패했지만 직전 성공본을 계속 노출 중 |
+| `unreachable` | 켜져 있으나 한 번도 성공한 적 없음 |
+| `disabled` | 설정에서 `enabled: false` |
+
+응답에 **`manifestUrl`과 `namePrefix`는 넣지 않는다.** 진단에 꼭 필요하지 않은데 내부 주소 체계를 더 드러낸다.
+`lastFailureReason`도 메시지가 아니라 **예외 타입 이름만** 담는다. 메시지에는 URL이나 응답 조각이 섞일 수 있다.
+
+읽기 전용이며 상태를 바꾸지 않는다. 그러나 내부 구조를 노출하므로 외부에 공개하지 않는다.
+
+이 endpoint는 Spring Boot Actuator가 제공하므로 `/mcp`의 JSON-RPC 예외 처리 경계를 통과하지 않는다.
+
+## 10. 실행 경로 (MCP → Tool, 현재 구현)
+
+이미 구현되어 있는 계약이다. Tool Service는 아래를 받을 수 있어야 한다.
+
+```text
+POST {endpoint}
+Content-Type: application/json
+guid, x-request-id, mcp-session-id, employee-no, virtual-employee-no
+Authorization: <설정에 따라 전달>
+
+<tools/call의 arguments 객체 원본>
+```
+
+- 호출자 header 다섯 개는 **이름과 값을 바꾸지 않고 그대로 bypass**한다. 값이 없는 header는 보내지 않는다.
+- `employee-no`·`virtual-employee-no`는 호출자가 암호화한 값이다. **복호화는 Tool Service 몫이며
+  사내 KMS에서 발급받은 키를 사용한다.** MCP는 키를 갖지 않으므로 값을 읽지도, 로그에 남기지도 못한다.
+  MCP가 인증을 하지 않으므로([ADR-0006](../../decisions/ADR-0006-no-authentication-in-mcp.md))
+  이 값의 신뢰 여부는 Tool Service가 판단한다. 두 header가 모두 없을 수 있다는 점도 함께 고려한다.
+- 발송·등록·변경 Tool의 중복 실행 방지는 Tool Service 책임이다. retry가 같은 `guid`를 재사용할지와
+  이를 멱등성 키로 사용할지는 아직 합의되지 않았으므로 현재 wire 계약으로 가정하지 않는다.
+  합의 대상은 [extension-points.md](../../extension-points.md)에 한 번만 관리한다.
+- 요청 body는 에이전트가 보낸 `arguments` 객체 **그대로**다. MCP는 이름·값을 바꾸지 않는다.
+- 응답이 JSON object/array면 MCP가 compact JSON 문자열로 `result.content[0].text`에 담는다.
+- Tool이 반환한 HTTP 4xx/5xx와 timeout은 `result.isError: true`로 변환한다.
+- 호출 소요 시간은 `result.content[0]._meta.searchTime`(ms)로 반환한다.
+
+향후 Tool Service를 MCP 서버로 만들면 매니페스트 조회를 표준 `tools/list`로, 실행을 표준
+`tools/call`로 대체할 수 있다. 이 경우 §4·§5는 MCP 표준으로 흡수된다. 전환 여부는 합의 항목이다.
+
+## 11. 트레이드오프와 확장 경계
+
+현재 선택은 **Tool Service 원천 + 주기 pull + in-memory last-good + 선택 Redis 공유 cache**다.
+Redis의 key 형식, TTL, 공유 범위와 운영 정책은 이 Tool Service wire 계약의 범위가 아니며
+[extension-points.md](../../extension-points.md#운영-적용-전-필수-보완)에서 합의한다.
+
+| 트레이드오프 | 현재 선택 |
+|---|---|
+| replica snapshot 차이 | 일시 허용. 성공본만 교체하고 Tool miss 시 원천을 한 번 재확인 |
+| 변경 반영 지연 | 기본 한 주기 허용. 즉시 알림·ETag는 아직 도입하지 않음 |
+| 조회 부하 | replica별 조회 허용. 규모가 커질 때만 leader election 검토 |
+| 기동 중 원천 장애 | Redis warm start 후 즉시 preload. local profile에 fallback 파일이 있으면 최초 실패 때만 채택하고, 없으면 다음 조회까지 Registry unavailable |
+| stale Tool | 조회 실패만으로 삭제하지 않음. 성공한 매니페스트에서 빠진 경우에만 삭제 |
+| Redis 장애 | cache miss로 격리. 요청 경로는 in-memory만 조회 |
+
+NetworkPolicy·egress, 관측 지표, retry/idempotency, outputSchema 등 아직 합의하거나 보완할 내용은
+[extension-points.md](../../extension-points.md)에서만 관리한다. 구현 목록은 코드와 테스트가 정본이며 이 계약에 다시 나열하지 않는다.
+
+## 12. 의도적으로 넣지 않은 기능
+
+- `If-None-Match` / `304`: 매니페스트가 작아 현재 효용이 없음
+- 즉시 refresh 알림 endpoint: 주기 반영으로 부족하다는 운영 근거가 생길 때 검토
+- leader election: replica 조회 부하가 실제 병목이 될 때 검토
+- 상태 응답의 `manifestUrl`·`namePrefix`: 불필요한 내부 주소 노출 방지

docs/contracts/tool-service-mcp/tool-list-loading-guide.md

@@ -0,0 +1,187 @@
+# 안내: Tool 목록 최초 적재와 `tools/list` 노출 흐름
+
+> 상태: **안내 문서** · 기준: 현재 MCP 서버 구현 · 대상: Tool Service 개발 파트
+>
+> 이 문서는 현재 동작을 이해하기 위한 안내다. 외부 wire 계약의 정본은
+> [Tool Service-MCP Bundle 조회 계약 v0.2](protocol-v0.2-bundle-discovery.md)다.
+> 규범 내용은 여기에 복제하지 않고 계약을 가리킨다. 복제본은 조용히 낡기 때문이다.
+
+## 먼저 구분할 것
+
+Tool Service가 MCP 표준 `tools/list`를 직접 구현하는 구조가 아니다. Tool Service는 아래의 내부
+**매니페스트 endpoint**를 제공하고, MCP Server가 이를 읽어 Agent Builder용 표준 `tools/list` 응답으로
+변환한다.
+
+```text
+Tool Service -- GET /tool-manifest --> MCP Server -- JSON-RPC tools/list --> Agent Builder
+```
+
+현재 운영 배포는 MCP 하나가 Tool Service Bundle 하나를 본다. 구현은 호환 목적으로 여러 Bundle의
+병합도 지원하지만, Tool 개발 파트는 자기 Bundle 하나의 매니페스트만 제공하면 된다.
+
+## 1. 최초 적재는 구현되어 있는가?
+
+**구현되어 있다.** Spring 애플리케이션이 준비되면 `ToolRegistryRefreshScheduler.preload()`가 실행된다.
+
+```text
+ApplicationReadyEvent
+  -> 선택 Redis snapshot warm start (있으면 memory에 임시 적재)
+  -> Tool Service manifest 즉시 조회
+  -> 검증 성공한 전체 Tool 목록으로 memory snapshot 교체
+  -> 선택 Redis cache 저장
+  -> readiness 판단 가능
+```
+
+Redis는 선택 cache일 뿐이다. Redis가 없거나 실패해도 Tool Service 매니페스트 조회가 성공하면 정상
+기동한다. 반대로 최초 조회와 선택 cache 모두 실패하면 애플리케이션 프로세스는 살아 있어도 usable
+Tool 목록이 없으므로 readiness는 DOWN이다. 다음 주기 조회에서 자동 재시도한다.
+
+`tools/list` 요청이 기동 preload보다 먼저 들어와 memory snapshot이 비어 있으면, 요청 경로도 원천을
+한 번 직접 조회해 cold start 공백을 메운다.
+
+## 2. Tool Service에서 memory까지의 처리 순서
+
+```text
+ToolBundleRegistryClient.fetchTools()
+  -> ToolBundleDiscovery.discoverAll()
+  -> GET {manifestUrl}
+  -> bundleId / tools[] / Tool 필수 필드 검증
+  -> ToolMetadata 생성 (endpoint는 Tool Service manifest의 top-level endpoint 또는 _meta.endpoint 사용)
+  -> enabled=false Tool 제외
+  -> immutable List<ToolMetadata>를 AtomicReference snapshot에 저장
+```
+
+실제 memory 저장소는 `ToolRegistryService`의 `AtomicReference<List<ToolMetadata>>`다.
+
+- 매니페스트 조회·검증에 **성공했을 때만** 새 immutable 목록으로 통째로 교체한다.
+- HTTP 오류, timeout, JSON 오류, 필수 필드 누락, 이름 규칙 위반은 기존 snapshot을 비우지 않는다.
+- Tool 하나만 걸러서 부분 반영하지 않는다. 매니페스트 하나가 잘못되면 해당 Bundle 전체를 거부한다.
+- 현재 운영은 Bundle 하나지만, 구현상 여러 Bundle이면 모두 사용 가능한 성공본이 있을 때만 하나의 snapshot을 교체한다.
+- 주기 refresh가 겹치면 single-flight로 하나의 원천 조회를 공유한다.
+
+## 3. Agent Builder의 `tools/list` 요청은 어떻게 처리되는가?
+
+Agent Builder는 공개 `POST https://{mcpHost}{publicPath}`로 JSON-RPC 요청을 보낸다. OpenShift Route는
+해당 path의 MCP Service만 선택하고, 컨테이너가 같은 `POST {publicPath}`를 직접 처리한다.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+처리 경로는 다음과 같다.
+
+```text
+McpController
+  -> McpMethodHandlerRegistry
+  -> ToolsListHandler
+  -> ToolRegistryService.listTools()
+  -> in-memory snapshot 읽기
+  -> MCP SDK ListToolsResult 변환
+  -> JSON-RPC result.tools 반환
+```
+
+memory snapshot이 이미 있으면 `tools/list`는 Tool Service나 Redis를 호출하지 않는다. 따라서 Tool
+Service가 잠시 느리거나 Redis가 장애여도 이미 적재한 목록은 바로 반환한다.
+
+`ToolsListHandler`는 매니페스트 Tool 정의의 공개 필드만 MCP Tool로 만든다. `_meta` 안의
+`version`, `timeoutMillis`, `enabled`와 MCP 내부의 `endpoint`는 절대 Agent Builder에 노출하지 않는다.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "tools": [
+      {
+        "name": "processing.contract.inquiry",
+        "title": "계약 조회",
+        "description": "계약번호로 계약의 기본 정보를 조회합니다.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "contractNo": { "type": "string" }
+          },
+          "required": ["contractNo"]
+        },
+        "annotations": {
+          "readOnlyHint": true
+        }
+      }
+    ]
+  }
+}
+```
+
+정확한 Agent Builder 응답 fixture는
+[tools-list-response.json](../agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json)을 따른다.
+
+## 4. Tool Service가 구현할 매니페스트 endpoint
+
+Tool Service는 MCP 배포 설정에 등록된 `manifestUrl`에 대해 다음을 반환한다.
+
+```text
+GET /tool-manifest
+Accept: application/json
+
+200 OK
+Content-Type: application/json
+```
+
+이 요청은 사용자 Tool 실행이 아니라 MCP의 배경 metadata 갱신이다. 따라서 `guid`, 사원 식별자,
+`Mcp-Session-Id` 같은 요청 상관·사용자 header를 기대하면 안 된다.
+
+현재 구현은 conditional GET을 보내지 않으므로 Tool Service는 우선 항상 `200 OK`와 전체 JSON을
+반환하면 된다. `304 Not Modified`와 ETag는 계약상 선택 사항이지만 현재 MCP 구현 범위가 아니다.
+
+### 응답 규칙
+
+필드별 규칙과 검증 결과는 [계약 v0.2 §5](protocol-v0.2-bundle-discovery.md#5-매니페스트-스키마)가
+정본이다. 이 문서에 같은 표를 두지 않는다. 예전에 표와 예제를 복제했다가 `endpoint` 필수화를 놓쳐,
+MCP가 거부할 매니페스트를 안내하고 있었다.
+
+실제 응답 예제는 [examples/bundle-v0.2/manifest-response.json](examples/bundle-v0.2/manifest-response.json)을
+본다. 이 파일은 `ToolBundleContractExampleTest`가 직접 읽어 구현과 대조하므로, 문서 가운데 유일하게
+조용히 어긋날 수 없는 사본이다.
+
+Tool Service가 특히 놓치기 쉬운 세 가지만 짚는다.
+
+- **`endpoint`는 필수다.** top-level `endpoint` 또는 `_meta.endpoint`가 없으면 그 Tool 하나가 아니라
+  Bundle 전체가 거부된다. 상대 경로는 Portal registry의 `serviceDomain` 뒤에 붙고, 절대 URL은
+  HTTP(S) scheme과 host를 갖춰야 한다.
+- **`tools`는 전체 상태다.** 부분 목록이나 증분 변경을 보내면 안 된다.
+- **credential·개인정보·업무 payload는 매니페스트에 넣지 않는다.**
+
+## 5. Tool Service가 알아야 할 실패 동작
+
+조회 결과별 처리는 [계약 v0.2 §6](protocol-v0.2-bundle-discovery.md#6-mcp의-조회-동작)과
+[§7 병합 규칙](protocol-v0.2-bundle-discovery.md#7-병합-규칙)이 정본이다.
+
+Tool Service 입장에서 결론은 하나다. **한 번의 `200` 응답은 그 시점에 노출할 Tool의 완전한 목록이어야
+한다.** 조회가 실패하면 MCP는 직전 성공 목록을 유지하므로 실패가 Tool 삭제로 해석되지는 않는다.
+그러나 성공한 응답에서 Tool이 빠지면 그것은 삭제로 반영된다. 부분 목록을 한 번 보내는 순간 그대로
+카탈로그가 된다.
+
+## Tool Service 구현 체크리스트
+
+1. `GET /tool-manifest`를 MCP Server namespace에서만 접근 가능하게 제공한다.
+2. `bundleId`가 배포 설정의 Bundle id와 정확히 일치하는지 배포 전에 함께 확인한다.
+3. 모든 Tool에 고유한 표준 `name`, 비어 있지 않은 `description`, object 형태의 `inputSchema`, `_meta.version`을 넣는다.
+4. Tool을 숨기려면 `_meta.enabled: false`를 쓰거나 정상 전체 목록에서 제거한다. 둘의 변경 반영 시점은 다음 refresh다.
+5. credential·개인정보·업무 payload를 매니페스트에 넣지 않는다. 실행 주소는 6번을 따른다.
+6. Tool 자체 실행 endpoint는 manifest의 top-level `endpoint` 또는 `_meta.endpoint`에 선언한다. 상대 경로는 Portal registry의 `serviceDomain` 뒤에 붙고, 절대 HTTP(S) URL은 Tool Service가 제공한 실행 주소 원천으로 그대로 사용한다.
+
+## 확인한 구현·테스트
+
+- 최초 preload·주기 refresh: `ToolRegistryRefreshScheduler`
+- in-memory snapshot·실패 fallback: `ToolRegistryService`
+- HTTP 매니페스트 조회·필드 검증: `ToolBundleDiscovery`
+- `tools/list` 공개 필드 변환·`_meta` 제거: `ToolsListHandler`
+- 회귀 테스트: `ToolRegistryServiceTest`, `ToolBundleDiscoveryTest`, `ToolsListHandlerTest`
+
+자세한 field 정의와 실행 계약은 [v0.2 계약](protocol-v0.2-bundle-discovery.md), 실제 manifest 전체 예시는
+[manifest-response.json](examples/bundle-v0.2/manifest-response.json)을 참고한다.

docs/decisions/ADR-0001-stateless-execution-boundary.md

@@ -0,0 +1,23 @@
+# ADR-0001 Stateless 실행 책임 경계
+
+- 상태: Accepted
+- 결정일: 2026-07-10
+- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md)
+
+## 배경
+
+Agent Builder는 사용자 의도와 업무 맥락을 바탕으로 실행할 Tool을 결정하고, MCP Server는 요청된 Tool을 안전하게 검증·실행하는 계층이다.
+
+## 결정
+
+- MCP Server는 서버 측 대화 세션을 보관하지 않는 stateless 실행 계층으로 유지한다.
+- Tool 선택, 의도 분류, 대체 Tool 탐색은 Agent Builder 책임이다.
+- MCP Server는 요청에 명시된 Tool만 Registry metadata에 따라 검증하고 실행한다.
+- `mcp-session-id`가 사용되더라도 대화 상태가 아닌 correlation 값으로 취급한다.
+- Business Rule은 Tool Service 책임으로 유지한다.
+
+## 영향
+
+- MCP Server에 LLM inference, intent classification 또는 autonomous tool selection을 추가하지 않는다.
+- 인증·권한 책임은 이 결정 이후 [ADR-0006](ADR-0006-no-authentication-in-mcp.md)에서 확정했다. MCP는 인증·인가하지 않는다.
+- 현재 구현은 이 결정과 대체로 일치하므로 즉시 코드 변경하지 않는다.

docs/decisions/ADR-0002-tool-exposure-and-single-call.md

@@ -0,0 +1,32 @@
+# ADR-0002 Agent Builder Tool 노출 제한과 단일 Tool 호출
+
+- 상태: Accepted
+- 결정일: 2026-07-10
+- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md)
+
+## 배경
+
+많은 Tool을 한 번에 LLM context에 노출하면 Tool 식별과 선택 정확도가 저하될 수 있다. 또한 한 요청에서 여러 Tool을 실행하면 timeout, 부분 성공, 순서 의존성과 오류 계약이 복잡해진다.
+
+## 결정
+
+- Agent Builder가 사용자·Agent·업무 맥락에 맞는 Tool을 선택한다.
+- Agent Builder가 한 시점에 LLM에 노출하는 활성 Tool은 최대 50개다.
+- 목표 Agent Builder-MCP 호출 모델은 요청 하나당 Tool 하나다.
+- MCP Server는 50개 선별 로직이나 LLM 기반 우선순위 판단을 구현하지 않는다.
+
+## 영향
+
+- 50개 선별은 Agent Builder 변경 사항이며 MCP 코드 변경 대상이 아니다.
+- 요청 하나당 Tool 하나라는 결정은 그대로 유효하다.
+
+### 결정 당시의 envelope 기록 (현재 구현 아님)
+
+결정 시점에는 최종 field 이름이 미확정이어서 `params.toolCalls[]` 배열 envelope를 유지하고,
+원소를 정확히 한 개만 허용해 단일 호출을 강제했다. 빈 배열과 2개 이상은 `-32602`로 거절했다.
+
+이 envelope는 [ADR-0005](ADR-0005-standard-tool-name.md)와
+[계약 v0.3](../contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md)에서
+표준 MCP `params.name` + `params.arguments`로 대체되었다.
+**현재 코드에 `toolCalls`는 존재하지 않는다.** 배열이 사라졌으므로 "정확히 한 개" 검증도
+필요 없어졌고, 단일 호출 결정은 envelope 구조 자체로 만족된다.

docs/decisions/ADR-0003-builder-tool-uid.md

@@ -0,0 +1,29 @@
+# ADR-0003 Builder Tool UID를 시스템 간 식별 키로 사용
+
+- 상태: Superseded
+- 결정일: 2026-07-10
+- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md)
+- 대체 결정: [ADR-0005](ADR-0005-standard-tool-name.md)
+
+> 이 문서는 당시 검토 이력을 보존한다. 현재 구현과 신규 연동에는 ADR-0005를 적용한다.
+
+## 배경
+
+Tool name은 중복 또는 변경 가능성이 있으므로 Agent Builder Tool Registry가 부여한 고유 식별자를 시스템 간 mapping key로 사용할 필요가 있다.
+
+## 결정
+
+- Agent Builder Tool Registry가 Custom Tool에 부여한 UID를 Agent Builder-MCP 사이의 Tool 식별 키로 사용한다.
+- MCP Server는 UID를 Registry metadata의 Tool name, version, endpoint와 매핑하여 실행한다.
+- Tool name과 version은 설명 및 검증 metadata로 유지할 수 있지만 시스템 간 기본 mapping key 역할은 UID가 담당한다.
+
+## 구현 보류 조건
+
+다음 항목은 아직 결정되지 않았으므로 코드 변경 조건이 충족되지 않았다.
+
+- UID 생성 시점과 Agent Builder/MCP 전달 시점
+- version 변경, 비활성화, 삭제, 재등록 시 UID 규칙
+- 환경별 UID 승격 또는 분리 규칙
+- 목표 요청 payload의 UID field 이름
+
+이 보류안은 ADR-0005로 대체되었으며 현재 모델에 UID field를 두지 않는다.

docs/decisions/ADR-0004-execution-guardrails.md

@@ -0,0 +1,30 @@
+# ADR-0004 실행 가드레일
+
+- 상태: Accepted
+- 결정일: 2026-07-10
+- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md)
+
+## 결정
+
+- Agent Builder-MCP 상호작용에는 300초 hard limit을 둔다.
+- MCP Server는 3만 자 기준으로 Tool Service의 원문 응답을 임의 절단하지 않는다.
+- write/update 성격의 Tool은 idempotency가 보장되지 않으면 자동 retry하지 않는다.
+
+## 해석 경계
+
+- 300초는 전체 상한 원칙이며 모든 계층의 socket read timeout을 무조건 300초로 설정한다는 의미가 아니다.
+- 원문 미절단은 response body를 무제한 허용한다는 의미가 아니다.
+- read Tool이 항상 retry 가능하다는 결정은 아니다.
+
+## 구현 보류 조건
+
+다음 세부 계약이 확정되기 전에는 timeout 또는 retry 코드를 변경하지 않는다.
+
+- ~~Agent Builder, ingress, MCP, Tool Service별 timeout budget~~ →
+  **확정 (2026-08-01).** Agent Builder 300초(호출 시점 기준) > MCP 270초 > Tool 30초.
+  배분과 근거는 [architecture.md의 요청 시간 예산](../architecture.md#요청-시간-예산)이 정본이다.
+- client disconnect와 downstream cancellation 전파
+- response body 최대 크기와 pagination/continuation 정책
+- Tool별 idempotency/retryable metadata와 오류 코드
+
+현재 구현에는 3만 자 절단 및 자동 retry가 없으므로 두 원칙에 대한 즉시 코드 변경은 없다.

docs/decisions/ADR-0005-standard-tool-name.md

@@ -0,0 +1,25 @@
+# ADR-0005 표준 MCP Tool name을 실행 식별자로 사용
+
+- 상태: Accepted
+- 결정일: 2026-07-30
+- 대체 대상: [ADR-0003](ADR-0003-builder-tool-uid.md)
+
+## 배경
+
+Tool의 원천 정보는 각 Tool Service가 소유하고 MCP Server가 매니페스트를 pull한다.
+Agent Builder의 UID는 Agent Builder 내부 관리 개념이므로 MCP와 Tool Service 사이의 계약으로
+전파하면 표준 `tools/list`와 `tools/call` 외에 별도 식별자 동기화가 필요해진다.
+
+## 결정
+
+- `tools/list`가 노출하고 `tools/call.params.name`이 전달하는 표준 MCP Tool `name`을 실행 식별자로 사용한다.
+- Tool Service가 전체 MCP 범위에서 고유한 namespaced name을 직접 선언한다.
+- 허용 형식은 MCP 표준에 맞춘 1~64자의 영문·숫자와 `_`, `-`, `.`, `/`다.
+- MCP Server는 이름을 재작성하지 않고 형식, bundle의 `namePrefix`, 전체 중복을 검증한다.
+- Agent Builder 내부 UID는 Agent Builder가 자체 관리하며 MCP metadata와 실행 요청에 요구하지 않는다.
+
+## 결과
+
+- 표준 MCP 계약만으로 목록과 실행 대상을 연결한다.
+- Tool 이름 변경은 식별자 변경이므로 Tool Service와 Agent Builder의 rolling 호환 기간이 필요하다.
+- 이름 충돌이나 전체 Tool 수 상한 초과 시 일부 목록을 노출하지 않고 기존 정상 snapshot을 유지한다.

docs/decisions/ADR-0006-no-authentication-in-mcp.md

@@ -0,0 +1,82 @@
+# ADR-0006 MCP Server는 인증·인가를 하지 않는다
+
+- 상태: Accepted
+- 결정일: 2026-08-01
+- 관련 결정: [ADR-0001](ADR-0001-stateless-execution-boundary.md), [ADR-0010](ADR-0010-tool-service-manifest-owns-execution-endpoint.md), [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.md)
+
+> 이 ADR은 **inbound** 신뢰 경계를 다룬다. outbound 목적지는
+> [ADR-0010](ADR-0010-tool-service-manifest-owns-execution-endpoint.md) 이후 Tool Service 매니페스트가 정하며,
+> 도메인 허용목록도 egress NetworkPolicy도 없다. 아래 "책임 소재" 표의 NetworkPolicy 항목은 ingress 통제이므로
+> outbound 위험을 덮지 않는다.
+
+## 배경
+
+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가 자체 인증을 도입할 때 필요한 연결점이다.

docs/decisions/ADR-0007-one-mcp-per-tool-service.md

@@ -0,0 +1,101 @@
+# ADR-0007 MCP 배포 하나는 Tool Service 하나만 본다
+
+- 상태: Superseded
+- 결정일: 2026-08-02
+- 대체 결정: [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.md)
+- 관련: [ADR-0001](ADR-0001-stateless-execution-boundary.md), [ADR-0002](ADR-0002-tool-exposure-and-single-call.md), [ADR-0009](ADR-0009-container-handles-public-mcp-path.md), [계약 v0.2](../contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md)
+
+> 이 문서는 검토 이력을 보존한다. 현재 구현과 신규 연동에는 [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.md)을 적용한다.
+> route↔Tool Service 매핑의 원천이 Portal로 옮겨지면서, MCP 배포 하나가 N개 route를 보고 route 하나에 N개 Tool Service가 붙는다.
+> 아래 격리 논거는 폐기된 것이 아니라 ADR-0013이 무엇을 포기했는지 판단하는 근거로 남는다.
+
+외부에서 여러 MCP를 하나의 host 아래 path로 묶는 방식은 [ADR-0009](ADR-0009-container-handles-public-mcp-path.md)이
+소유한다.
+
+## 배경
+
+MCP 설정의 `mcp.bundles`는 여러 Tool Service를 하나의 카탈로그로 병합할 수 있다. 이 능력을 실제로 쓸지,
+즉 MCP와 Tool Service를 M:N으로 묶을지는 결정되지 않은 상태였다.
+
+고객 요구는 **Tool의 군집화**다. MCP 자체를 군집화해 달라는 요구가 아니다. 요구의 목적은 가용성이며,
+중요한 Tool은 다운이 없어야 한다는 것이다. 분할 기준은 먼저 업무로 나누고, 그 안에서 중단 시 업무
+영향도와 가용성 위험도로 다시 나누는 형태다. 예: 처리계-중요, 처리계-비중요, 정보계-중요,
+정보계-비중요. 여기서 위험도는 보안·권한 정책이 아니라 **서비스 중단 위험**을 뜻한다. 업무 정책은
+Tool Service가 관리하며 이 배포 등급의 범위가 아니다.
+
+Tool 목록이 확정되지 않아 Tool Service가 몇 개가 될지 모르며, 10~20개 이상이 될 수 있다.
+
+## 결정
+
+1. **MCP 배포 하나는 Tool Service를 정확히 하나 본다.** `mcp.bundles`는 항상 한 항목이다.
+2. 배포 단위의 분할 축은 **업무 × 등급(tier)** 이다. 등급은 `critical`과 `standard`로 둔다.
+3. 등급은 **배포 속성일 뿐 wire 계약에 나타나지 않는다.** Tool 이름·`namePrefix`·매니페스트에 등급을 넣지 않는다.
+4. 다중 bundle 병합 코드는 **삭제하지 않고 유지**하되, 배포 설정에서 bundle 1개로 잠근다.
+
+## 근거
+
+### 등급이 다른 Tool Service를 한 MCP가 보면 격리가 깨진다
+
+`ToolBundleRegistryClient.fetchTools()`는 사용 가능한 성공본이 없는 bundle이 하나라도 있으면
+카탈로그 전체 교체를 거부한다(계약 v0.2 §1, §7). 한 MCP가 중요·비중요 Tool Service를 함께 보면
+**비중요 쪽 조회가 확정되지 않는 동안 중요 Tool의 카탈로그 갱신까지 멈춘다.** 직전 성공본으로
+서빙은 계속되지만 변경 반영은 막힌다.
+
+여기에 두 Tool Service 호출이 같은 프로세스의 HTTP connection pool과 스레드를 공유하므로,
+비중요 쪽 지연이 중요 쪽 여유를 잠식한다.
+
+**병합은 가용성 요구와 정면으로 충돌한다.** 등급을 나눈 목적을 배포 구조가 되돌려 놓는다.
+
+### 병합해서 얻는 것이 없다
+
+MCP에는 업무 로직이 없다. 여러 Tool Service를 하나로 합치는 일이 MCP 안에서 일어나야 할
+기술적 이유가 없다. Agent Builder는 MCP를 개별 등록하면서 하위 Tool 정보를 자기 DB에 저장하고,
+사용자 요청을 판단한 뒤 **해당 Tool을 가진 MCP로 호출을 보낸다.** 여러 Tool 묶음을 아우르는 일은
+Tool 선택을 이미 수행하는 Agent Builder 계층에서 끝난다.
+
+런타임에 공유되는 공통 Tool Service도 없다. Tool 파트의 `tool-common`은 각 Tool Service 프로젝트가
+함께 빌드하는 **빌드 타임 라이브러리**이지 별도로 뜨는 서비스가 아니다. 1:1을 깨야 할 사례가 남지 않는다.
+
+### 1:1이라야 등급별로 다른 비용을 쓸 수 있다
+
+한 MCP가 등급을 섞어 들고 있으면 그 배포 전체에 중요 등급 기준을 적용해야 한다. 나뉘어 있으면
+`critical`에만 replica 여유와 PodDisruptionBudget을 주고 `standard`는 최소로 둘 수 있다.
+**분할의 실질 이득은 격리 자체보다 여기에 있다.**
+
+다만 배포를 나누는 것만으로 가용성이 생기지는 않는다. 같은 노드 배치, 같은 namespace의 쿼터,
+공통 Redis·클러스터 장애는 분할로 막히지 않는다. 등급 분리가 의미를 가지려면 replica 하한,
+PodDisruptionBudget, anti-affinity와 usable Tool snapshot 기반 readiness가 함께 가야 한다. Chart의
+`tiers` 설정과 `HelmDeploymentContractTest`가 test·prod의 정적 values를 검사하며, 실제 렌더링 결과는
+배포 파이프라인의 `helm lint`와 `helm template`이 확인한다.
+
+## 전제
+
+아래가 깨지면 이 결정을 재검토한다.
+
+1. Agent Builder는 MCP를 개별 등록하고, 한 Agent가 여러 MCP의 Tool을 사용할 수 있다.
+2. Tool 호출은 한 요청에 하나이며([ADR-0002](ADR-0002-tool-exposure-and-single-call.md)) 그 Tool을 가진 MCP로 직접 간다.
+3. 런타임에 공유되는 공통 Tool Service가 없다.
+
+## 영향
+
+- **배포 수 = Tool Service 수**다. 10~20개를 전제로 Helm values는 토폴로지를 한 파일에 모으고
+  배포 시 `deploymentKey`로 하나를 고른다. 배포가 늘어도 파일 수는 변하지 않는다.
+- 계약 v0.2 §7의 병합 규칙 중 bundle 간 이름 충돌(6번)과 `maxToolsTotal`(3번 후단)은 운영에서 발동하지 않는다.
+  규칙 자체는 계약에 남는다.
+- **Tool 이름의 전역 유일성은 Tool Service 책임으로 남는다.** 서로 다른 MCP가 같은 `namePrefix`를
+  쓰는 것을 MCP는 막지 못한다. 등급으로 나뉜 두 배포가 같은 업무 prefix(`processing.`)를 공유하는 것은
+  의도된 구성이며, 그 안에서 Tool 이름이 겹치지 않아야 한다.
+- Tool을 다른 등급으로 옮기면 그 Tool을 제공하는 **MCP endpoint가 바뀐다.** Agent Builder가 Tool 정보를
+  DB에 보관하므로 반영에는 재등록 또는 다음 `tools/list` 주기가 필요하다. 등급은 자주 바꾸지 않는 값으로 다룬다.
+- [ADR-0002](ADR-0002-tool-exposure-and-single-call.md)의 Tool 노출 상한 50개는 한 Agent가 여러 MCP에서
+  가져온 Tool의 **합계**에 적용된다. MCP를 나눈다고 상한이 늘지 않는다.
+
+## 채택하지 않은 대안
+
+**M:N — 한 MCP가 여러 Tool Service를 본다.** 배포 수는 줄지만 위의 격리 문제가 그대로 남는다.
+가용성이 분할의 목적이므로 목적과 수단이 어긋난다.
+
+**코드에서 bundle 1개를 강제한다.** `McpProperties`에 검증을 넣으면 다중 bundle 병합 코드가
+도달 불가능해진다. 전제 3이 깨질 때 되돌리는 비용이 커지고, 이미 작성·테스트된 경로를 죽은 코드로
+만든다. 1:1은 애플리케이션 불변식이 아니라 **배포 결정**이므로 배포 정의에서 잠그는 편이 맞다.
+이 선택은 검증 위치를 옮긴 것이지 검증을 뺀 것이 아니다.

docs/decisions/ADR-0008-shared-host-path-routing.md

@@ -0,0 +1,58 @@
+# 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 검증 계층이 중복되므로 채택하지 않았다.

docs/decisions/ADR-0009-container-handles-public-mcp-path.md

@@ -0,0 +1,41 @@
+# ADR-0009 컨테이너가 공개 MCP path를 직접 처리한다
+
+- 상태: Accepted
+- 결정일: 2026-08-05
+- 대체: [ADR-0008](ADR-0008-shared-host-path-routing.md)
+- 부분 대체됨: 결정 4는 [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.md)이 대체한다
+- 관련: [ADR-0007](ADR-0007-one-mcp-per-tool-service.md)
+
+> 결정 1·2·3·5는 유효하다. 공개 path를 rewrite하지 않고 컨테이너가 직접 처리한다는 원칙은 그대로다.
+> 결정 4의 "MCP 컨테이너 하나는 endpoint와 Tool Service를 각각 하나만 가진다"만 ADR-0013이 대체하며,
+> 지금은 `/mcp` + 동적 route key로 한 컨테이너가 N개 route와 route당 N개 Tool Service를 처리한다.
+
+## 배경
+
+Agent Builder는 `/mcp/core`, `/mcp/process`, `/mcp/information`처럼 sub path까지 포함한 URL을 각각의 MCP로 등록한다. 각 URL은 독립 MCP 컨테이너와 Tool Service에 연결된다. 공개 path를 OpenShift Route가 내부 `/mcp`로 바꾸면 Agent Builder가 등록한 경로와 컨테이너가 처리한 경로가 달라져 운영 추적과 설정 검증이 어려워진다.
+
+## 결정
+
+1. `deployments.<key>.publicPath`는 Agent Builder 등록 URL과 컨테이너 endpoint가 함께 사용하는 단일 정본이다.
+2. OpenShift Route는 host와 path로 독립 MCP Service만 선택하고 path를 rewrite하지 않는다.
+3. Helm ConfigMap이 `publicPath`를 `mcp.endpoint-path`로 주입하고, Controller와 Filter가 그 경로만 처리한다.
+4. MCP 컨테이너 하나는 endpoint와 Tool Service를 각각 하나만 가진다. 하나의 Java 프로세스에서 path별 Registry를 선택하지 않는다.
+5. 요청 body·header·Tool name은 컨테이너 선택에 관여하지 않는다.
+
+```text
+https://{host}/mcp/core        -> core MCP /mcp/core        -> core Tool Service
+https://{host}/mcp/process     -> process MCP /mcp/process  -> process Tool Service
+https://{host}/mcp/information -> information MCP /mcp/information -> information Tool Service
+```
+
+## 영향
+
+- 같은 host에서 여러 Service를 사용하므로 OpenShift Route의 path 기반 Service 선택은 유지한다.
+- rewrite annotation은 사용하지 않는다. access log와 애플리케이션 log가 같은 path를 본다.
+- `publicPath` 변경은 Route와 애플리케이션 endpoint를 함께 바꾸며 Agent Builder 등록 정보도 갱신해야 한다.
+- Registry snapshot, Redis namespace, readiness, connection pool과 장애 범위는 배포별로 계속 분리된다.
+- JSON-RPC payload와 Tool Service wire 계약은 바뀌지 않는다.
+
+## 대체한 결정
+
+ADR-0008의 공유 host와 독립 Deployment 원칙은 유지한다. 공개 path를 내부 `/mcp`로 rewrite한다는 부분만 이 ADR이 대체한다.

docs/decisions/ADR-0010-tool-service-manifest-owns-execution-endpoint.md

@@ -0,0 +1,47 @@
+# ADR-0010 Tool 실행 endpoint를 Tool Service 매니페스트가 선언한다
+
+- 상태: Accepted
+- 결정일: 2026-08-19
+- 기록: 2026-08-22. 구현 커밋 `6078852`를 기준으로 사후 작성했다.
+- 관련: [ADR-0006](ADR-0006-no-authentication-in-mcp.md), [ADR-0007](ADR-0007-one-mcp-per-tool-service.md)
+
+## 배경
+
+이전 설계에서 Tool 실행 주소는 MCP 배포 설정이 단독으로 소유했다. `mcp.bundles[].baseEndpoint` 뒤에 Tool name을 붙여 `POST {baseEndpoint}/{toolName}`을 만들었고, 매니페스트가 endpoint 성격의 값을 담고 있어도 읽지 않았다. **Tool Service가 반환한 어떤 값도 MCP가 요청을 보내는 대상을 바꿀 수 없다**는 것이 이 설계의 핵심이었고, `docs/architecture.md`, Tool Service 계약 v0.2, `ToolBundleDiscovery`의 Javadoc, `application.yml` 주석이 같은 문장을 반복해 고정하고 있었다.
+
+Portal registry를 Tool Server 목록의 원천으로 도입하면서 전제가 무너졌다. 포털은 route별로 Tool Server의 `serviceDomain`과 `manifestPath`만 제공한다. Tool 하나하나의 실행 경로는 포털이 모르고, MCP 배포 설정도 미리 알 수 없다. 기존 구조를 유지하려면 Tool을 추가하거나 경로를 바꿀 때마다 배포 설정의 endpoint 목록을 함께 고쳐야 했고, 이는 Tool Service의 배포 주기와 MCP의 배포 주기를 묶어 버린다.
+
+## 결정
+
+1. Tool 실행 주소는 Tool Service 매니페스트가 선언한다. MCP는 각 Tool의 top-level `endpoint`를 먼저 읽고, 없으면 `_meta.endpoint`를 사용한다.
+2. 둘 다 없거나 비어 있으면 그 Bundle 전체를 거부한다. Tool 하나의 누락이 나머지 Tool을 조용히 통과시키지 않는다.
+3. 상대 경로는 Portal registry가 제공한 `serviceDomain` 뒤에 붙여 절대 URL로 만든다. 이것이 운영에서 기대하는 형태다.
+4. 절대 URL은 Tool Service가 제공한 실행 주소 원천으로 그대로 사용한다. scheme이 HTTP(S)가 아니거나 host가 없으면 거부한다. 프로토콜 상대 주소(`//host/path`)와 개행이 섞인 값도 거부한다.
+5. `mcp.bundles[].baseEndpoint`는 더 이상 실행 주소의 정본이 아니다. 상대 경로를 해석하는 기준으로만 남으며, 절대 HTTP(S)여야 한다.
+6. `endpoint`는 내부 실행 정보이므로 `_meta`와 함께 제거해 `tools/list` 공개본에 내보내지 않는다.
+
+```text
+manifest endpoint = "/mcp/processing.contract.inquiry"   (운영 관례)
+  -> https://tool-cus.devjun.net/mcp/processing.contract.inquiry
+
+manifest endpoint = "https://other.example/tool"          (허용되지만 위험)
+  -> https://other.example/tool
+```
+
+## 영향
+
+- Tool을 추가하거나 실행 경로를 바꿀 때 MCP 배포 설정을 함께 바꾸지 않아도 된다. Tool Service가 매니페스트만 갱신하면 다음 refresh에 반영된다.
+- **신뢰 경계가 이동한다.** 이전에는 배포 설정이 outbound 대상을 봉인했으나, 이제는 매니페스트가 결정한다. 매니페스트가 절대 URL을 선언하면 MCP는 그 호스트로 요청을 보낸다.
+- 검증은 두 지점에 있다. discovery 시점에 `ToolBundleDiscovery`가 scheme·host·프로토콜 상대 주소·개행을 확인하고, 실행 시점에 `ToolRoutingService.validateEndpoint()`가 절대 HTTP(S)인지 다시 확인한다. 둘 다 **형식 검사이며 도메인 허용목록은 없다.** 따라서 매니페스트 원천의 신뢰성이 곧 outbound 대상의 신뢰성이다.
+- 네트워크 계층의 완화도 없다. `deploy/helm/mcp-server/templates/networkpolicy.yaml`은 `policyTypes: [Ingress]`만 선언하므로 outbound 목적지를 제한하지 않는다. 이 저장소가 제공하는 allowlist(`route.sourceAllowlist`, NetworkPolicy)는 모두 inbound 통제다.
+- [ADR-0006](ADR-0006-no-authentication-in-mcp.md)에 따라 MCP는 인증·인가를 하지 않는다. 그래서 "`GET /tool-manifest`를 NetworkPolicy로 MCP Server namespace에서만 접근 가능하게 한다"는 기존 요구가 선택적 권고가 아니라 이 결정의 전제 조건이 된다.
+- endpoint 검증 실패는 Bundle 전체 거부로 처리되고 직전 정상 snapshot이 유지되므로, 잘못된 매니페스트 배포가 기존 Tool 목록을 지우지는 않는다.
+- 계약 문서와 예제가 함께 갱신됐다. `docs/contracts/tool-service-mcp/examples/bundle-v0.2/manifest-response.json`이 `endpoint`를 포함하며, `ToolBundleContractExampleTest`가 문서와 구현의 일치를 고정한다.
+
+## 남은 위험
+
+- **도메인 허용목록 부재.** 매니페스트가 임의의 HTTP(S) 호스트를 지정할 수 있고, 애플리케이션 검사도 네트워크 정책도 이를 좁히지 않는다. 내부망 운영 전에 두 방향 중 하나를 정해야 한다.
+  - `mcp.tool-domains` 형태의 allowlist를 두고 절대 URL을 그에 대조한다.
+  - 절대 URL을 아예 거부하고 상대 경로만 허용해 목적지를 Portal registry의 `serviceDomain`으로 봉인한다. 운영 예제가 이미 상대 경로만 쓰고 있어 비용이 가장 낮고, 이전 설계의 "Tool Service가 호출 대상을 바꿀 수 없다"는 성질도 회복된다.
+- egress NetworkPolicy를 함께 검토한다. 위 두 방안 중 무엇을 택하든 애플리케이션 단독 방어보다 낫다.
+- 이 ADR은 기존 ADR을 대체하지 않는다. 뒤집힌 불변식이 ADR이 아니라 architecture 문서와 코드 주석에만 있었기 때문이다. 같은 일이 반복되지 않도록 실행 주소 관련 결정은 앞으로 이 ADR을 갱신하거나 후속 ADR로 남긴다.

docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md

@@ -0,0 +1,87 @@
+# ADR-0013 Tool Server endpoint 목록과 route 매핑의 원천은 Portal이 소유한다
+
+- 상태: Accepted
+- 결정일: 2026-08-22
+- 대체 결정: [ADR-0007](ADR-0007-one-mcp-per-tool-service.md) 전체, [ADR-0009](ADR-0009-container-handles-public-mcp-path.md) 결정 4
+- 관련: [ADR-0001](ADR-0001-stateless-execution-boundary.md) · [ADR-0005](ADR-0005-standard-tool-name.md) · [ADR-0010](ADR-0010-tool-service-manifest-owns-execution-endpoint.md) · [Portal-MCP 계약 v0.1](../contracts/portal-mcp/protocol-v0.1-registry.md)
+- 번호 주석: `feature/mcp-integration`이 ADR-0011·ADR-0012를 Tool inputSchema 정책에 쓰고 있어 그 번호를 비워 둔다. 같은 브랜치의 동명 ADR-0013과 이 문서는 같은 결정이다.
+
+## 배경
+
+[ADR-0007](ADR-0007-one-mcp-per-tool-service.md)은 MCP 배포 하나가 Tool Service 하나만 보게 하고, 어떤 Tool Service를 볼지를 `mcp.bundles`에 배포 시점으로 못박았다. 전제는 **매핑이 배포 시점에 확정된다**는 것이었다.
+
+내부망 운영은 그 전제를 따르지 않는다. route와 Tool Service의 매핑은 Portal이 관리하고, MCP는 기동 preload와 주기 refresh에서 Portal registry를 읽어 매핑을 받는다. 매핑이 바뀌어도 MCP를 다시 배포하지 않아야 한다.
+
+구현은 이미 이 구조였다. `PortalToolRegistryClient`가 registry 응답을 `Map<String, List<Bundle>>`(route → Tool Service 목록)로 유지하고, `McpRequestContextFactory`가 `/mcp/{routeKey}`에서 route를 뽑고, `ToolRegistryService`가 route별 snapshot을 들고 있다. 그런데 이 경로를 정당화하는 결정 문서가 없었고, 그 사이 ADR-0007은 `Accepted` 상태로 남아 코드와 정반대되는 내용을 현재 설계 근거처럼 제시하고 있었다.
+
+## 결정
+
+1. **Tool Server endpoint 목록과 route↔Tool Service 매핑의 원천은 Portal이다.** MCP는 기동 preload와 주기 refresh에서 Portal registry를 조회한다.
+2. **MCP 배포 하나가 N개 route를 서비스한다.** route key는 `/mcp/{routeKey}` URI에서만 결정한다.
+3. **route 하나에 N개 Tool Service가 붙을 수 있다.** 카탈로그 병합 단위는 route다.
+4. Portal은 **주소만** 소유한다. Tool 목록·schema·timeout은 Tool Service 매니페스트가 소유하고, Tool 실행 주소도 매니페스트가 정한다([ADR-0010](ADR-0010-tool-service-manifest-owns-execution-endpoint.md)).
+5. 요청 경로(`tools/list`, `tools/call`, route key 검증)는 in-memory snapshot만 읽는다. Portal은 요청 경로에 없다.
+6. 응답 모양과 실패 처리는 [Portal-MCP 계약 v0.1](../contracts/portal-mcp/protocol-v0.1-registry.md)이 정본이다.
+
+## 근거
+
+### 매핑이 동적이면 배포 축과 매핑 축을 겹칠 수 없다
+
+ADR-0007은 매핑을 배포 정의에 넣었다. Portal이 매핑을 소유하는 순간 **매핑 변경이 곧 배포 변경**이 되어 Portal을 원천으로 둔 의미가 사라진다. 원천이 Portal이면 배포는 매핑에 대해 중립이어야 하고, 그래서 한 배포가 N route를 서비스한다.
+
+### ADR-0007의 격리 논거는 층위별로 다르게 남는다
+
+ADR-0007이 지키려던 것은 가용성 등급별 격리였다. 이 구조에서 무엇이 남고 무엇이 사라지는지 숨기지 않고 적는다. 아래는 현재 main 코드 기준이다.
+
+| 층위 | 격리 | 근거 |
+|---|---|---|
+| route별 snapshot 보관 | **유지** | `ToolRegistryService`가 route별 snapshot을 따로 들고, 요청은 자기 route만 읽는다 |
+| route 안 N개 Tool Service의 **조회** | **유지** | `ToolBundleDiscovery`가 bundle마다 last-good을 따로 보관한다 |
+| route 안 카탈로그 **교체** | **없음** | 사용 가능한 성공본이 없는 Tool Service가 하나라도 있으면 그 route 전체 교체를 거부한다 |
+| route 간 **갱신** | **없음** | 아래 "남은 위험" 1번 참고. 한 route의 실패가 그 주기의 전 route 갱신을 막는다 |
+| 프로세스 자원(connection pool, thread, heap) | **없음** | 전 route가 공유한다 |
+| 배포·재기동·프로세스 장애 | **없음** | 전 route가 동시에 영향을 받는다 |
+
+**ADR-0007이 지키려던 가용성 등급별 물리 분리는 이 구조에서 성립하지 않는다.** 등급 요구가 다시 생기면 이 ADR을 재검토한다(전제 2).
+
+## 전제
+
+아래가 깨지면 이 결정을 재검토한다.
+
+1. route↔Tool Service 매핑의 관리 주체는 Portal이며, 매핑 변경이 MCP 재배포 없이 반영되어야 한다.
+2. 가용성 등급별 물리 분리 요구가 없다.
+3. 전 route의 Tool 총량과 매니페스트 조회 부하를 한 프로세스가 감당한다.
+4. Portal은 신뢰 경계 안에 있고 공개 네트워크에 노출되지 않는다.
+
+## 영향
+
+- route 없는 `/mcp` 호출은 `route key is required`로 거부된다. Agent Builder에는 route별 URL만 등록한다.
+- 등록되지 않은 route는 `McpRouteKeyValidator`가 controller 진입 전에 거부한다. 판단은 memory snapshot만 본다.
+- Tool 이름 유일성은 **route 안에서만** 검사한다. 서로 다른 route에 같은 이름이 있어도 거부하지 않는다.
+- `mcp.discovery.max-tools-total`은 전역이 아니라 **route 단위 상한**으로 동작한다. `merge()`가 route마다 호출되기 때문이다.
+- Portal 조회 실패는 목록을 비우지 않는다. memory를 유지하고, cold start일 때만 `mcp.redis.portal-registry-key`의 Redis fallback을 읽는다.
+- refresh 실패는 애플리케이션을 죽이지 않는다. `ToolRegistryRefreshScheduler`가 `RuntimeException`을 잡아 warn 로그만 남긴다.
+- [ADR-0009](ADR-0009-container-handles-public-mcp-path.md)의 "공개 path를 rewrite하지 않고 컨테이너가 직접 처리한다"는 유지된다. 다만 고정 `publicPath` 대신 `/mcp` + 동적 route로 처리하므로 결정 4만 이 ADR이 대체한다.
+- [ADR-0002](ADR-0002-tool-exposure-and-single-call.md)의 Tool 노출 상한 50개는 Agent 기준 합계이므로 바뀌지 않는다.
+
+## 남은 위험
+
+이 결정을 확정하면서 코드가 아직 따라오지 못한 지점이다. 셋 다 이 ADR의 의도와 어긋나므로 기록해 둔다.
+
+1. **route 간 갱신 격리가 없다.** `PortalToolRegistryClient.fetchAllTools()`는 `bundlesByRoute`를 순회하며 route마다 `merge()`를 호출하는데, 한 route가 `TOOL_REGISTRY_UNAVAILABLE`을 던지면 예외가 `fetchAllTools()` 밖으로 나가 그 주기의 갱신이 통째로 중단된다. 기존 snapshot은 남으므로 목록이 비지는 않지만, **Tool Service 하나의 장애가 무관한 route의 Tool 변경 반영까지 막는다.** route 단위로 예외를 격리하고 실패한 route만 결과에서 빼야 한다.
+2. **warm start가 Portal 모드에서 동작하지 않는다.** `ToolRegistryService.warmStartFromSharedCache()`는 route `""`의 Redis key만 읽는다. route가 이름을 갖는 이 구성에서는 아무것도 읽지 못해, 기동 직후 빈 목록 구간을 줄이는 효과가 사라진다.
+3. **readiness가 route별 상태를 노출하지 않는다.** `ToolCatalogHealthIndicator`는 `usableSnapshot`만 detail로 내보낸다. 어느 route가 준비됐고 어느 route가 비어 있는지 관제가 알 수 없다.
+
+## 남은 판단
+
+- `mcp.portal.route-key`가 선언돼 있으나 어떤 코드도 읽지 않는다. 결정 2에 따라 route는 URI에서만 오므로 이 속성은 제거 대상이다. 지금은 선언만 남아 있다.
+- `deploy/helm/`의 배포별 topology와 `HelmDeploymentContractTest`는 `mcp.bundles` 기반 1:1 구성의 계약이다. 코드에 그 경로가 남아 있어 local 검증과 1:1 배포에서는 유효하지만, 내부망 운영 대상인지 여부는 이 ADR이 정하지 않는다.
+- readiness를 route 단위로 세분화할지는 운영 관측 이후에 다시 본다.
+
+## 채택하지 않은 대안
+
+**ADR-0007을 유지하고 배포마다 자기 route만 조회한다.** 격리는 지키지만 route 추가가 배포 추가가 된다. Portal이 route 목록의 원천인데 배포 topology가 그 목록을 따라가야 하므로 순환이 생긴다.
+
+**`mcp.bundles`에 매핑을 하드코딩한다.** 매핑 변경마다 재배포가 필요해 전제 1과 충돌한다.
+
+**route별로 프로세스를 나누고 각자 Portal을 조회한다.** 자원 격리는 얻지만 Portal이 route 목록을 소유하는 이상 배포 수를 Portal이 정하게 되어, 운영 중 route 추가가 배포 파이프라인을 건드린다.

docs/decisions/README.md

@@ -0,0 +1,28 @@
+# Architecture Decision Records
+
+장기 설계 결정은 ADR로 관리한다.
+
+- `Proposed`: 초안. 검토 후 `Accepted`로 확정한다
+- `Accepted`: 확정된 결정
+- `Superseded`: 후속 ADR로 대체된 결정
+- `Rejected`: 검토했으나 채택하지 않은 결정
+
+결정이 변경되면 기존 ADR을 삭제하거나 의미를 덮어쓰지 않고 새 ADR에서 대체 관계를 기록한다.
+
+## 결정 목록
+
+| ADR | 제목 | 상태 |
+|---|---|---|
+| [ADR-0001](ADR-0001-stateless-execution-boundary.md) | Stateless 실행 책임 경계 | Accepted |
+| [ADR-0002](ADR-0002-tool-exposure-and-single-call.md) | Agent Builder Tool 노출 제한과 단일 Tool 호출 | Accepted |
+| [ADR-0003](ADR-0003-builder-tool-uid.md) | Builder Tool UID를 시스템 간 식별 키로 사용 | Superseded |
+| [ADR-0004](ADR-0004-execution-guardrails.md) | 300초, Raw Data, unsafe retry 실행 가드레일 | Accepted |
+| [ADR-0005](ADR-0005-standard-tool-name.md) | 표준 MCP Tool name을 실행 식별자로 사용 | Accepted |
+| [ADR-0006](ADR-0006-no-authentication-in-mcp.md) | MCP Server는 인증·인가를 하지 않는다 | Accepted |
+| [ADR-0007](ADR-0007-one-mcp-per-tool-service.md) | MCP 배포 하나는 Tool Service 하나만 본다 | Superseded |
+| [ADR-0008](ADR-0008-shared-host-path-routing.md) | 공유 host의 path를 독립 MCP 배포로 연결 | Superseded |
+| [ADR-0009](ADR-0009-container-handles-public-mcp-path.md) | 컨테이너가 공개 MCP path를 직접 처리 | Accepted |
+| [ADR-0010](ADR-0010-tool-service-manifest-owns-execution-endpoint.md) | Tool 실행 endpoint를 Tool Service 매니페스트가 선언 | Accepted |
+| [ADR-0013](ADR-0013-portal-owns-route-and-endpoint-registry.md) | Tool Server endpoint 목록과 route 매핑의 원천은 Portal | Accepted |
+
+ADR-0011과 ADR-0012는 비어 있다. `feature/mcp-integration`이 Tool inputSchema 정책 두 건에 그 번호를 쓰고 있어, 문서를 합칠 때 충돌하지 않도록 예약해 둔 것이다.

docs/discussions/DISC-20260710-001-agentbuilder-mcp-interface.md

@@ -0,0 +1,50 @@
+# DISC-20260710-001 Agent Builder-MCP 인터페이스 협의 기록
+
+- 상태: Closed / Historical
+- 회의 기준일: 2026-07-10
+- 원본: `20260710_AgentBuilder_MCP_통신규약분석협의_회의록.pptx`
+- 원본 위치: 저장소 외부의 통제된 AX HUB 업무 자료 영역
+- 보안 등급: 내부용
+
+이 문서는 당시 논의의 출발점만 보존한다. 현재 동작이나 미합의 사항의 정본으로 사용하지 않는다.
+
+## 현재 정본
+
+| 주제 | 정본 |
+|---|---|
+| 현재 Agent Builder wire 계약 | [동기 JSON v0.3](../contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md) |
+| Stateless 책임 | [ADR-0001](../decisions/ADR-0001-stateless-execution-boundary.md) |
+| 단일 Tool 실행 | [ADR-0002](../decisions/ADR-0002-tool-exposure-and-single-call.md) |
+| 실행 식별자 | [ADR-0005](../decisions/ADR-0005-standard-tool-name.md) |
+| Timeout·retry | [ADR-0004](../decisions/ADR-0004-execution-guardrails.md), [요청 시간 예산](../architecture.md#요청-시간-예산) |
+| 인증·인가 경계 | [ADR-0006](../decisions/ADR-0006-no-authentication-in-mcp.md) |
+| 아직 합의하지 않은 사항 | [extension-points.md](../extension-points.md) |
+
+## 회의 당시 확인한 방향
+
+1. MCP Server는 stateless 실행 계층이며 Tool을 자율 선택하지 않는다.
+2. Agent Builder가 LLM에 노출할 Tool을 선택하고 최대 50개로 제한한다.
+3. 요청 하나는 Tool 하나만 실행한다.
+4. 전체 상호작용은 300초를 넘기지 않는다.
+5. MCP는 3만 자라는 임의 기준으로 Tool 원문 응답을 자르지 않는다.
+6. 멱등성이 확인되지 않은 write/update Tool은 자동 retry하지 않는다.
+
+## 회의 이후 달라진 결정
+
+- 회의에서 검토한 Builder Tool UID는 MCP wire 식별자로 사용하지 않는다. 표준 MCP `name`을 사용한다.
+- 당시 예시의 `tool/call`, `toolId/contract`, `toolCalls[]`는 현재 계약이 아니다. 현재는 표준 `tools/call`의 `params.name`과 `params.arguments`를 사용한다.
+- MCP의 JWT decode·인증·인가 구현은 제거했다. NetworkPolicy가 호출자를 제한하고, Agent Builder와 Tool Service가 각자의 권한을 집행한다.
+- MCP 요청 deadline 기본값은 270초이고 Tool timeout 상한은 30초다. 300초는 Agent Builder를 포함한 전체 상한이다.
+- streaming 실행 경로는 제거했다. 기존 `Accept: application/json, text/event-stream`은 수용하지만 응답은 단일 `application/json`이다.
+
+## 남은 논의의 관리 위치
+
+오류 노출, cancellation, retry와 멱등성, 대용량 응답, 식별자 lifecycle, 운영 보완 사항은
+[extension-points.md](../extension-points.md)에서만 관리한다. 이 문서에는 이후 상태를 중복 기록하지 않는다.
+
+## 변경 이력
+
+| 일자 | 내용 |
+|---|---|
+| 2026-07-13 | 회의 자료 분석과 초기 변경 범위 기록 |
+| 2026-08-01 | 후속 ADR·현재 계약이 확정되어 역사 문서로 종결하고 정본 링크만 유지 |

docs/discussions/README.md

@@ -0,0 +1,14 @@
+# 협의 및 검토 기록
+
+이 디렉터리는 회의, 검토, 분석 당시의 사실과 쟁점을 보존한다.
+
+- 협의 기록은 최종 인터페이스 규격이 아니다.
+- 확정된 장기 설계 결정은 `../decisions/`의 ADR로 분리한다.
+- 현재 구현 계약과 목표 계약은 `../contracts/`에서 관리한다.
+- 후속 협의가 끝나면 원문을 덮어쓰지 않고 관련 ADR과 계약 문서 링크를 추가한다.
+
+## 기록 목록
+
+| ID | 제목 | 상태 | 기준일 |
+|---|---|---|---|
+| [DISC-20260710-001](DISC-20260710-001-agentbuilder-mcp-interface.md) | Agent Builder-MCP 인터페이스 협의 분석 | Closed / Historical | 2026-07-10 |

docs/extension-points.md

@@ -0,0 +1,104 @@
+# 미합의 항목과 확장 포인트
+
+이 문서는 **아직 결정되지 않았거나 운영 적용 전에 보완할 내용만** 관리한다. 현재 동작 설명은 [architecture.md](architecture.md), Agent Builder wire 계약은 [v0.3](contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md), Tool Service wire 계약은 [bundle 조회 v0.2](contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md), Portal registry wire 계약은 [registry v0.1](contracts/portal-mcp/protocol-v0.1-registry.md)이 정본이다.
+
+결정이 끝난 항목은 ADR 또는 현재 계약으로 옮기고 이 목록에서 제거한다. 목표안인 [Agent Builder-MCP v1 기준선](contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md)은 전체 payload가 승인되기 전까지 구현 근거가 아니다.
+
+## Agent Builder와 합의할 항목
+
+1. 여러 MCP protocol version 공존 시 fallback·upgrade와 공지 정책
+2. Tool name 변경·폐기 시 구·신 이름의 rolling 호환 기간과 Agent 재등록 정책
+3. Agent Builder가 `tools/list`를 다시 읽는 **주기**. 주기적으로 읽는다는 것까지는 확인됐고 값은 미정이다.
+   Agent Builder는 MCP 등록 시점에 Tool 정보를 자기 DB에 저장해 계속 사용하므로, Tool 변경이 실제로 반영되기까지
+   걸리는 시간은 **MCP의 매니페스트 갱신 주기 + Agent Builder의 조회 주기**다. 두 값을 각자 정하면 합이 얼마인지
+   아무도 모르게 되므로 함께 정한다
+4. Agent Builder 내부 UID와 표준 MCP `name`의 lifecycle. UID는 MCP wire 계약에 포함하지 않음
+5. Agent별 최대 50개 Tool 선별 로직과 권한 거부 시 Agent Builder가 사용자에게 보일 응답
+6. client disconnect 시 downstream cancellation 계약. 현재 MCP는 이미 시작한 Tool 호출을 취소하지 않는다
+   (계층별 budget 배분은 [architecture.md의 요청 시간 예산](architecture.md#요청-시간-예산)에서 확정)
+7. Tool 원본 오류·업무 코드·PII를 Agent Builder에 노출하거나 마스킹하는 기준
+8. response 크기, pagination/continuation과 대용량 결과 정책
+9. retry가 같은 업무 요청인지 판별하는 규칙과 `guid` 재사용 여부. 같은 `guid`를 재사용하기로 합의한 뒤에만 Tool Service의 멱등성 키로 사용
+10. `employee-no`·`virtual-employee-no`가 둘 다 없는 요청을 Agent Builder가 보낼 수 있는지, 언젠가 필수로 승격할지
+11. **주기 `tools/list`가 실패했을 때 DB의 Tool 정보를 어떻게 처리하는가.** 직전 목록을 유지하는지, 비우는지에 따라
+    MCP 재기동·배포 중 수십 초 공백이 Agent에 그대로 드러날 수 있다. 중요 등급 MCP의 replica 하한과 PodDisruptionBudget은
+    이 답과 무관하게 [ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)에서 이미 강제하지만,
+    답에 따라 비중요 등급의 배포 방식도 달라진다
+12. 같은 환경 host의 여러 공개 path를 Agent Builder에 등록·변경·폐기하는 절차와 주체. path 처리는
+    [ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)로 확정했지만, 배포 수가 Tool Service 수와 같아
+    10~20개 이상일 때의 등록 자동화는 미정이다
+
+인증 주체는 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)에서 확정했다. MCP는 인증·인가를 하지 않는다.
+
+## Tool Service와 합의할 항목
+
+1. `GET {manifestUrl}` 제공, 인증 방식과 NetworkPolicy 범위
+2. Tool name namespace, 변경·폐기 절차와 하위 호환 기간
+3. 허용할 JSON Schema 2020-12 keyword, 원격 `$ref`와 `format` 정책
+4. Tool별 timeout, 권한 scope, write Tool의 idempotency 보장
+5. `outputSchema`/`structuredContent` 도입 여부와 응답 검증 실패 의미
+6. 매니페스트 revision·ETag/304 및 즉시 refresh 알림의 필요성
+7. 사원 식별자 검증 방식: KMS 키 배포 범위(위조 방지 가능 여부), 동일 암호문 재사용 허용 여부, 만료·nonce 도입 여부.
+   [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md) 전제 2가 이 항목에 의존한다
+8. Tool 이름의 **전역 유일성 보장 방법**. 등급으로 나뉜 두 Tool Service가 같은 업무 `namePrefix`를 공유하므로
+   (`처리계-중요`와 `처리계-비중요`가 모두 `processing.`), 그 안에서 이름이 겹치지 않게 하는 것은 Tool Service 책임이다.
+   MCP는 자기 bundle의 prefix만 검증하며 다른 MCP의 이름을 알지 못한다([ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md))
+9. Tool의 **가용성 등급 분류 기준과 변경 절차**. 이 문서에서 위험도는 보안 정책이 아니라 중단 시 업무
+   영향도를 뜻한다. 등급이 바뀌면 그 Tool을 제공하는 MCP endpoint가 바뀌므로 Agent Builder 반영이
+   필요하다. 자주 바뀌지 않는 값으로 다룰 수 있는지 확인한다
+
+MCP와 Tool Service를 1:1로 묶는 결정은 [ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)에서 확정했다.
+
+현재 서버는 `tools/call` 결과를 `content[0].text`로만 반환한다. `structuredContent`를 지원하기 전까지 운영 매니페스트에는 `outputSchema`를 사용하지 않는다.
+
+## 플랫폼·DevOps와 확인할 항목
+
+배포 정의를 이 저장소가 어디까지 소유하는지 확정되지 않았다.
+GitOps 저장소도 ArgoCD Application도 아직 없어, 그때까지 [Helm Chart](../deploy/helm/mcp-server/)와
+push 방식 파이프라인(`.gitea/workflows/`)을 이 저장소가 **임시로** 소유한다.
+그 방식이 무엇을 포기하는지와 넘길 때 할 일은
+[deploy/README.md](../deploy/README.md#gitops-저장소가-없는-동안의-우회)가 정본이다.
+
+1. **Helm Chart를 어디에 두는가.** 앱 저장소인가 배포 전용 저장소인가
+2. 환경별 namespace 명명 규칙과 Agent Builder namespace.
+   후자는 Route를 우회한 Pod 직접 접근의 허용 출처이므로 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)의 전제와 직결된다
+3. 사내 Nexus에 `io.modelcontextprotocol.sdk:mcp-json-jackson2:2.0.0`과 Spring Boot 3.5.11가 있는가.
+   없으면 라이브러리 반입이 선행되어야 한다
+4. 사내 registry의 JDK 21 빌드·실행 이미지 이름. 현재 `Dockerfile`은 외부 이미지를 쓴다
+5. 소스 개행 표준(CRLF)과 `gradlew`의 관계.
+   shell script가 CRLF이면 Linux 컨테이너에서 실행되지 않으므로 예외 또는 우회 방식이 필요하다
+6. 환경별 실제 `global.mcpHost`, 인증서와 TLS termination 책임
+7. Agent Builder의 실제 고정 egress CIDR과 Route `ip_allowlist` 값
+8. 대상 OpenShift의 ingress namespace label과 IngressController endpoint publishing 방식이 Chart의 NetworkPolicy 전제와 맞는지
+9. **GitOps 저장소와 ArgoCD Application의 소유 주체와 생성 시점.** 그때까지 파이프라인이 클러스터
+   자격증명(`OCP_SERVER`·`OCP_TOKEN`)을 들고 있어야 하므로, 러너를 신뢰 경계 안에 두는 것이 전제다
+10. **운영 배포 모델을 `portal`로 확정하는가.** Chart는 `portal`과 `bundles`를 모두 렌더링하지만
+    [ADR-0013](decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md)이
+    [ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)을 대체했다. `bundles` 경로를 언제 삭제할지
+11. 사내 registry 주소·인증 방식과 `imagePullSecrets`에 넣을 Secret 이름
+12. `TOOL_SERVER_API_KEY`를 담을 Secret의 소유 주체와 이름. Chart는 `toolService.apiKeySecret`으로 이름만 참조한다
+13. VM docker compose 배포(`.gitea/workflows/deploy.yaml`)를 계속 쓸지, 그 `deploy.sh`를 저장소로 가져올지.
+    현재 스크립트는 러너의 `/home/ubuntu/apps/prd-dap-gateway/`에 있어 이 저장소가 내용을 모른다
+
+## 운영 적용 전 필수 보완
+
+| 영역 | 현재 상태 | 필요한 결정·구현 |
+|---|---|---|
+| egress | 절대 HTTP(S) 여부만 검증 | host allowlist, redirect·DNS rebinding 방어, mTLS/NetworkPolicy |
+| 장애 격리 | timeout과 last-good 제공 | 측정 후 bulkhead·circuit breaker·제한적 retry 결정 |
+| 관측성 | 경계 로그와 bundle Actuator 제공 | Micrometer/OpenTelemetry/SIEM 지표와 경보 기준 |
+| 감사 | 일반 애플리케이션 로그만 제공 | 보존 대상·기간·암호화·위변조 방지·유실 정책 확정 후 durable sink |
+| 용량 | request body 1 MiB 제한 | response 크기, JSON depth, 동시 실행 수, connection pool 부하 기준 |
+| Redis | 요청 경로 밖의 선택 cache. Tool snapshot cache는 route별 key(`key-prefix:identity:v2:route:{routeToken}`)로 분리하고, Portal registry fallback key와도 분리한다. Portal registry fallback key 기본값은 `axhub:mcp:portal-registry`이며 운영에서는 `mcp.redis.portal-registry-key`로 포털 저장 key와 반드시 맞춘다. | Redis 사용 여부, key namespace·schema version·TTL·공유 범위, TLS/ACL, Sentinel/Cluster, rolling upgrade 정책 |
+| 종료 | Spring graceful shutdown | 신규 요청 차단과 진행 중 Tool 호출 drain 검증 |
+| 가용성 | test·prod critical의 replica·PDB·노드 분산 values를 정적 테스트가 검사하고 usable snapshot으로 readiness 판정. 공개 Route도 배포마다 분리 | `helm lint/template`, 노드 분산 실제 확인, 배포 창 분리, 쿼터 산정. 공유 ingress·DNS 장애는 path 분할로 막히지 않는다 |
+
+## 코드 확장 경계
+
+- 새 MCP method: `McpMethodHandlerRegistry.Handler` 구현 하나를 추가하고 SDK method 상수를 사용한다.
+- Tool metadata: 새 원천을 만들지 말고 local fixture 또는 Tool Service 매니페스트 계약을 확장한다.
+- Tool protocol: 실제 두 번째 protocol이 필요할 때만 `ToolClient` 구현을 추가한다.
+- 인증: 추가하지 않는다. 필요가 생기면 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)을 대체하는 ADR을 먼저 쓴다.
+- 규제 감사: 저장·전달 보장이 합의된 뒤 HTTP/Tool 경계에 durable sink를 연결한다.
+
+새 interface, mapper, DTO, cache 계층은 현재 경계로 해결할 수 없는 요구가 확인되기 전에는 추가하지 않는다.

docs/mcp-java-sdk-adoption.md

@@ -0,0 +1,145 @@
+# MCP Java SDK 선택적 도입 설계
+
+- 상태: 적용 완료
+- 적용 버전: `io.modelcontextprotocol.sdk:mcp-json-jackson2:2.0.0`
+- 대상 런타임: Java 21, Spring Boot 3.5.11
+- 적용 원칙: 외부 계약과 AX HUB 고유 실행 경계는 유지하고, 표준 프로토콜 모델과 JSON Schema 검증만 SDK에 위임한다.
+- 이 SDK가 끌어오는 전이 의존 전체와 라이선스는 [SBOM](sbom/README.md)이 정본이다.
+
+## 1. 도입 결론
+
+이 프로젝트는 MCP Java SDK의 서버 Starter나 HTTP transport를 사용하지 않는다. 현재 `/mcp` endpoint는
+Agent Builder와 합의한 동기 JSON, `Mcp-Session-Id`, protocol version HTTP 400, trace 계약을 이미 구현하고
+있으므로 SDK transport를 함께 활성화하면 같은 endpoint에 두 프로토콜 처리 경로가 생길 수 있기 때문이다.
+
+대신 실제 사용 모듈인 `mcp-json-jackson2`에 직접 의존한다. 이 모듈이 `mcp-core`를 전이 제공하므로 aggregate artifact를 별도로 선언하지 않는다. 적용 범위는 다음과 같다.
+
+| 적용 영역 | SDK 타입/기능 | 기존 코드에서의 사용 위치 |
+|---|---|---|
+| MCP method 이름 | `McpSchema.METHOD_*` | handler와 protocol validator |
+| JSON-RPC 버전과 표준 오류 번호 | `McpSchema.JSONRPC_VERSION`, `McpSchema.ErrorCodes` | request parser, response, error enum |
+| initialize 결과 | `McpSchema.InitializeResult`, `Implementation`, `ServerCapabilities` | `InitializeHandler` |
+| tools/list 결과 | `McpSchema.ListToolsResult`, `Tool` | `ToolsListHandler` |
+| tools/call 결과 | `McpSchema.CallToolResult`, `TextContent` | `ToolsCallHandler` |
+| Tool arguments schema 검증 | `DefaultJsonSchemaValidator` | `ToolArgumentValidator` |
+
+이 서버는 Spring AI API를 사용하지 않으므로 Spring AI BOM을 두지 않는다. MCP SDK 버전은 `2.0.0`으로 직접
+고정한다. Starter를 추가하지 않았기 때문에 Spring AI MCP auto-configuration, 별도 `/mcp` mapping,
+SSE/Streamable transport bean은 생성되지 않는다.
+
+## 2. 전체 요청 경계
+
+```text
+Agent Builder
+  -> 기존 McpExchangeFilter
+     - 호출자 header 추출 (guid, request-id, session, 사원 식별자)
+     - guid, x-request-id, MCP Session correlation
+     - protocol version HTTP header 검증
+     - HTTP/Tool 경계 trace log
+  -> 기존 McpController
+  -> 기존 JsonRpcRequestParser / McpMethodHandlerRegistry
+  -> Handler
+     - initialize: SDK InitializeResult 생성
+     - tools/list: 기존 Registry metadata -> SDK Tool/ListToolsResult
+     - tools/call: 기존 실행 결과 -> SDK CallToolResult/TextContent
+  -> 기존 JsonRpcResponse envelope
+  -> application/json 응답
+```
+
+Tool 실행 경로는 다음과 같다.
+
+```text
+tools/call
+  -> 기존 ToolsCallHandler params 검증
+  -> 기존 ToolRegistryService
+  -> 기존 basic contract + SDK JSON Schema 검증
+  -> SDK JSON Schema 2020-12 검증
+  -> 기존 ToolRoutingService / ToolClient
+  -> 기존 timeout·correlation 처리 (MCP는 인증·인가하지 않음)
+```
+
+SDK 모델은 handler의 표준 MCP payload를 만드는 데만 사용한다. SDK server가 요청을 dispatch하거나 Tool Service를
+호출하지 않는다.
+
+## 3. SDK와 기존 소스의 책임 경계
+
+### SDK에 위임한 책임
+
+- 표준 MCP method 문자열과 JSON-RPC 상수
+- initialize, Tool definition, list result, call result의 표준 필드 구조
+- text content의 `type: "text"` 표현
+- JSON Schema 2020-12 기반 arguments 검증과 schema 컴파일 재사용
+- `minLength`, `pattern`, `enum`, `additionalProperties`, 중첩 객체 등 기존 기본 validator보다 넓은 schema keyword
+
+### 기존 구현이 계속 소유하는 책임
+
+- `/mcp` HTTP mapping과 항상 `application/json`을 반환하는 transport 정책
+- `Accept: application/json, text/event-stream` 수용
+- `Mcp-Session-Id` 생성과 stateless correlation
+- `MCP-Protocol-Version` 누락·미지원 시 HTTP 400 처리
+- JSON-RPC parse/invalid request/invalid params의 현재 오류 envelope와 메시지
+- Tool Service 매니페스트 pull, Redis/memory fallback, local fixture
+- Tool endpoint/timeout/version 진단 정보와 dynamic metadata
+- 호출자 header 추출·검증과 Tool Service bypass 정책 (인증·인가는 하지 않음, ADR-0006)
+- `guid`·`x-request-id` 전파, 요청 context 정리, HTTP/Tool 경계 로그
+- Tool 선택 금지, exactly-one Tool 실행, outbound routing과 업무 오류 변환
+
+## 4. 기존 계약 보존 방법
+
+| 위험 | 회피 방식 |
+|---|---|
+| SDK Starter가 기존 `/mcp`와 충돌 | Starter를 사용하지 않고 core 모델과 Jackson 2 validator만 의존 |
+| SDK가 Tool 검증 실패를 `isError=true`로 바꿈 | SDK server handler를 사용하지 않고 검증 실패를 기존 `-32602 Invalid params`로 변환 |
+| 기존 required/type 오류 문구 변경 | 공개된 기본 검증을 SDK보다 먼저 실행해 기존 메시지를 그대로 유지 |
+| `Mcp-Session-Id`/protocol header 동작 변경 | 기존 filter, controller, validator를 유지 |
+| `tools/call` 결과 필드 위치 변경 | 직렬화 계약 테스트로 `content[0]._meta.searchTime`과 `isError`를 고정 |
+| local tools/list 공개 필드 누락 | SDK `Tool` 변환 전 `_meta`만 제거하고 title/outputSchema/annotations를 직렬화 비교 |
+| Registry의 기존 Tool에 inputSchema 누락 | SDK 필수 조건을 만족하는 빈 object schema로 정규화 |
+| dynamic Registry를 annotation Tool로 고정 | `@McpTool`을 사용하지 않고 요청마다 기존 Registry service를 조회 |
+| correlation·Trace 기능이 SDK 내부로 사라짐 | transport와 실행 orchestration을 기존 코드에 유지 |
+| SDK 업그레이드로 wire payload 변경 | SDK 버전을 명시하고 initialize/list/call golden serialization 테스트를 통과한 경우에만 변경 |
+
+## 5. JSON Schema 검증 정책
+
+SDK 검증은 `ToolExecutionService`가 Registry 기반 argument validation을 수행하는 위치에 연결했다.
+검증 순서는 다음과 같다.
+
+1. 기존 object/required/basic type 검증으로 공개된 오류 문구를 보존한다.
+2. SDK JSON Schema validator로 나머지 2020-12 keyword를 검증한다.
+3. 실패하면 Tool Service를 호출하지 않고 기존 `JsonRpcException(INVALID_PARAMS)`으로 종료한다. SDK 원문 오류는
+   입력값을 포함할 수 있으므로 외부에는 `arguments do not match inputSchema`만 반환한다.
+
+SDK validator는 Spring singleton으로 한 번 생성되며 동일 schema의 컴파일 결과를 재사용한다. Registry가 제공하는
+schema 자체의 허용 dialect와 `$ref` 원격 해석 정책은 운영 Registry 계약으로 별도 통제해야 한다.
+
+## 6. 의도적으로 도입하지 않은 SDK 기능
+
+- `spring-ai-starter-mcp-server-webmvc`
+- SDK sync/async/stateless server와 transport provider
+- SSE 또는 Streamable HTTP 응답
+- SDK authorization/security 구현
+- annotation 기반 정적 `@McpTool` 등록
+- SDK가 소유하는 Tool lifecycle, list-changed notification
+- Resources, Prompts, Sampling, Elicitation
+
+이 기능들은 현재 요구사항을 해결하지 않거나 기존 계약과 중복된다. 실제 필요가 생기면 별도 ADR과 Agent Builder
+contract test를 먼저 추가한다.
+
+## 7. 변경 및 검증 기준
+
+SDK 버전을 올릴 때는 다음을 모두 확인한다.
+
+1. Spring Boot/Java/MCP Java SDK 조합의 dependency resolution
+2. SDK `McpSchema` 필드와 Jackson 2 직렬화 변경 여부
+3. initialize, tools/list, tools/call 성공·실패 JSON의 기존 예제 일치
+4. JSON-RPC 오류 code/message/data 및 HTTP status
+5. `Accept`에 `text/event-stream`이 있어도 JSON 응답을 유지하는지
+6. `Mcp-Session-Id`, protocol version, `guid`, `x-request-id` 전파
+7. local profile, Registry 장애 fallback, Redis 비필수 동작
+8. `.\gradlew.bat clean test`
+
+참고:
+
+- [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk)
+- [Spring AI 2.0 Upgrade Notes](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)
+- [Spring AI MCP Server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)

docs/sbom/AXHUB_MCP_Tool_Service_SBOM_CycloneDX1.5.json

@@ -0,0 +1,706 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "serialNumber": "urn:uuid:dd2dbf54-3ff5-57b2-bc28-765721359457",
+  "version": 1,
+  "metadata": {
+    "timestamp": "2026-08-18T00:00:00Z",
+    "component": {
+      "type": "application",
+      "bom-ref": "pkg:maven/io.shinhanlife.dap.biz.mcp/ax-hub-mcp-server@0.1.0",
+      "group": "io.shinhanlife.dap.biz.mcp",
+      "name": "ax-hub-mcp-server",
+      "version": "0.1.0",
+      "description": "AXHUB MCP&Tool Service 공통 스택 (Java 21 / Spring Boot 3.5.11)",
+      "purl": "pkg:maven/io.shinhanlife.dap.biz.mcp/ax-hub-mcp-server@0.1.0"
+    },
+    "properties": [
+      {
+        "name": "axhub:scope",
+        "value": "MCP Java SDK 2.0.0과 그 런타임 전이 의존, 그리고 빌드 환경. MCP Server와 Tool Service의 공통 스택에 적용된다"
+      },
+      {
+        "name": "axhub:source",
+        "value": "build.gradle + Gradle 로컬 캐시의 실제 pom/jar 판독"
+      }
+    ]
+  },
+  "components": [
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/io.modelcontextprotocol.sdk/mcp-json-jackson2@2.0.0",
+      "name": "mcp-json-jackson2",
+      "version": "2.0.0",
+      "publisher": "Anthropic",
+      "description": "MCP JSON 직렬화 · JSON Schema 2020-12 검증 구현체",
+      "scope": "required",
+      "purl": "pkg:maven/io.modelcontextprotocol.sdk/mcp-json-jackson2@2.0.0",
+      "group": "io.modelcontextprotocol.sdk",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "2f9b7d72acb74d854589b7f22477aaaef4d84083"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "58951bd4b1c5a385af5b146b5582bc457475e2933a220d2fd63c1aed4435d1fc6f585b068dc752170d58890bd4036947c82afa8686f872560c2d148d270654fe"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT",
+            "url": "https://opensource.org/licenses/MIT"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/modelcontextprotocol/java-sdk"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "직접 선언 (build.gradle implementation)"
+        },
+        {
+          "name": "axhub:note",
+          "value": "이 SBOM의 유일한 직접 선언 오픈소스"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/io.modelcontextprotocol.sdk/mcp-core@2.0.0",
+      "name": "mcp-core",
+      "version": "2.0.0",
+      "publisher": "Anthropic",
+      "description": "MCP 표준 프로토콜 모델(McpSchema) · JSON-RPC 상수",
+      "scope": "required",
+      "purl": "pkg:maven/io.modelcontextprotocol.sdk/mcp-core@2.0.0",
+      "group": "io.modelcontextprotocol.sdk",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "fd49feda3b9e6914a46a56ccd4a8f70e35156898"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "44dcf26bddfaa4757d7b2d765cd48745a0130fbc074ebb59565a03f66c92f387073d109c54fe62e1a68f3df71629928df973f6adc8abe75d4f5cf76b1d1f6f0b"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT",
+            "url": "https://opensource.org/licenses/MIT"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/modelcontextprotocol/java-sdk"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-json-jackson2"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.networknt/json-schema-validator@2.0.0",
+      "name": "json-schema-validator",
+      "version": "2.0.0",
+      "publisher": "Network New Technologies Inc.",
+      "description": "JSON Schema draft 2020-12 검증 엔진 (Tool inputSchema 검증)",
+      "scope": "required",
+      "purl": "pkg:maven/com.networknt/json-schema-validator@2.0.0",
+      "group": "com.networknt",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "bc7c4ddf322d1295e3c296f28a9966590e6dea20"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "bc033e50c66e72ad89df6442532b614fc984386aad2da68daaa098d81ac5a4a82933d0783d3f1a0ed5fe80e3bca6091d72acf5d7dcadcb50c3153100edcf334b"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/networknt/json-schema-validator"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-json-jackson2"
+        },
+        {
+          "name": "axhub:note",
+          "value": "optional인 joni·graal-js를 해석하지 않아 pattern 검증에 JDK 정규식 엔진을 사용한다"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.ethlo.time/itu@1.14.0",
+      "name": "itu",
+      "version": "1.14.0",
+      "publisher": "ethlo (Morten Haraldsen)",
+      "description": "RFC 3339 date/date-time 파싱 — json-schema-validator의 format 구현용",
+      "scope": "required",
+      "purl": "pkg:maven/com.ethlo.time/itu@1.14.0",
+      "group": "com.ethlo.time",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "c0f9f9d4f4404787e992ab3af5ae95f2fad79e47"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "aa69a6af3a7123eb41425bbaf6834e16dc3323172709e2338b8a21b970fd21333d996515f42da4aa0225251e30542ad7d9c8332bdf7d62ed96b42fadc8a1520d"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/ethlo/itu"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← json-schema-validator"
+        },
+        {
+          "name": "axhub:note",
+          "value": "SDK 검증기가 format을 단언하지 않아 런타임에 호출되지 않는다. classpath에는 포함되므로 수록"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.fasterxml.jackson.dataformat/jackson-dataformat-yaml@2.19.4",
+      "name": "jackson-dataformat-yaml",
+      "version": "2.19.4",
+      "publisher": "FasterXML, LLC",
+      "description": "YAML 형식 schema 로딩 (validator 부가 기능)",
+      "scope": "required",
+      "purl": "pkg:maven/com.fasterxml.jackson.dataformat/jackson-dataformat-yaml@2.19.4",
+      "group": "com.fasterxml.jackson.dataformat",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "500956daea0869bf753b94fdaa77e5dc99847d79"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "42cf2edacf2dea3c0616991a9a945c6e3e44dcb719918e76e6babae55601454397a1667bf75b7d55c74f96a7da7c0d9f60a0f4be60f84fd405fa31eb144f9b92"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/FasterXML/jackson-dataformats-text"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← json-schema-validator"
+        },
+        {
+          "name": "axhub:note",
+          "value": "Spring Boot 3.5.11 BOM이 2.19.4로 정렬"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/io.projectreactor/reactor-core@3.7.16",
+      "name": "reactor-core",
+      "version": "3.7.16",
+      "publisher": "VMware (Project Reactor)",
+      "description": "mcp-core가 참조하는 리액티브 타입 제공",
+      "scope": "required",
+      "purl": "pkg:maven/io.projectreactor/reactor-core@3.7.16",
+      "group": "io.projectreactor",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "dc7f2ba3c4fbc69678937dfe1ad45264d8a1c7be"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "f0313eedd03acee06e7e38a915ecb8060d6996ffafbd05afeff4c7cdeb239e022b65f8f721290e228d5c30180d069a417cb40c3f782b643508fa0b64d11de10f"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/reactor/reactor-core"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-core"
+        },
+        {
+          "name": "axhub:note",
+          "value": "pom 요청 3.7.0 → reactor-bom 2024.0.15의 3.7.16"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/org.reactivestreams/reactive-streams@1.0.4",
+      "name": "reactive-streams",
+      "version": "1.0.4",
+      "publisher": "Reactive Streams SIG",
+      "description": "리액티브 스트림 표준 인터페이스",
+      "scope": "required",
+      "purl": "pkg:maven/org.reactivestreams/reactive-streams@1.0.4",
+      "group": "org.reactivestreams",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "3864a1320d97d7b045f729a326e1e077661f31b7"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "cdab6bd156f39106cd6bbfd47df1f4b0a89dc4aa28c68c31ef12a463193c688897e415f01b8d7f0d487b0e6b5bd2f19044bf8605704b024f26d6aa1f4f9a2471"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT-0",
+            "url": "https://spdx.org/licenses/MIT-0.html"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "http://www.reactive-streams.org/"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← reactor-core"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4",
+      "name": "jackson-databind",
+      "version": "2.19.4",
+      "publisher": "FasterXML, LLC",
+      "description": "JSON 데이터 바인딩",
+      "scope": "required",
+      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4",
+      "group": "com.fasterxml.jackson.core",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "7a39bf9257b726b90b80f27fa3f5174bc75162a5"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "02a80c97ea12874f66802cb2c8909e5358639b41050bd04da495c0ee8db496a0d9d609a3c62a1dca7cbd89681bf340d6f6dbc507d4f21602aa1a7f31b2285ba8"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/FasterXML/jackson-databind"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-json-jackson2, json-schema-validator"
+        },
+        {
+          "name": "axhub:note",
+          "value": "pom 요청 2.20.1 / 2.18.3 → Spring Boot 3.5.11 BOM의 2.19.4로 정렬"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.19.4",
+      "name": "jackson-core",
+      "version": "2.19.4",
+      "publisher": "FasterXML, LLC",
+      "description": "JSON 스트리밍 파서/생성기",
+      "scope": "required",
+      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.19.4",
+      "group": "com.fasterxml.jackson.core",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "a720ca9b800742699e041c3890f3731fe516085e"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "987de559d452fb78557c038a02289454cf1354985bdb79df1087c5bc33db35c9510ee6c1c1dd3816e220a86a35d19820a8c32176a7d4fc4e5d3c7e65df5536d4"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/FasterXML/jackson-core"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← jackson-databind"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.19.4",
+      "name": "jackson-annotations",
+      "version": "2.19.4",
+      "publisher": "FasterXML, LLC",
+      "description": "JSON 바인딩 애노테이션",
+      "scope": "required",
+      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.19.4",
+      "group": "com.fasterxml.jackson.core",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "bbb09b1e7f7f5108890270eb701cb3ddef991c05"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "22a2ce8150c380b9dc00bfbdd026f26e626f483e8ceebfbb2087e9abd63462781daf4e18ca09543a7d0eb7b5c5625f02332d3251e29c2abc6016d69a7194a565"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://github.com/FasterXML/jackson-annotations"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-core, jackson-databind"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/org.slf4j/slf4j-api@2.0.17",
+      "name": "slf4j-api",
+      "version": "2.0.17",
+      "publisher": "QOS.ch",
+      "description": "로깅 파사드",
+      "scope": "required",
+      "purl": "pkg:maven/org.slf4j/slf4j-api@2.0.17",
+      "group": "org.slf4j",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "d9e58ac9c7779ba3bf8142aff6c830617a7fe60f"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "9a3e79db6666a6096a3021bb2e1d918f30f589d8de51d6b600f8ebd92515a510ae2d8f87919cc2dfa8365d64f10194cac8dfa0fb950160eef0e9da06f6caaeb9"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT",
+            "url": "https://opensource.org/licenses/MIT"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://www.slf4j.org/"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← mcp-core, json-schema-validator"
+        },
+        {
+          "name": "axhub:note",
+          "value": "pom 요청 2.0.16 → Spring Boot 3.5.11 BOM의 2.0.17로 정렬"
+        }
+      ]
+    },
+    {
+      "type": "library",
+      "bom-ref": "pkg:maven/org.yaml/snakeyaml@2.4",
+      "name": "snakeyaml",
+      "version": "2.4",
+      "publisher": "SnakeYAML",
+      "description": "YAML 파서 (jackson-dataformat-yaml 백엔드)",
+      "scope": "required",
+      "purl": "pkg:maven/org.yaml/snakeyaml@2.4",
+      "group": "org.yaml",
+      "hashes": [
+        {
+          "alg": "SHA-1",
+          "content": "e0666b825b796f85521f02360e77f4c92c5a7a07"
+        },
+        {
+          "alg": "SHA-512",
+          "content": "1573717e2c47868515cbed5265a6f77ebec23a0b5c6376ac18b9f5c2335beb65d4c68d2073d50143d59a60141980be8db1e493a85d7c78106cdb94a52e8361d2"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://bitbucket.org/snakeyaml/snakeyaml"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "전이 ← jackson-dataformat-yaml"
+        }
+      ]
+    },
+    {
+      "type": "platform",
+      "bom-ref": "pkg:generic/jdk@21.0.5",
+      "name": "jdk",
+      "version": "21.0.5",
+      "publisher": "Eclipse Adoptium (Temurin)",
+      "description": "언어/실행 환경 — Java 21 toolchain",
+      "scope": "optional",
+      "purl": "pkg:generic/jdk@21.0.5",
+      "licenses": [
+        {
+          "expression": "GPL-2.0-only WITH Classpath-exception-2.0"
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://adoptium.net/temurin/releases/?version=21"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "build.gradle java.toolchain (vendor=ADOPTIUM)"
+        },
+        {
+          "name": "axhub:note",
+          "value": "표준가이드의 openjdk21u-jdk_x64_windows_hotspot_21.0.5 기준. Classpath Exception이 있어 이 JDK로 실행하는 애플리케이션에는 소스 공개 의무가 없다"
+        }
+      ]
+    },
+    {
+      "type": "application",
+      "bom-ref": "pkg:generic/gradle@8.14.3",
+      "name": "gradle",
+      "version": "8.14.3",
+      "publisher": "Gradle Inc.",
+      "description": "빌드 도구 (gradle wrapper 고정)",
+      "scope": "optional",
+      "purl": "pkg:generic/gradle@8.14.3",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "bd71102213493060956ec229d946beee57158dbd89d0e62b91bca0fa2c5f3531"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "Apache-2.0",
+            "url": "https://www.apache.org/licenses/LICENSE-2.0"
+          }
+        }
+      ],
+      "externalReferences": [
+        {
+          "type": "website",
+          "url": "https://gradle.org/"
+        }
+      ],
+      "properties": [
+        {
+          "name": "axhub:dependencyPath",
+          "value": "gradle/wrapper/gradle-wrapper.properties"
+        },
+        {
+          "name": "axhub:note",
+          "value": "SHA-256은 wrapper의 distributionSha256Sum 값"
+        }
+      ]
+    }
+  ],
+  "dependencies": [
+    {
+      "ref": "pkg:maven/io.shinhanlife.dap.biz.mcp/ax-hub-mcp-server@0.1.0",
+      "dependsOn": [
+        "pkg:maven/io.modelcontextprotocol.sdk/mcp-json-jackson2@2.0.0"
+      ]
+    },
+    {
+      "ref": "pkg:maven/io.modelcontextprotocol.sdk/mcp-json-jackson2@2.0.0",
+      "dependsOn": [
+        "pkg:maven/io.modelcontextprotocol.sdk/mcp-core@2.0.0",
+        "pkg:maven/com.networknt/json-schema-validator@2.0.0",
+        "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4"
+      ]
+    },
+    {
+      "ref": "pkg:maven/io.modelcontextprotocol.sdk/mcp-core@2.0.0",
+      "dependsOn": [
+        "pkg:maven/io.projectreactor/reactor-core@3.7.16",
+        "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.19.4",
+        "pkg:maven/org.slf4j/slf4j-api@2.0.17"
+      ]
+    },
+    {
+      "ref": "pkg:maven/com.networknt/json-schema-validator@2.0.0",
+      "dependsOn": [
+        "pkg:maven/com.ethlo.time/itu@1.14.0",
+        "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4",
+        "pkg:maven/com.fasterxml.jackson.dataformat/jackson-dataformat-yaml@2.19.4",
+        "pkg:maven/org.slf4j/slf4j-api@2.0.17"
+      ]
+    },
+    {
+      "ref": "pkg:maven/com.ethlo.time/itu@1.14.0",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:maven/com.fasterxml.jackson.dataformat/jackson-dataformat-yaml@2.19.4",
+      "dependsOn": [
+        "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4",
+        "pkg:maven/org.yaml/snakeyaml@2.4"
+      ]
+    },
+    {
+      "ref": "pkg:maven/io.projectreactor/reactor-core@3.7.16",
+      "dependsOn": [
+        "pkg:maven/org.reactivestreams/reactive-streams@1.0.4"
+      ]
+    },
+    {
+      "ref": "pkg:maven/org.reactivestreams/reactive-streams@1.0.4",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.19.4",
+      "dependsOn": [
+        "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.19.4",
+        "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.19.4"
+      ]
+    },
+    {
+      "ref": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.19.4",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.19.4",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:maven/org.slf4j/slf4j-api@2.0.17",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:maven/org.yaml/snakeyaml@2.4",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:generic/jdk@21.0.5",
+      "dependsOn": []
+    },
+    {
+      "ref": "pkg:generic/gradle@8.14.3",
+      "dependsOn": []
+    }
+  ]
+}

docs/sbom/README.md

@@ -0,0 +1,82 @@
+# SBOM — AXHUB MCP&Tool Service
+
+- 산출물: `AXHUB_MCP_Tool_Service_SBOM_CycloneDX1.5.json` (CycloneDX 1.5 정본), `AXHUB_MCP_Tool_Service_SBOM_CycloneDX1.5.xlsx` (검토용)
+- 대상: AXHUB MCP Server와 Tool Service의 공통 스택 (Java 21 / Spring Boot 3.5.11)
+- 산출 기준 빌드: `ax-hub-mcp-server@0.1.0`
+- 생성 기준일: 2026-08-18
+
+## 대상 범위
+
+MCP Server와 Tool Service는 같은 기술 스택과 같은 MCP SDK를 쓰므로 이 SBOM을 공통으로 적용한다.
+`build.gradle`이 직접 선언한 오픈소스는 `io.modelcontextprotocol.sdk:mcp-json-jackson2:2.0.0`
+하나이며, 이 SBOM은 그 **런타임 전이 의존 전체**와 **빌드 환경**을 담는다. Spring Boot starter
+계열(web / validation / data-redis / actuator)은 glow f/w가 제공하는 플랫폼 구성이라 범위 밖이다.
+
+다만 목록은 **MCP Server 빌드(`ax-hub-mcp-server@0.1.0`) 하나에서 산출했다.** Tool Service가 이
+스택 밖의 의존(예: DB 드라이버, 연계 라이브러리)을 추가하면 그만큼은 이 SBOM에 없으므로, 해당
+빌드에서 다시 산출해 합쳐야 한다.
+
+| 구분 | 개수 | 내용 |
+|---|---|---|
+| 런타임 의존성 (scope: required) | 12 | 실행 산출물 classpath에 올라가는 라이브러리 |
+| 빌드 환경 (scope: optional) | 2 | JDK 21, Gradle 8.14.3 |
+| 합계 | 14 | |
+
+라이선스는 Apache-2.0 9건, MIT 3건, MIT-0 1건, GPL-2.0 with Classpath Exception 1건(JDK)이다.
+라이브러리 12건은 모두 permissive이고, copyleft는 JDK 하나뿐이다. JDK는 Classpath Exception이
+있어 이 JDK로 실행하는 애플리케이션에 소스 공개 의무가 생기지 않는다.
+
+JDK 배포판은 표준가이드가 정한 Eclipse Temurin
+(`openjdk21u-jdk_x64_windows_hotspot_21.0.5`)이고, 이 SBOM은 그 환경에서 산출했다. 컨테이너 빌드와
+실행도 같은 계열인 `eclipse-temurin:21-jdk-alpine`과 `eclipse-temurin:21-jre-alpine`을 쓴다.
+
+다만 현재 `build.gradle`의 toolchain은 `languageVersion`만 지정하고 **vendor를 고정하지 않는다.**
+로컬 빌드는 설치된 아무 JDK 21이나 잡을 수 있으므로, 이 SBOM의 JDK 항목은 산출 시점 환경의 기록이지
+빌드가 강제하는 값이 아니다. 배포 산출물은 Dockerfile이 Temurin 이미지를 고정하므로 영향이 없다.
+
+## 제외 항목
+
+제외 항목과 사유는 엑셀 `Exclusions` 시트가 정본이다. 요약하면 다음과 같다.
+
+- **test scope와 annotationProcessor** — 선언 4건. 산출물에 포함되지 않는다.
+  - `spring-boot-starter-test`, `com.squareup.okhttp3:mockwebserver:4.12.0`,
+    `org.junit.platform:junit-platform-launcher` (test scope)
+  - `org.springframework.boot:spring-boot-configuration-processor` (annotationProcessor)
+- `joni`, `graal-js`, `graal-sdk` — json-schema-validator의 `optional`. ECMA262 정규식 검증을
+  쓰지 않아 해석되지 않으므로 약 50MB가 빠진다.
+- `jakarta.servlet-api:6.1.0` — mcp-core의 `provided`. 산출물에 포함되지 않고 서블릿 컨테이너가 제공한다.
+- `mcp:2.0.0`(aggregate), `mcp-json-jackson3:2.0.0` — Jackson 3 경로를 쓰지 않아 선언하지 않는다.
+  자세한 배경은 [mcp-java-sdk-adoption.md](../mcp-java-sdk-adoption.md) 참고.
+
+## 산출 방법과 한계
+
+버전과 해시는 `build.gradle` 선언에서 출발해 Gradle 로컬 캐시의 실제 `pom`을 따라가 그래프를
+만들고, 캐시된 실제 jar 바이너리에서 SHA-512 / SHA-1을 직접 계산했다. Gradle 배포본의 SHA-256은
+wrapper의 `distributionSha256Sum` 값을 그대로 옮겼다.
+
+최초 산출 시점에는 gradle daemon이 뜨지 않아(`Unable to establish loopback connection`)
+`gradlew dependencies` 대조를 하지 못했고, 버전 정렬은 pom과 Spring Boot BOM 판독에만 근거했다.
+2026-08-22에 그 대조를 실행해 **네 항목 모두 판독과 일치함을 확인했다.**
+
+```bash
+./gradlew dependencies --configuration runtimeClasspath
+```
+
+| 컴포넌트 | pom 요청 버전 | 수록 버전 | 근거 | 실측 |
+|---|---|---|---|---|
+| jackson-databind | 2.20.1 (mcp-json-jackson2) | 2.19.4 | Spring Boot 3.5.11 → jackson-bom 2.19.4 | `2.20.1 -> 2.19.4` 확인 |
+| jackson-databind | 2.18.3 (json-schema-validator) | 2.19.4 | 위와 동일 | `2.18.3 -> 2.19.4` 확인 |
+| reactor-core | 3.7.0 (mcp-core) | 3.7.16 | Spring Boot 3.5.11 → reactor-bom 2024.0.15 | `3.7.0 -> 3.7.16` 확인 |
+| slf4j-api | 2.0.16 (mcp-core) | 2.0.17 | Spring Boot 3.5.11 관리 버전 | `2.0.16 -> 2.0.17` 확인 |
+
+같은 실행에서 `mcp-json-jackson2`의 전이 트리가 이 SBOM의 런타임 12건과 정확히 일치하는 것도 확인했다.
+`jackson-bom`은 BOM이라 컴포넌트가 아니며, 제외 항목으로 적은 `joni` / `graal-js` / `graal-sdk`와
+`jakarta.servlet-api`는 실제로 `runtimeClasspath`에 나타나지 않았다.
+
+가장 확인이 필요한 항목은 jackson-databind다. SDK가 요청한 2.20.1이 `io.spring.dependency-management`에
+의해 2.19.4로 내려가므로, initialize / tools/list / tools/call 직렬화 계약 테스트로 동작을 확인한다.
+(2026-08-22 기준 전체 테스트 159건 통과)
+
+CycloneDX 1.5 공식 JSON Schema 원본 대조는 폐쇄망이라 수행하지 않았다. 대신 생성 시점에
+`dependencies`의 모든 `ref` / `dependsOn`이 실재하는 `bom-ref`를 가리키는지, 컴포넌트가 빠짐없이
+`dependencies`에 등장하는지 구조 점검을 통과시켰다.

src/main/resources/application.yml

@@ -89,8 +89,10 @@ mcp:
     # HTTP(S) Portal API or local Spring resource location such as file:./config/local-toolserver-info-sample-v1.json.
     registry-url: ${MCP_PORTAL_REGISTRY_URL:}
     refresh-interval-seconds: ${MCP_PORTAL_REFRESH_INTERVAL_SECONDS:300}
-  # Declared per deployment. baseEndpoint is the execution address and is owned by this file only:
-  # nothing a Tool Service returns can change where MCP sends the call.
+  # Declared per deployment. baseEndpoint is only the base a relative manifest endpoint resolves against.
+  # The execution address itself comes from the Tool Service manifest (endpoint or _meta.endpoint), and an
+  # absolute HTTP(S) value there decides where MCP sends the call. Only scheme and host are validated, so
+  # a manifest can point MCP at any HTTP(S) host: keep manifest sources trusted.
   bundles: []
   trace:
     enabled: true    # Rejects oversized MCP request bodies before controller processing.

src/test/java/io/shinhanlife/dap/biz/mcp/deploy/HelmDeploymentContractTest.java

@@ -20,7 +20,7 @@ import org.yaml.snakeyaml.Yaml;
  * Helm Chart의 배포 토폴로지와 환경별 values를 배포 전에 검증하는 계약 테스트입니다. {@code McpProperties}의 {@code @AssertTrue}는 Pod이 뜬 뒤에야 잘못된 설정을 잡지만, GitOps에서는 그 시점이 이미 배포된 뒤라
  * CrashLoopBackOff로 나타납니다. 같은 규칙을 여기서 먼저 적용해 잘못된 values가 머지되는 것을 막습니다.
  *
- * <p>이 테스트가 고정하는 핵심 규칙은 MCP 배포와 Tool Service의 1:1 관계, 공개 path의 유일성, Route와 애플리케이션 endpoint의 동일성입니다. 이 규칙들은 애플리케이션 불변식이 아니라 배포 결정이므로 production 코드가 아니라
+ * <p>이 테스트가 고정하는 핵심 규칙은 두 배포 모델(portal·bundles)의 경계, portal 모드에서 route key가 배포 정의로 새지 않는 것, bundles 모드의 Tool Service 1:1 관계, 공개 path의 유일성, Route와 애플리케이션 endpoint의 동일성입니다. 이 규칙들은 애플리케이션 불변식이 아니라 배포 결정이므로 production 코드가 아니라
  * 배포 정의에서 잠급니다. 파일을 읽기만 하며 애플리케이션 context나 helm 바이너리를 필요로 하지 않습니다.
  */
 class HelmDeploymentContractTest {
@@ -302,6 +302,92 @@ class HelmDeploymentContractTest {
                 .contains("replicas: {{ $tier.replicas }}");
     }
 
+    /**
+     * Chart가 지원하는 배포 모델만 선언하는지 확인합니다. {@code mode}는 template 전체의 분기 축이므로, 오타가 있으면 렌더링이 통째로 실패하거나 더 나쁘게는 의도하지 않은 모델로 설치됩니다.
+     */
+    @Test
+    void valuesDeclareASupportedDeploymentMode() throws IOException {
+        Map<String, Object> values = loadYaml(VALUES);
+
+        assertThat(String.valueOf(values.get("mode")))
+                .withFailMessage("values.yaml의 mode는 portal 또는 bundles여야 합니다: %s", values.get("mode"))
+                .isIn("portal", "bundles");
+    }
+
+    /**
+     * portal 모드의 단일 배포가 이름·등급·공개 path를 선언하고, 그 path가 route key를 포함하지 않는지 확인합니다. route key는 {@code /mcp/{routeKey}} URI에서만 결정되므로(ADR-0013) publicPath에 route를 적으면 그 배포는 한 route만
+     * 받게 되어 Portal이 매핑을 소유하는 의미가 사라집니다.
+     */
+    @Test
+    void portalDeploymentServesEveryRouteUnderTheBareMcpPath() throws IOException {
+        Map<String, Object> values = loadYaml(VALUES);
+        Map<String, Object> deployment = asMap(section(values, "portal").get("deployment"));
+
+        assertThat(deployment)
+                .withFailMessage("portal.deployment에 name/tier/publicPath가 모두 있어야 합니다: %s", deployment)
+                .containsKeys("name", "tier", "publicPath");
+        assertThat(String.valueOf(deployment.get("publicPath")))
+                .withFailMessage("portal.deployment.publicPath에 route key가 들어 있습니다. route는 URI에서만 옵니다(ADR-0013).")
+                .isEqualTo("/mcp");
+        assertThat(section(values, "tiers").keySet())
+                .withFailMessage("portal.deployment의 tier '%s'가 tiers에 없습니다.", deployment.get("tier"))
+                .contains(String.valueOf(deployment.get("tier")));
+    }
+
+    /**
+     * Portal registry 주소에 기본값이 없고 환경별 values가 각자 선언하는지 확인합니다. 기본값이 있으면 지정을 빠뜨린 설치가 조용히 성공해 dev가 운영 Portal을 보거나 그 반대가 됩니다.
+     */
+    @ParameterizedTest
+    @ValueSource(strings = {"dev", "test", "prod"})
+    void everyEnvironmentDeclaresItsOwnPortalRegistryUrl(String env) throws IOException {
+        Object shared = section(loadYaml(VALUES), "portal").get("registryUrl");
+        assertThat(shared == null || String.valueOf(shared).isEmpty())
+                .withFailMessage("values.yaml이 portal.registryUrl 기본값 '%s'를 갖고 있습니다. 환경별 파일이 소유해야 합니다.", shared)
+                .isTrue();
+
+        String url = String.valueOf(section(loadYaml(environmentValues(env)), "portal").get("registryUrl"));
+        assertThat(url)
+                .withFailMessage("values-%s.yaml에 portal.registryUrl이 없습니다. mode=portal 렌더링이 실패합니다.", env)
+                .isNotBlank()
+                .doesNotContain("null")
+                .startsWith("http");
+    }
+
+    /**
+     * ConfigMap이 두 모델을 모두 만들되 서로 섞이지 않는지 확인합니다. portal 분기는 정적 bundle을 선언하지 않아야 하고, route key를 ConfigMap에 적어서는 안 됩니다. 적는 순간 매핑이 다시 배포 시점으로 고정되어 Portal을 원천으로 둔
+     * 이유가 사라집니다.
+     */
+    @Test
+    void configMapKeepsPortalAndBundleSourcesSeparate() throws IOException {
+        String configMap = Files.readString(CHART.resolve("templates/configmap.yaml"));
+
+        assertThat(configMap)
+                .contains("{{- if eq .Values.mode \"portal\" }}")
+                .contains("bundles: []")
+                .contains("registry-url: {{ .Values.portal.registryUrl | quote }}")
+                .contains("portal-registry-key: {{ .Values.portal.registryRedisKey | quote }}");
+        assertThat(configMap)
+                .withFailMessage("ConfigMap이 route key를 직접 적고 있습니다. route는 /mcp/{routeKey} URI에서만 옵니다(ADR-0013).")
+                .doesNotContain("route-key");
+    }
+
+    /**
+     * 검사 helper가 확인한 값을 출력하지 않는지 확인합니다. {@code required}의 결과를 변수에 담지 않으면 검사한 host와 CIDR이 렌더링 결과에 그대로 섞여 리소스 이름과 path가 오염됩니다. 정적 values 검사로는 드러나지 않고 렌더링해야 보이는
+     * 종류의 실수이므로 여기서 형태를 고정합니다.
+     */
+    @Test
+    void validationHelperDoesNotEmitTheValuesItChecks() throws IOException {
+        List<String> emitting =
+                Files.readAllLines(CHART.resolve("templates/_helpers.tpl")).stream()
+                        .map(String::trim)
+                        .filter(line -> line.startsWith("{{- required") || line.startsWith("{{ required"))
+                        .toList();
+
+        assertThat(emitting)
+                .withFailMessage("required 결과를 변수에 담지 않아 검사 값이 렌더링 결과에 출력됩니다: %s", emitting)
+                .isEmpty();
+    }
+
     /**
      * 환경별 values 파일 경로를 만듭니다.
      */