Apigee Hybrid에서 모델 컨텍스트 프로토콜 (MCP) 사용 설정

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 페이지에서는 버전 1.17.0 이상을 실행하는 기존 Apigee Hybrid 클러스터에서 모델 컨텍스트 프로토콜(MCP)을 사용 설정하는 방법을 설명합니다. 이 절차를 완료하면 클러스터가 새 클러스터 내 MCP 데이터 영역을 실행하고 메시지 프로세서가 MCP 도구 호출을 라우팅할 준비가 됩니다. 그런 다음 공유된 MCP 빠른 시작에 따라 첫 번째 MCP 탐색 프록시를 배포할 수 있습니다.

Apigee와 Apigee Hybrid 간에 공유되는 MCP 개념, 아키텍처, 기능 세부정보는 Apigee의 MCP 개요를 참조하세요.

이 절차의 역할

Apigee Hybrid 클러스터에서 MCP를 사용 설정하면 다음과 같이 변경됩니다.

  1. Apigee 컨트롤 플레인의 MCP 구성에 대한 apigee-watcher ID 액세스 권한을 부여합니다. MCP 사이드카가 Apigee 컨트롤 플레인에서 MCP 구성 번들을 가져올 수 있도록 Apigee 조직의 controlPlaneAccess 리소스에 있는 watcher_identities 목록에 apigee-watcher 서비스 계정을 추가합니다. 이는 Apigee 조직으로 범위가 지정된 컨트롤 플레인 변경사항이며 해당 조직에 서비스를 제공하는 클러스터 수에 관계없이 조직당 한 번만 수행하면 됩니다.
  2. 새로운 클러스터 내 MCP 데이터 영역을 추가합니다. Apigee Hybrid가 설치된 동일한 Kubernetes 네임스페이스(기본값 apigee)에 새 MCP 포드 집합이 생성되며, 이를 실행하는 데 필요한 지원 Kubernetes 리소스(서비스, 수평형 포드 자동 확장 처리, RBAC)도 함께 생성됩니다. MCP 도구 호출은 이 포드에서 처리됩니다.
  3. MCP 데이터 영역에 도달하도록 메시지 프로세서를 구성합니다. Apigee 연산자는 MP가 MCP 도구 호출을 새 클러스터 내 MCP 데이터 영역으로 라우팅하도록 메시지 프로세서 포드 사양을 업데이트합니다. 이 변경사항을 적용하면 메시지 프로세서(ApigeeDeployment 컨트롤러에서 관리)의 단계적 카나리아 출시가 트리거됩니다. 이전 포드는 새 포드가 Ready될 때까지 트래픽을 계속 처리합니다. 이 릴리스는 활성화 및 비활성화 전환 시에만 실행되며, 진행 중인 MCP 활동이나 안정적인 MCP 트래픽에는 실행되지 않습니다. 승인된 유지보수 기간에 이 절차를 실행하고 출시가 완료될 때까지 기다린 후 진행합니다.

1단계: overrides.yaml 수정

Apigee Hybrid Helm 차트에 사용하는 overrides.yaml 파일을 엽니다. 파일의 최상위 수준에 다음을 추가합니다.

enableMcpServer: true

MCP를 사용 설정하는 데 필요한 최소 구성입니다. apigee-org 차트의 기본 제공 기본값을 사용합니다. 즉, CPU 사용률 70% 에서 10개로 자동 확장되는 MCP 데이터 영역 복제본 2개, MCP 데이터 영역 컨테이너의 CPU 500m 및 메모리 512Mi의 리소스 요청, CPU 2000m 및 메모리 1Gi의 한도가 사용됩니다. 복제본 수, 리소스 요청 또는 MCP 서비스 계정을 맞춤설정하려면 이 페이지 뒷부분의 참조: overrides.yaml의 MCP 필드를 참조하세요.

다음은 병합된 overrides.yaml의 전체 예시이며, 각 인증 스타일에 대해 하나씩 제공됩니다. 기존 기본 설치 구성 방식과 일치하는 예시를 사용합니다. MCP 관련 줄은 주석으로 강조 표시되어 있으며 세 가지 변형 모두에서 동일합니다.

기본 설치에서 Apigee 구성요소를 Google Cloud에 인증하는 방식과 일치하는 탭을 선택합니다. 선택한 항목은 이 페이지의 모든 변이 범위 코드 블록에 적용됩니다.

워크로드 아이덴티티(GKE)

기본 설치에서 GKE 워크로드 아이덴티티를 통해 Google Cloud에 Apigee 구성요소를 인증하는 경우 이 변형을 사용합니다(디스크에 서비스 계정 키 파일 없음).

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
  workloadIdentity:
    enabled: true
    gsa: apigee-non-prod@my-hybrid-project.
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
envs:
- name: my-env

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

파일 기반 서비스 계정 키

기본 설치에서 각 클러스터에 배포하는 서비스 계정 키 파일을 통해 Apigee 구성요소를 Google Cloud에 인증하는 경우 이 변형을 사용합니다.

instanceID: "my-hybrid-instance"
namespace: APIGEE_NAMESPACE
gcp:
  region: us-central1
  projectID: my-hybrid-project
k8sCluster:
  name: my-cluster
  region: us-central1
org: my-org
guardrails:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
mart:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
connectAgent:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json
watcher:
  serviceAccountPath: ./service-accounts/apigee-non-prod.json  # MCP also uses this key file
envs:
- name: my-env
  serviceAccountPaths:
    synchronizer: ./service-accounts/apigee-non-prod.json
    runtime:      ./service-accounts/apigee-non-prod.json

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

워크로드 아이덴티티 제휴(AKS/EKS)

기본 설치가 AKS 또는 EKS에 있고 워크로드 아이덴티티 제휴를 통해 Google Cloud에 인증하는 경우 이 변형을 사용합니다. MCP는 watcher.serviceAccountPath에서 apigee-watcher가 이미 사용하는 사용자 인증 정보 구성 파일을 사용하므로 MCP 관련 ID 구성을 추가하지 않습니다. 사용자 인증 정보 구성을 Kubernetes 보안 비밀에 대신 저장하는 경우 기타 ID 메커니즘을 참조하세요.

기존 WIF overrides.yaml에 MCP 최상위 키를 추가합니다.

# ---- MCP: minimum required -------------------------------------------------
enableMcpServer: true

# ---- MCP: optional customization (all fields default when omitted) ---------
# mcpServer:
#   replicaCountMin: 2
#   replicaCountMax: 10
#   targetCPUUtilizationPercentage: 70
#   resources:
#     requests: { cpu: 500m,  memory: 512Mi }
#     limits:   { cpu: 2000m, memory: 1Gi }
#   sidecar:
#     resources:
#       requests: { cpu: 200m, memory: 128Mi }
#       limits:   { cpu: 500m, memory: 512Mi }
#   annotations: {}
# ----------------------------------------------------------------------------

mcpServer.gsa 및 mcpServer.serviceAccountPath는 설정하지 않은 상태로 둡니다. MCP 사이드카는 watcher.serviceAccountPath의 apigee-watcher와 동일한 사용자 인증 정보 구성 파일을 사용합니다.

2단계: 컨트롤 플레인의 MCP 구성에 대한 감시자 ID 액세스 권한 부여

MCP 사이드카는 apigee-watcher 구성요소의 Google Cloud 서비스 계정(1단계에서 선택한 ID)을 사용하여 Apigee 컨트롤 플레인에서 구성 번들을 가져옵니다. MCP 포드가 시작되기 전에 해당 서비스 계정을 Apigee 조직의 controlPlaneAccess 리소스에 있는 watcher_identities 목록에 추가합니다. 이 권한이 없으면 MCP 구성을 검색하기 위한 MCP 사이드카의 apigee.googleapis.com 호출이 404 Not Found를 반환하고 MCP 데이터 영역이 도구 트래픽을 제공할 준비가 되지 않습니다.

이 단계는 조직당 한 번만 수행하면 됩니다(클러스터별로 수행하지 않음). 동일한 Apigee 조직의 이전 클러스터에 대한 액세스 권한을 이미 부여한 경우 이 단계를 건너뜁니다.

  1. API 호출에 사용하는 셸 변수를 설정합니다. 설치 값을 재사용합니다.
    export ORG_NAME=YOUR_ORG_NAME
    export PROJECT_ID=YOUR_GCP_PROJECT_ID
    export WATCHER_SA=apigee-watcher@${PROJECT_ID}.
    export TOKEN=$(gcloud auth print-access-token)

    각 항목의 의미는 다음과 같습니다.

    • YOUR_ORG_NAME은 Apigee Hybrid 조직의 이름입니다.
    • YOUR_GCP_PROJECT_ID는 Apigee Hybrid 조직을 호스팅하는 Google Cloud 프로젝트입니다.
    • WATCHER_SA은 apigee-watcher 서비스 계정의 이메일 주소입니다. overrides.yaml에서 watcher.gsa를 재정의한 경우 기본 apigee-watcher@${PROJECT_ID}. 대신 해당 값을 사용합니다.
  2. updateControlPlaneAccess API를 호출하여 감시자 서비스 계정을 watcher_identities 목록에 추가합니다.

    데이터 상주 없음

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
      -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"
    

    데이터 상주

    curl -X PATCH -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \
      -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"
    

    여기서 CONTROL_PLANE_LOCATION은 Apigee Hybrid 설치에서 데이터 레지던시를 사용하는 경우 컨트롤 플레인 데이터의 위치입니다. 사용 가능한 위치 목록은 사용 가능한 Apigee API 컨트롤 플레인 리전을 참조하세요.

    호출은 장기 실행 작업을 반환합니다. 완료될 때까지 기다렸다가 아래의 확인 단계를 실행합니다.

  3. 지원금이 지급되었는지 확인합니다. getControlPlaneAccess를 호출하고 감시자 서비스 계정이 응답의 watcherIdentities 필드에 표시되는지 확인합니다.

    데이터 상주 없음

    curl -X GET -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"
    

    데이터 상주

    curl -X GET -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"
    

    응답에는 감시자 서비스 계정이 포함된 watcherIdentities 배열이 포함되어야 합니다. 예를 들면 다음과 같습니다.

    {
      "synchronizerIdentities": [ ... ],
      "analyticsPublisherIdentities": [ ... ],
      "watcherIdentities": [
        "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID."
      ]
    }

    watcherIdentities가 응답에 없거나 감시자 서비스 계정을 포함하지 않는 경우 PATCH 명령어를 다시 실행하고 계속하기 전에 작업 상태에서 오류를 확인합니다.

3단계: apigee-operator 차트 업그레이드

먼저 연산자 차트를 업그레이드합니다. 운영자 차트는 새 MCP 리소스의 스키마를 소유하고 조직 차트는 이를 참조합니다. 잘못된 순서로 업그레이드하면 helm upgrade가 성공하지만 MCP 포드가 생성되지 않습니다.

helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

명령어는 1분 이내에 완료됩니다. 새 이미지로 연산자 배포가 완전히 출시되었는지 확인합니다(apigee-controller-manager Deployment는 ApigeeDeployment가 아닌 일반 Kubernetes 리소스이므로 여기서는 kubectl rollout status deploy가 올바른 명령어임).

kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m

예상 출력:

deployment "apigee-controller-manager" successfully rolled out

4단계: apigee-org 차트 업그레이드

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

이제 두 개의 조정 루프가 동시에 실행됩니다.

  • Apigee 연산자는 MCP 배포, 서비스, HPA, ServiceAccount, 역할, RoleBinding을 만듭니다. MCP 포드는 한 번에 두 개씩 나타납니다(Kubernetes 예약에 따라 다름). 각 포드의 사이드카 컨테이너는 시작 직후 Apigee 컨트롤 플레인에서 첫 번째 구성 가져오기를 수행합니다.
  • Apigee 연산자는 hostAliases 항목을 메시지 프로세서 포드 사양에 삽입하여 apigee-runtime ApigeeDeployment 출시를 트리거합니다.

5단계: 설치 확인

MCP 데이터 영역이 실행 중인지 확인

연산자가 만든 4개의 MCP 관련 리소스를 검사합니다. 리소스 이름에는 조직에서 파생된 서픽스가 포함됩니다. 다음 샘플에서는 ORG_CR_SUFFIX를 해당 서픽스의 자리표시자로 사용하며 포드 서픽스와 서비스 ClusterIP는 환경에 따라 다릅니다.

MCP 포드(기본값은 2개, 부하가 있을 때 10개로 자동 확장):

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                                                READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-abc12   2/2     Running   0          2m
apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-def34   2/2     Running   0          2m

모든 포드는 READY 열에 2/2을 표시해야 합니다. 각 포드의 두 컨테이너는 다음과 같습니다.

  • apigee-mcp-server — MP 포드가 연결되는 MCP 데이터 영역 컨테이너입니다.
  • apigee-mcp-server-config — Apigee 컨트롤 플레인에서 구성 번들을 가져와 MCP 데이터 영역 컨테이너가 읽는 공유 볼륨에 쓰는 구성 사이드카(apigee-watcher 바이너리의 모드)입니다.

MCP ApigeeDeployment(일반 Deployment가 아닌 Kubernetes 커스텀 리소스):

kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                              STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   running                 2m

예상 상태는 running입니다. 또한 기본 포드가 2/2 Running인지 확인합니다.

kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                                    READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH   2/2     Running   0          2m

MCP 서비스:

kubectl get svc -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME                              TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                              AGE
apigee-mcp-server-default-ORG_CR_SUFFIX   ClusterIP   10.96.42.17   <none>        80/TCP,443/TCP,15021/TCP,15000/TCP   2m

MCP HorizontalPodAutoscaler:

kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server

MINPODS가 overrides.yaml(기본값 2)의 mcpServer.replicaCountMin와 일치하고 MAXPODS가 mcpServer.replicaCountMax(기본값 10)와 일치하는지 확인합니다. TARGETS, REPLICAS, AGE 열은 실시간 측정항목 및 클러스터 상태에 따라 달라집니다.

메시지 프로세서 포드가 hostAliases 항목을 수신했는지 확인

모든 MP 포드에 삽입된 항목이 표시되어야 합니다. 포드가 하나라도 누락되면 해당 포드는 MCP 도구 호출을 라우팅할 수 없습니다. 모든 MP 포드와 해당 hostAliases를 나열합니다.

kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

예상 출력: 모든 MP 포드는 이전 단계의 MCP 서비스 ClusterIP를 가리키는 두 개의 호스트 이름이 있는 항목 하나가 포함된 hostAliases 배열을 나열합니다(두 번째 호스트 이름은 소문자 조직 이름을 사용함). 메시지 프로세서 포드 이름은 apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH 템플릿을 따릅니다. 여기서 TRUNCATED_ORG은 조직 이름(조직 이름이 긴 경우 Kubernetes 63자 이름 제한에 맞게 잘림), ENV_GROUP_HASH은 환경별 배포 그룹 해시, REV은 현재 출시 버전 번호(4자리, 예: 1170), POD_HASH은 포드별 무작위 서픽스입니다. 예를 들면 다음과 같습니다.

apigee-runtime-myorg-env1-abc12-1170-def34   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
apigee-runtime-myorg-env1-abc12-1170-ghi56   [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]

포드에 빈 hostAliases 값이 표시되면 메시지 프로세서 ApigeeDeployment가 업데이트된 포드 사양을 완전히 선택하지 않은 것입니다. 현재 메시지 프로세서 포드를 삭제하여 새로운 스테이징된 카나리아 릴리스를 강제합니다. ApigeeDeployment 컨트롤러는 현재 사양(이제 hostAliases 항목 포함)에서 다시 렌더링합니다.

kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime

ApigeeDeployment 컨트롤러는 1분 이내에 포드를 다시 만듭니다. 메시지 프로세서는 Deployment가 아닌 ApigeeDeployment 커스텀 리소스로 배포되므로 kubectl rollout restart deploy(일반 Kubernetes 명령어)는 메시지 프로세서에서 작동하지 않습니다.

설치 완료

이전 세 가지 검사를 함께 수행하면 MCP 데이터 영역이 실행 중이고 MP 주소 지정이 가능한지 확인할 수 있습니다.

  • 모든 MCP 포드는 2/2 Running입니다. MCP 데이터 영역 컨테이너는 운영자가 발급한 TLS 인증서가 로드되지 않고 사이드카가 아직 초기 MCP 구성을 로드하지 않은 경우 포트 15021에서 Kubernetes 준비 프로브에 실패하므로 Ready 포드에는 이러한 두 가지 기본 요건이 모두 적용됩니다.
  • 모든 MP 포드의 사양에는 mcp.apigee.internal 및 ORG_NAME.mcp.apigee.internal를 MCP 서비스 ClusterIP에 고정하는 hostAliases 항목이 포함됩니다. 따라서 MP 포드는 MCP 프록시 대상 엔드포인트를 클러스터 내 MCP 데이터 영역으로 확인할 수 있습니다.
  • MP 포드는 삽입된 hostAliases 항목을 통해 mcp.apigee.internal를 MCP 서비스 ClusterIP로 변환합니다.

첫 번째 MCP 탐색 프록시를 배포한 후 공유 MCP 빠른 시작의 일부로 엔드 투 엔드 MCP 도구 트래픽(Apigee 인그레스를 통한 실제 MCP initialize 또는 tools/list 호출)을 확인합니다.

이전 세 가지 검사 중 하나라도 실패하면 빠른 시작을 진행하기 전에 MCP 배포 문제 해결을 참고하세요.

6단계: 나머지 클러스터에서 MCP 사용 설정

특정 호스트 이름에 대한 MCP 요청은 해당 Apigee 환경 그룹을 제공하는 모든 클러스터로 라우팅될 수 있습니다. 동일한 환경 그룹의 일부 클러스터에서 MCP가 사용 설정되고 다른 클러스터에서는 사용 설정되지 않은 경우 MCP가 사용 설정되지 않은 클러스터로 라우팅되는 MCP 요청이 실패합니다(일반적으로 클라이언트에 503 Service Unavailable로 반환됨).

동일한 환경 그룹을 제공하는 모든 클러스터에서 MCP를 균일하게 사용 설정합니다. 추가 클러스터마다 1, 3, 4, 5단계를 반복합니다. 2단계(감시자 ID 액세스 권한 부여)를 반복할 필요가 없습니다. 이 권한 부여는 Apigee 조직으로 범위가 지정되며 동일한 조직의 모든 클러스터에 적용됩니다.

스테이트리스(Stateless) MCP 프로토콜(버전 1.17.4 이상) 확인

Apigee Hybrid 버전 1.17.4 이상에서는 기본적으로 스테이트리스(Stateless) MCP 프로토콜(버전 2026-07-28)을 제공합니다. 설치에서 이를 제공하는지 확인하려면 스테이트리스(Stateless) 프로토콜에만 존재하는 server/discover 메서드를 호출합니다. 이 검사에는 배포된 MCP 탐색 프록시가 필요하므로 MCP 빠른 시작을 완료한 후 실행하세요. 스테이트풀(Stateful) MCP 프로토콜 버전만 제공하는 버전 1.17.0~1.17.3에서는 이 검사를 건너뜁니다.

요청은 Apigee 환경 그룹의 호스트 이름으로 전송되므로 환경 그룹을 제공하는 모든 클러스터가 요청에 응답할 수 있습니다. 따라서 이 검사는 특정 클러스터가 아닌 환경 그룹을 확인하며 환경 그룹당 한 번만 실행하면 됩니다. 각 클러스터가 정상인지 확인하려면 5단계: 설치 확인에서 클러스터별 검사를 사용합니다.

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "server/discover",
        "params": {
          "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientCapabilities": {}
          }
        }
      }'

다음을 바꿉니다.

  • MCP_ENDPOINT_URL: MCP 엔드포인트의 호스트 이름입니다. Apigee 환경 그룹에 등록되고 Apigee 인그레스 게이트웨이에서 제공하는 호스트 이름입니다. 예를 들면 api.example.com입니다.
  • TOKEN: OAuth 2.0 액세스 토큰. MCP 프록시가 OAuthV2 정책으로 토큰을 확인하는 경우 필요합니다. 프록시가 VerifyAPIKey 정책을 대신 사용하는 경우 -H "Authorization: Bearer TOKEN" 줄을 정책이 읽는 헤더 또는 쿼리 매개변수의 API 키로 바꿉니다. 프록시가 인증되지 않은 요청을 수락하는 경우 이 줄을 삭제합니다.

응답이 HTTP 200이고 result.supportedVersions 배열에 2026-07-28가 포함된 경우 환경 그룹은 스테이트리스(Stateless) MCP 프로토콜을 제공합니다. 성공적인 응답은 다음과 유사하게 표시됩니다.

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "SERVICE_NAME",
        "version": "1.0.0"
      }
    },
    "cacheScope": "public",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "resultType": "complete",
    "supportedVersions": [
      "2026-07-28",
      "2025-11-25",
      "2025-06-18",
      "2025-03-26",
      "2024-11-05"
    ],
    "ttlMs": 0
  }
}

응답에서 SERVICE_NAME는 응답한 MCP 서비스의 이름입니다. cacheScope 및 ttlMs 필드는 캐시 힌트입니다. "ttlMs": 0는 기본값이며 오류를 나타내지 않습니다.

응답이 오류인 경우 이를 사용하여 원인을 찾습니다.

  • error.code -32602 및 error.message Unsupported protocol version를 사용하는 HTTP 400: 클러스터는 스테이트리스(Stateless) 프로토콜을 제공하지 않는 Apigee Hybrid 버전 1.17.0~1.17.3을 실행합니다. 버전 1.17.4 이상으로 업그레이드합니다.
  • HTTP 401 또는 403(인증), HTTP 404(이 환경 그룹의 /mcp에 MCP 프록시가 배포되지 않음), HTTP 503(비정상 MCP 데이터 영역) 또는 잘못된 요청의 다른 error.code 값과 같은 기타 오류: 원인은 Apigee Hybrid 버전이 아닙니다. MCP 배포 문제 해결을 참조하세요.

스테이트리스(Stateless) 요청 요구사항 및 오류의 전체 집합은 지원되는 MCP 프로토콜 버전을 참고하세요.

롤백

클러스터에서 MCP를 사용 중지하려면 overrides.yaml에서 enableMcpServer: false를 설정하거나 필드를 완전히 삭제한 후 apigee-org 차트를 업그레이드합니다.

helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \
  --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml

enableMcpServer 필드는 apigee-org 차트에서만 사용되므로 사용 중지 중에 연산자 차트를 업그레이드할 필요가 없습니다. Apigee 연산자(변경되지 않음)는 ApigeeOrganization 커스텀 리소스에서 구성 변경사항을 선택하고, MCP 리소스를 삭제하고, 메시지 프로세서 포드 사양에서 hostAliases 항목을 삭제하여 apigee-runtime ApigeeDeployment 출시를 트리거합니다. 승인된 유지보수 기간에 롤백합니다.

롤백 후 Apigee 환경에 배포한 MCP 탐색 프록시는 Apigee 컨트롤 플레인에 계속 존재하지만 해당 환경 그룹의 클러스터는 MCP 트래픽을 제공하지 않습니다. MCP 탐색 프록시를 배포 취소하여 기능을 완전히 해제하거나 배포된 상태로 두고 나중에 클러스터에서 MCP를 다시 사용 설정합니다.

MCP 데이터 영역과 인그레스 게이트웨이 간에 mTLS 구성

MCP 도구 호출은 MCP 데이터 영역을 벗어나 Apigee 인그레스 게이트웨이를 통해 클러스터에 다시 들어갑니다. 이때 해당 환경 그룹에 대한 다른 API 호출과 동일한 호스트 별칭과 동일한 virtualhosts[] 항목을 사용합니다. 기본적으로 MCP 데이터 영역은 단방향 TLS를 통해 인그레스 게이트웨이에 연결됩니다. 연결은 암호화되지만 MCP 데이터 영역은 클라이언트 인증서를 제공하지 않으며 인그레스 게이트웨이의 인증서를 확인하지 않습니다.

Apigee Hybrid 1.17.4부터 virtualhosts[].mcpMtls 블록을 사용하여 환경 그룹별로 이 연결에서 상호 TLS(mTLS)를 사용 설정할 수 있습니다. mTLS가 사용 설정된 경우:

  • MCP 데이터 영역은 사용자가 발급한 클라이언트 인증서를 제공하므로 인그레스 게이트웨이는 해당 환경 그룹의 다른 mTLS 클라이언트를 인증하는 것과 동일한 방식으로 MCP 데이터 영역을 인증합니다.
  • MCP 데이터 영역은 인그레스 게이트웨이의 인증서가 사용자가 지정한 CA에 연결되고 호출되는 호스트 별칭을 포함하는지 확인합니다. 두 검사 모두 기본적으로 사용 설정되어 있으며 환경 그룹별로 사용 중지할 수 있습니다.

한 번에 환경 그룹 하나씩 mTLS를 구성합니다. mcpMtls가 없는 환경 그룹은 동일한 인그레스 게이트웨이에서 제공하는 환경 그룹을 포함하여 단방향 TLS를 계속 사용하므로 점진적으로 마이그레이션할 수 있습니다. 클라이언트 인증서와 트러스트 CA도 환경 그룹별로 다릅니다. 클러스터 전체 MCP 클라이언트 인증서는 없으며 동일한 인그레스 게이트웨이에 있는 두 환경 그룹은 서로 다른 CA에서 발급한 서로 다른 클라이언트 인증서를 제공할 수 있습니다.

mcpMtls 필드는 한 수준 위의 인그레스 TLS 필드 이름을 의도적으로 재사용하지만 역할은 반대입니다. 이 연결에서 MCP 데이터 영역은 클라이언트이고 인그레스 게이트웨이는 서버이기 때문입니다.

필드 virtualhosts[].mcpMtls 미만 virtualhosts[] 바로 아래
sslCertPath, sslKeyPath MCP 데이터 영역이 인그레스 게이트웨이에 제공하는 클라이언트 인증서 및 키입니다. clientAuth 확장 키 사용을 포함해야 합니다. 인그레스 게이트웨이의 자체 서버 인증서 및 키입니다.
sslSecret 클라이언트 인증서 및 키(키 cert, key)를 보유하는 보안 비밀입니다. 인그레스 게이트웨이의 서버 인증서와 키를 보관하는 보안 비밀입니다.
caCertPath 또는 -cacert가 추가된 sslSecret 이름 인그레스 게이트웨이의 서버 인증서에 대해 MCP 데이터 영역이 신뢰하는 CA입니다. MCP 데이터 영역을 포함하여 수신 클라이언트 인증서에 대해 인그레스 게이트웨이가 신뢰하는 CA입니다.

시작하기 전에

  • 클러스터는 Apigee Hybrid 1.17.4 이상을 실행하고, apigee-operator, apigee-org, apigee-virtualhost 차트가 모두 해당 버전으로 업그레이드되고, 1단계: overrides.yaml 수정부터 시작하는 단계를 완료하여 MCP가 사용 설정됩니다. 업그레이드에 업데이트된 Apigee CRD 설치 단계(kubectl apply -k apigee-operator/etc/crds/default/ ...)가 포함되어 있는지 확인합니다. 연산자 차트만 업그레이드하면 CRD가 업데이트되지 않습니다. 1.17.4 이전의 CRD에서 API 서버는 ApigeeRouteConfig 리소스에서 mcpMtls 블록을 자동으로 삭제하므로 블록이 적용되지 않고 클러스터가 확인에 설명된 인증서 문제를 보고할 수 없습니다.
  • 이 환경 그룹에 대해 인그레스 게이트웨이가 신뢰하는 CA에서 발급한 MCP 데이터 영역의 클라이언트 인증서 및 비공개 키: virtualhosts[].caCertPath의 CA 또는 동일한 virtualhosts[] 항목의 INGRESS_SECRET_NAME-cacert 보안 비밀입니다. 인증서에 확장 키 사용 확장 프로그램이 있는 경우 clientAuth를 포함해야 합니다. MCP 데이터 영역은 확장 키 사용이 생략된 인증서를 거부합니다(확장 키 사용 확장 프로그램이 없는 인증서는 허용됨). 비공개 CA 사용: 공개 CA는 일반적으로 clientAuth 확장 키 사용이 있는 인증서를 발급하지 않습니다.
  • 이 환경 그룹의 인그레스 게이트웨이 자체 TLS 인증서에 서명한 CA 인증서(virtualhosts[].sslCertPath 또는 INGRESS_SECRET_NAME의 인증서)입니다. MCP 데이터 영역은 이 CA에 대해 인그레스 게이트웨이의 유효성을 검사합니다. disableChainValidation: true를 설정한 경우에만 생략합니다.
  • disableSanValidation: true를 설정하지 않는 한 인그레스 게이트웨이의 인증서는 주체 대체 이름에 환경 그룹의 호스트 별칭을 나열해야 합니다. 외부 클라이언트가 동일한 검사를 실행하므로 일반적으로는 그렇습니다.

인증서를 제공하는 두 가지 방법 중 하나를 선택합니다. 인그레스 게이트웨이 자체 mTLS 구성의 두 가지 옵션을 미러링합니다.

옵션 1: 인증서 파일

파일 경로가 있는 mcpMtls를 환경 그룹의 virtualhosts[] 항목에 추가합니다. Helm은 차트 디렉터리 내의 파일만 읽을 수 있으므로 파일은 $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ 아래에 있어야 하고(예: 인그레스 인증서 옆의 certs/ 디렉터리) 경로는 기존 sslCertPath, sslKeyPath, caCertPath 필드와 마찬가지로 해당 디렉터리에 상대적입니다. TLS 인증서 만들기를 참조하세요.

virtualhosts:
- name: ENV_GROUP_NAME
  tlsMode: MUTUAL
  caCertPath: certs/INGRESS_CA_FILE        # CA the ingress gateway trusts for client certificates
  sslCertPath: certs/INGRESS_CERT_FILE
  sslKeyPath: certs/INGRESS_KEY_FILE
  mcpMtls:
    sslCertPath: certs/MCP_CLIENT_CERT_FILE  # client certificate the MCP data plane presents
    sslKeyPath: certs/MCP_CLIENT_KEY_FILE
    caCertPath: certs/MCP_TRUST_CA_FILE      # CA that signed INGRESS_CERT_FILE

옵션 2: Kubernetes 보안 비밀

  1. 클라이언트 인증서 및 키가 포함된 보안 비밀을 만듭니다. 데이터 키는 cert 및 key여야 합니다.
    kubectl create secret generic MCP_CLIENT_SECRET_NAME -n APIGEE_NAMESPACE \
      --from-file=cert=MCP_CLIENT_CERT_FILE \
      --from-file=key=MCP_CLIENT_KEY_FILE
  2. 인그레스 게이트웨이의 인증서에 서명한 CA를 포함하는 두 번째 보안 비밀을 만듭니다. 이름은 첫 번째 보안 비밀의 이름에 -cacert가 추가된 이름이어야 하며 데이터 키는 cacert여야 합니다. disableChainValidation: true를 설정한 경우에만 이 단계를 건너뜁니다.
    kubectl create secret generic MCP_CLIENT_SECRET_NAME-cacert -n APIGEE_NAMESPACE \
      --from-file=cacert=MCP_TRUST_CA_FILE
  3. 환경 그룹의 virtualhosts[] 항목에서 첫 번째 보안 비밀을 참조합니다.
    virtualhosts:
    - name: ENV_GROUP_NAME
      tlsMode: MUTUAL
      sslSecret: INGRESS_SECRET_NAME
      mcpMtls:
        sslSecret: MCP_CLIENT_SECRET_NAME

하나의 mcpMtls 블록에서 두 옵션을 혼합하지 마세요. helm upgrade는 다음과 같은 일반적인 잘못된 구성의 항목을 지정하는 진단과 함께 빠르게 실패합니다. 경로 필드와 결합된 sslSecret, sslKeyPath가 없는 sslCertPath, sslCertPath가 없는 sslKeyPath, 두 양식 모두 제공되지 않음, 참조된 보안 비밀이 누락되었거나 예상 데이터 키가 없음. 다른 불일치(예: caCertPath가 disableChainValidation: true와 함께 설정됨)는 virtualhosts[].mcpMtls 속성 참조에 설명되어 있습니다.

변경사항 적용

환경 그룹의 apigee-virtualhost 출시 버전을 업그레이드합니다.

helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f overrides.yaml

MCP 포드가 다시 시작되지 않으며 다른 환경 그룹은 영향을 받지 않습니다. MCP 데이터 영역은 일반적으로 몇 분 이내에 다음 정기 새로고침에서 새 구성을 선택합니다. 동일한 업그레이드에서 항목을 tlsMode: SIMPLE에서 MUTUAL로 전환하는 경우 MCP 데이터 영역이 클라이언트 인증서를 제공하기 전에 인그레스 게이트웨이가 클라이언트 인증서를 요구하기 시작하므로 이 기간 동안 이 환경 그룹에 대한 MCP 도구 호출이 실패할 수 있습니다. 해당 환경 그룹의 유지보수 기간에 변경합니다.

확인

  1. 구성이 환경 그룹의 MCP 데이터 영역 라우팅 리소스에 도달했는지 확인합니다. 출력에는 보안 비밀 이름과 구성한 두 개의 검증 플래그가 표시되어야 합니다(설정되지 않은 플래그는 생략됨).
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    업그레이드 후 몇 분이 지나도 mcpMtls 열이 비어 있으면 일반적으로 클러스터의 Apigee CRD가 1.17.4보다 이전 버전이고 필드가 삭제되었기 때문입니다. 업데이트된 CRD를 적용하고(시작하기 전에 참조) apigee-virtualhost 업그레이드를 다시 실행합니다. 드물게 감시자 이미지를 제공하는 apigee-org 차트가 1.17.4로 업그레이드되지 않았습니다.
  2. MCP 데이터 영역에서 인증서를 수락했는지 확인합니다. 보안 비밀이 누락되었거나, 읽을 수 없거나, 사용할 수 없는 자료를 보유할 때마다 사이드카는 error 줄을 로깅하고 해당 환경 그룹의 이전 구성을 유지합니다. 사용 설정 직후에는 아무것도 없어야 합니다.
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    최근 기간이 아닌 전체 로그를 검색합니다. 잘못된 보안 비밀은 새로고침할 때마다 보고되는 것이 아니라 사이드카에서 처음 발견할 때 보고됩니다.
  3. ApigeeIssue 리소스로 보고된 인증서 문제를 확인합니다(MCP mTLS 문제 참고).
    kubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)'
  4. MCP 빠른 시작과 같이 환경 그룹에서 배포된 MCP 검색 프록시를 통해 MCP 요청을 전송합니다. 도구 호출이 성공하면 인그레스 게이트웨이와의 mTLS 핸드셰이크를 포함한 전체 경로가 확인됩니다.

인증서 순환

  • 옵션 2(보안 비밀): 보안 비밀을 적절하게 업데이트합니다(예: kubectl create secret generic ... --dry-run=client -o yaml | kubectl apply -f -). MCP 데이터 영역은 두 보안 비밀을 모두 감시하고 다음 새로고침 시 새 자료를 로드합니다. 포드 다시 시작 및 helm upgrade가 필요하지 않으며 진행 중인 MCP 호출이 중단되지 않습니다. 데이터 키 cert, key, cacert는 변경하지 않고 유지합니다.
  • 옵션 1(파일): 파일을 바꾸고 변경사항 적용에서와 동일한 helm upgrade를 실행합니다. 차트는 관리하는 보안 비밀을 업데이트하고 MCP 데이터 영역은 옵션 2에 설명된 대로 이를 선택합니다.

클라이언트 인증서 또는 트러스트 CA가 만료되기 14일 전에 클러스터는 심각도가 WARNING인 ApigeeIssue를 발생시킵니다. 만료 후에는 심각도가 ERROR입니다. 만료된 인증서는 교체할 때까지 계속 표시됩니다. 그러면 인그레스 게이트웨이가 핸드셰이크를 거부합니다.

환경 그룹에 mTLS 사용 중지

mcpMtls 블록을 삭제하고 동일한 수정에서 항목의 tlsMode를 다시 SIMPLE로 설정하거나 tlsMode를 삭제하고 동일한 helm upgrade를 실행합니다. MCP 데이터 영역은 다음 새로고침 시 해당 환경 그룹을 단방향 TLS로 반환하고 그룹에 대해 작성한 인증서 자료를 삭제합니다. 옵션 2에서 직접 만든 보안 비밀은 삭제되지 않습니다. 더 이상 필요하지 않으면 직접 삭제하세요.

인증서를 사용할 수 없는 경우의 동작

MCP 데이터 영역이 환경 그룹에 대해 구성된 인증서를 읽을 수 없거나 사용할 수 없는 경우(보안 비밀이 누락되었거나, 데이터 키가 없거나, 인증서에 clientAuth가 없거나, CA 보안 비밀이 CA가 아님) error 줄을 로깅하고, 마지막으로 성공적으로 로드된 인증서로 해당 환경 그룹을 계속 제공하며, 이후 새로고침 시 다시 시도합니다. 그룹에 인증서가 로드되지 않은 경우 해당 그룹에 대한 MCP 도구 호출이 실패하고(클라이언트는 일반적으로 503 Service Unavailable를 수신함) 다른 모든 환경 그룹은 계속 제공됩니다. 보안 비밀 또는 overrides.yaml 항목을 수정합니다. 다시 시작할 필요가 없습니다. 특정 메시지는 MCP 배포 문제 해결을 참조하세요.

참조: overrides.yaml의 MCP 필드

다음 표에는 버전 1.17.0에서 MCP 동작을 제어하는 모든 Apigee Hybrid overrides.yaml 필드가 나와 있습니다. enableMcpServer만 필요하며 다른 모든 필드에는 대부분의 설치에 적합한 안전한 기본값이 있습니다.

필드 정의는 Apigee Hybrid 1.17.0의 apigee-org Helm 차트 기본값과 일치합니다. MCP 데이터 영역에서 인그레스 게이트웨이로의 연결에 대한 mTLS 설정은 이 표에 없습니다. apigee-virtualhost 차트(1.17.4 이상)의 virtualhosts[].mcpMtls 아래에 환경 그룹별로 있습니다.

필드 유형 기본값 권장 조정
enableMcpServer 부울 false 필수. 이 클러스터에서 MCP를 사용 설정하려면 true로 설정합니다. 이 필드를 전환하면 메시지 프로세서의 단계적 카나리아 릴리스가 트리거됩니다. 유지보수 기간에만 전환하고 출시가 완료될 때까지 기다린 후 계속 진행하세요.
mcpServer.replicaCountMin 정수 2 HA를 위해 2로 유지합니다. MCP 트래픽이 높은 기준이 있는 경우에만 늘립니다. HPA는 CPU 압박이 있을 때 자동으로 확장됩니다. 신호: replicaCountMax에서 지속적인 HPA 및 목표를 초과하는 CPU
mcpServer.replicaCountMax 정수 10 피크 시간대에 HPA가 10로 제한되는 경우 늘립니다. 신호: kubectl top pods -l app=apigee-mcp-server는 피크 시 CPU 한도에 근접한 모든 포드를 보여줍니다. metrics-server가 설치되지 않은 경우 kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server를 사용하고 REPLICAS 열이 MAXPODS 상한에 있는지 확인합니다.
mcpServer.targetCPUUtilizationPercentage 정수 70 지연 시간에 민감한 워크로드의 경우 50~60로 낮춥니다(더 일찍 확장). 비용에 민감한 클러스터에서 복제본 수를 줄이려면 80~85로 높입니다. 신호: p95 요청 지연 시간은 포드당 CPU와 상관관계가 있습니다.
mcpServer.resources.requests ResourceList cpu: 500m, memory: 512Mi 포드가 안정적인 상태에서 자주 OOMKilled되거나 CPU 제한되는 경우 요청을 늘립니다. 신호: kubectl describe pod에 OOMKilled 또는 제한된 조건이 표시됩니다.
mcpServer.resources.limits ResourceList cpu: 2000m, memory: 1Gi p95 지연 시간이 높지만 전체 QPS가 낮은 경우(비용이 많이 드는 요청이 적음) 복제본 수를 늘리기 전에 CPU 한도를 높입니다. OOMKill이 표시되는 경우에만 메모리 한도를 늘립니다.
mcpServer.sidecar.resources.requests ResourceList cpu: 200m, memory: 128Mi 조정이 거의 필요하지 않습니다. 사이드카는 구성 번들을 주기적으로 작성하고 작성합니다. 정상 상태 CPU는 최소입니다.
mcpServer.sidecar.resources.limits ResourceList cpu: 500m, memory: 512Mi 조정이 거의 필요하지 않습니다. 단일 탐색 프록시에 비정상적으로 많은 수의 MCP 도구를 배포하는 경우에만 메모리를 늘립니다.
mcpServer.terminationGracePeriodSeconds 정수 30 조정이 거의 필요하지 않습니다. 포드 드레이닝 중에 장기 실행 중인 MCP 요청을 완료하는 데 시간이 더 필요한 경우 늘립니다.
mcpServer.annotations 지도 {} 클러스터에 필요한 경우 포드 주석을 추가합니다.
mcpServer.serviceAccountPath 문자열 unset 구성요소별 ID 분리가 필요하지 않으면 설정하지 않은 상태로 둡니다. 설정하지 않으면 MCP는 watcher.serviceAccountPath을 사용합니다. MCP는 envs[].serviceAccountPaths.runtime를 사용하지 않습니다. apigee-watcher ID에는 MCP 사이드카에 필요한 권한이 이미 있습니다. 이 필드를 재정의하는 경우 Google Cloud 서비스 계정 키 JSON 파일의 경로를 지정합니다. mcpServer.gsa와 상호 배타적입니다.

워크로드 아이덴티티가 사용 설정되어 있지 않고 mcpServer.serviceAccountRef 또는 serviceAccountSecretProviderClass를 설정하지 않은 경우 mcpServer.serviceAccountPath 또는 watcher.serviceAccountPath를 설정해야 합니다. 둘 다 설정하지 않으면 helm upgrade가 mcpServer.serviceAccountPath or watcher.serviceAccountPath is required!! 오류와 함께 실패합니다.

가능하면 워크로드 아이덴티티(GKE) 또는 워크로드 아이덴티티 제휴(AKS/EKS)를 사용하는 것이 좋습니다. 파일 기반 서비스 계정 키는 순환되고, 안전하게 저장되고, 모든 클러스터에 배포되어야 하며, 지원 아티팩트로 유출되는 가장 일반적인 소스입니다(지원 케이스 참조).
mcpServer.gsa 문자열 unset 구성요소별 ID 분리가 필요하지 않으면 설정하지 않은 상태로 둡니다. 설정하지 않으면 MCP는 watcher.gsa로 대체된 후 gcp.workloadIdentity.gsa로 대체됩니다. apigee-watcher ID에는 MCP 사이드카에 필요한 권한이 이미 있으므로 이를 재사용하는 것이 좋습니다. 조직에서 감사 목적으로 MCP 사이드카에 별도의 ID가 필요한 경우에만 전용 Google Cloud 서비스 계정 이메일로 재정의합니다.
mcpServer.serviceAccountRef 문자열 unset 고급을 클릭합니다. MCP 사이드카의 Google Cloud 서비스 계정 키를 보유하는 Apigee 네임스페이스의 기존 Kubernetes 보안 비밀 이름입니다. Apigee Helm 차트 외부에서 서비스 계정 키 보안 비밀을 관리하는 경우에만 사용합니다. mcpServer.serviceAccountPath 및 mcpServer.gsa와 상호 배타적입니다.

MCP는 watcher.serviceAccountRef를 사용하지 않습니다. 기본 설치에서 apigee-watcher 키를 watcher.serviceAccountRef이라는 이름의 Kubernetes 시크릿에 저장하는 경우, 이 속성을 동일한 시크릿 이름으로 설정하십시오.
mcpServer.podDisruptionBudget 지도 unset MCP 포드의 선택적 PodDisruptionBudget입니다. minAvailable 또는 maxUnavailable(정수 또는 백분율 문자열)을 허용합니다. 둘 중 하나만 설정합니다. 클러스터에 명시적 예산이 필요한 엄격한 자발적 중단 정책이 없는 한 설정하지 않은 상태로 둡니다.
mcpServer.tolerations list 설정되지 않음(최상위 tolerations로 대체) MCP 포드의 표준 Kubernetes 톨러레이션(toleration)입니다. MCP 포드가 다른 Apigee 구성요소가 허용하지 않는 taint를 허용해야 하는 경우에만 설정합니다.
mcpServer.image.pullPolicy 문자열 IfNotPresent MCP 서버 컨테이너의 이미지 가져오기 정책입니다. 거의 변경되지 않습니다.
mcpServer.sidecar.image.pullPolicy 문자열 IfNotPresent MCP 사이드카 컨테이너의 이미지 가져오기 정책입니다. 거의 변경되지 않습니다.

MCP 도구 용량 추정

Apigee Hybrid는 조직당 고정된 최대 MCP 도구 수를 적용하지 않습니다. 대신 도구 용량은 배포 또는 요청 시 적용되는 4가지 엄격한 크기 제한에 의해 제한됩니다. 특정 수의 도구가 적합한지 여부는 각 도구의 크기에 따라 달라지며, 이는 도구를 정의하는 OpenAPI 사양에서 파생됩니다.

일반적인 용량

대부분의 OpenAPI 사양(다양한 파라미터 수, 요청 본문 크기, 설명 길이를 가진 도구의 조합으로, 대부분의 도구가 소형에서 중형 크기 범위에 속함)의 경우 일반적으로 기본 tools/list 응답 크기 한도에서 조직당 10,000개의 MCP 도구를 맞출 수 있습니다.

실제 용량은 OpenAPI 사양의 특정 형태에 따라 다릅니다. 매개변수가 많거나 요청 본문이 크거나 설명이 긴 도구가 사양의 대부분을 차지하는 조직은 아래의 4가지 하드 한도 중 하나에 도달하기 전에 비례적으로 더 적은 수의 도구를 맞출 수 있습니다. 특정 사양의 용량을 검증하려면 아래의 사양 용량 추정을 따르세요.

엄격한 제한

Apigee Hybrid 버전 1.17.0에는 네 가지 크기 제한이 적용됩니다. 적용 가능한 가장 낮은 한도가 적용됩니다. 하나를 높여도 다른 한도는 높아지지 않습니다.

한도 값 범위 오류 모드
OpenAPI 사양 파일 크기 3 MiB 파일 .yaml개당 프록시 검증 시 400
MCP 프록시 번들 크기(압축 해제됨) 50 MiB MCP 검색 프록시당 프록시 검증 시 400
tools/list 응답 크기 10MiB(기본값) 호스트 이름당 502(TooBigBody 포함)
환경 그룹당 호스트 이름 100 환경 그룹당 환경 그룹 업데이트 시 400

도구별 크기를 결정하는 요소

도구별 크기는 거의 전적으로 도구의 inputSchema로 구성되며, 이는 작업에 대한 OpenAPI 사양의 parameters 및 requestBody에서 파생됩니다. 가장 중요한 세 가지 속성은 다음과 같습니다.

  • 파라미터 수. 각 매개변수 항목은 tools/list 응답에서 도구 크기에 약 100바이트를 추가합니다.
  • 요청 본문 속성 수 각 요청 본문 속성은 약 100바이트를 차지합니다. 따라서 요청 본문이 있는 작업(일반적으로 POST 및 PUT)은 요청 본문이 없는 작업(일반적으로 GET 및 DELETE)보다 훨씬 큽니다.
  • 설명 길이. 작업 설명은 도구에 거의 그대로 복사되므로 설명이 길어지면 도구 크기가 직접 증가합니다.

응답 스키마는 크기 예산에 포함되지 않습니다. parameters 및 requestBody만 MCP 구성에 도달합니다. 따라서 OpenAPI 파일 크기만으로 용량을 조정하면 비용이 과대평가되는 경향이 있습니다. 대부분의 실제 OpenAPI 사양에는 도구 크기에 영향을 미치지 않는 응답 스키마 정의가 포함되어 있기 때문입니다.

사양에 맞는 용량 추정

OpenAPI 사양의 도구 용량을 추정하는 가장 신뢰할 수 있는 방법은 대표적인 하위 집합을 측정하는 것입니다.

  1. 게시하려는 도구의 작은 대표 하위 집합(예: 전체 사양의 파라미터 수, 요청 본문 크기, 설명 길이의 조합을 반영하는 50~100개의 도구)을 참조하는 MCP 검색 프록시를 배포합니다.
  2. 배포된 프록시에 대해 tools/list를 호출하고 응답 크기(바이트)와 반환된 도구 수를 기록합니다.
  3. 응답 크기를 도구 수로 나누어 사양의 도구당 평균 크기를 구합니다.
  4. 관련 tools/list 응답 크기 한도(기본값: 10MiB)를 이 평균으로 나누어 이 형태의 사양에 대해 하나의 호스트 이름에 맞는 최대 도구 수를 추정합니다.

용량 증가

두 가지 메커니즘을 통해 도구 용량을 기본값 이상으로 늘릴 수 있습니다.

  • 호스트 이름 간에 도구를 샤딩합니다. tools/list 응답 한도는 호스트 이름별로 적용됩니다. 동일한 환경 그룹 내에서 여러 호스트 이름에 도구를 분할하면 호스트 이름당 여유 공간이 늘어납니다(환경 그룹당 호스트 이름 100개 제한 적용). 샤딩은 프록시별 번들 한도를 높이지 않습니다. 50MiB 번들 한도는 단일 MCP 검색 프록시의 모든 호스트 이름에 계속 적용됩니다.
  • tools/list 응답 크기 한도를 늘립니다. 기본 한도는 호스트 이름당 10MiB입니다. 최대 30MiB까지 늘릴 수 있습니다. 최소한 overrides.yaml에서 envs.components.runtime.resources.limits.memory, envs.components.runtime.resources.requests.memory, envs.components.runtime.cwcAppend.bin_setenv_max_mem를 설정한 후 apigee-org 차트에서 helm upgrade를 실행해야 합니다. 환경별 및 전체 설치 변형, 메시지 프로세서 힙 크기 조정 안내, 전체 overrides.yaml 예시를 포함한 전체 절차는 Apigee Hybrid에서 대용량 메시지 페이로드 지원 구성을 참조하세요. 응답 한도를 높여도 50MiB MCP 프록시 번들 크기 한도에는 영향을 미치지 않습니다. 용량이 이 한도로 제한되는 경우 이 변경사항은 도움이 되지 않습니다.

보안

신뢰 경계

MCP 데이터 영역은 자체 Kubernetes 클러스터 내에서 실행됩니다. Google은 데이터 영역에 대한 런타임 액세스 권한이 없습니다. Apigee 컨트롤 플레인은 OpenAPI 사양에서 파생된 MCP 구성을 제공하며 MCP 요청 트래픽을 관찰하지 않습니다. 저장 구성 데이터는 Apigee 테넌트 프로젝트로 범위가 지정된 Apigee 관리형 Cloud Storage 버킷에 저장되며, MCP 사이드카에서 주변 Google Cloud 서비스 계정을 사용하여 가져옵니다.

Apigee Operator는 MCP 데이터 영역 ServiceAccount를 위해 Apigee 네임스페이스(APIGEE_NAMESPACE)에 MCP 범위 Kubernetes Role 및 RoleBinding를 프로비저닝합니다. 역할은 읽기 전용 액세스 권한을 부여합니다.

  • 핵심 API 그룹의 services에 있는 get, list, watch
  • apigee.cloud.google.com API 그룹의 apigeeroutes에 대한 get, list, watch입니다.
  • 1.17.4 이상: 핵심 API 그룹의 secrets에 대한 get, list, watch MCP 데이터 영역은 이를 사용하여 클라이언트 인증서를 읽고 virtualhosts[].mcpMtls로 이름이 지정된 CA 보안 비밀을 신뢰하고 순환을 감지합니다(MCP 데이터 영역과 인그레스 게이트웨이 간에 mTLS 구성 참조). 이 권한 부여는 읽기 전용이지만 Apigee 네임스페이스의 모든 보안 비밀을 포함합니다. Kubernetes RBAC는 list 및 watch를 명명된 보안 비밀로 제한할 수 없습니다. 환경 그룹에 mcpMtls가 구성되어 있는지 여부에 관계없이 표시됩니다.

이 역할은 쓰기 동사를 부여하지 않으며 ConfigMaps 또는 포드 상태에 대한 액세스 권한을 부여하지 않습니다. 감사자는 클러스터에서 직접 다음을 사용하여 정확한 규칙을 확인할 수 있습니다.

APIGEE_ORG_CR=$(kubectl get apigeeorganization -n APIGEE_NAMESPACE \
  -o jsonpath='{.items[0].metadata.name}')
kubectl get role,rolebinding -n APIGEE_NAMESPACE \
  --field-selector metadata.name=apigee-mcp-server-$APIGEE_ORG_CR -o yaml

apigee-mcp-server-APIGEE_ORG_CR 역할 및 RoleBinding은 MCP 범위 RBAC 리소스입니다. 이름에는 ApigeeOrganization 커스텀 리소스의 전체 이름이 포함됩니다(Apigee 조직 이름과 짧은 해시에서 파생됨). 리소스 수준에서 app=apigee-mcp-server 라벨을 전달하지 않으므로(포드만 전달) 라벨 기반 조회는 결과를 반환하지 않습니다. 위의 필드 선택기 명령어가 아무것도 반환하지 않으면 다음을 사용하여 네임스페이스의 모든 MCP 관련 RBAC 리소스를 나열합니다.

kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server

메시지 프로세서와 MCP 데이터 영역 간의 TLS

메시지 프로세서 포드는 https://mcp.apigee.internal/ 또는 https://ORG_NAME.mcp.apigee.internal/에서 MCP 데이터 영역을 호출합니다. 이러한 호스트 이름은 삽입된 hostAliases 항목을 통해 MCP 서비스 ClusterIP로 확인됩니다. MCP 데이터 영역 컨테이너는 Apigee-operator-provisioned 발급기관(apigee-ca-issuer라는 ClusterIssuer)이 서명한 TLS 인증서를 제공합니다. 인증서의 주체 대체 이름에는 두 호스트 이름이 모두 포함됩니다.

MCP 데이터 영역과 인그레스 게이트웨이 간의 TLS

MCP 데이터 영역은 환경 그룹의 호스트 별칭을 사용하여 각 도구 호출을 포트 443의 Apigee 인그레스 게이트웨이로 전달합니다. 기본적으로 이 연결은 단방향 TLS이며 MCP 데이터 영역은 인그레스 게이트웨이의 인증서를 확인하지 않습니다. 1.17.4 이상에서는 환경 그룹별로 이 연결에 상호 인증을 요구할 수 있습니다. MCP 데이터 영역과 인그레스 게이트웨이 간에 mTLS 구성을 참조하세요.

MCP 서비스에 대한 인바운드 액세스 제한

Apigee Hybrid 1.17.0에서 MCP 데이터 영역은 호출자를 독립적으로 인증하지 않습니다. 도달하는 요청이 메시지 프로세서에서 실행되는 Apigee MCP 프록시에 의해 이미 인증되었다고 신뢰합니다. MCP 서비스의 유일한 호출자는 메시지 프로세서입니다. TCP 443에서 MCP 서비스 ClusterIP에 도달할 수 있는 다른 클러스터 내 워크로드는 인증 확인 없이 MCP 도구를 호출할 수 있습니다.

플랫폼의 클러스터 인그레스 정책 엔진(Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy 또는 이와 동등한 기능)을 사용하여 MCP 포드에 대한 인바운드 액세스를 메시지 프로세서 포드로만 제한합니다. 제한사항:

  • 동일한 네임스페이스에 있는 라벨 app=apigee-runtime이 지정된 포드에서만 TCP 443의 네임스페이스 APIGEE_NAMESPACE에 있는 라벨 app=apigee-mcp-server이 지정된 포드로의 인그레스를 허용합니다.
  • app=apigee-mcp-server 라벨이 있는 포드에 대한 TCP 443의 다른 모든 인그레스를 거부합니다.
  • 라벨이 app=apigee-mcp-server인 포드에 대한 TCP 15021의 모든 클러스터 내 인그레스를 거부합니다. 포트 15021은 준비 상태 프로브를 위해 kubelet에서 사용하는 인증되지 않은 일반 HTTP /healthz/ready 엔드포인트를 제공합니다. kubelet은 포드 IP에서 직접 연결하므로 다른 클러스터 내 워크로드가 15021의 MCP 포드에 도달해서는 안 됩니다.

MCP 빠른 시작을 완료하고 비개발 환경에 첫 번째 MCP 검색 프록시를 배포하기 전에 이 제한사항을 적용하세요.

구성 최신 상태 계약

MCP 사이드카가 구성 가져오기를 완료하면 MCP 데이터 영역 컨테이너가 가져온 번들을 로드하고 다음 가져오기가 완료될 때까지 계속 제공합니다. 후속 가져오기가 실패하면(Apigee 컨트롤 플레인에 연결할 수 없음, Cloud Storage에 연결할 수 없음, 감시자 서비스 계정에서 IAM 권한이 삭제됨, 가져오기 파이프라인의 다른 단계에서 오류 발생) 사이드카는 마지막으로 알려진 양호한 번들을 무기한으로 계속 제공합니다. 1.17.0에는 기본 제공되는 비활성 한도가 없습니다. 포드는 Ready 상태로 유지되고 MCP 도구 트래픽은 비활성 번들에 대해 계속 제공됩니다. 구성 새로고침이 중지되었다는 신호는 consecutive_failures 카운터를 전달하는 ERROR 수준의 사이드카 로그 줄입니다(실패 단계별로 사이드카가 내보내는 특정 메시지는 MCP 배포 문제 해결 참조).

규제 대상 프로덕션 환경의 경우 이 카운터의 반복 증가에 대한 페이지입니다. 최소 실행 가능 알림은 MCP 사이드카 컨테이너가 ERROR 수준 로그 줄을 내보내고 consecutive_failures가 비활성 허용치에 따라 설정한 기준점에 도달할 때 호출됩니다. 값이 증가하면 사이드카가 구성 새로고침을 중지했음을 나타냅니다. 사이드카는 그동안 마지막으로 성공한 번들을 계속 제공합니다.

사이드카가 구성 새로고침을 중지한 경우 사이드카 로그에서 실패 모드를 조사합니다. MCP 배포 문제 해결을 참조하세요. 새로 생성된 포드가 동일한 가져오기 경로에 도달하므로 MCP 포드를 바운스해도 기본 가져오기 문제가 해결되지 않습니다.

아웃바운드 네트워크 요구사항

MCP 사이드카(각 MCP 포드 내의 구성 컨테이너)에는 TCP 443의 다음 엔드포인트에 대한 아웃바운드 네트워크 액세스가 필요합니다. Apigee 조직에서 데이터 레지던시를 사용하는지 여부에 따라 탭을 선택합니다. 필요한 엔드포인트가 다릅니다.

데이터 상주 없음

엔드포인트 연결 대상:
apigee.googleapis.com 구성 새로고침마다 Apigee 컨트롤 플레인에서 조직의 현재 MCP 구성 참조를 가져옵니다.
storage.googleapis.com Google Cloud Storage에서 조직의 MCP 구성을 다운로드합니다.

데이터 상주

Apigee 조직에서 데이터 상주를 사용하는 경우 MCP 사이드카는 리전 Apigee 컨트롤 플레인 엔드포인트(다른 Apigee Hybrid 구성요소에서 사용하는 것과 동일한 엔드포인트로, overrides.yaml의 contractProvider 차트 값을 통해 구성됨)에 도달합니다. CONTROL_PLANE_LOCATION를 조직의 컨트롤 플레인 위치(예: us, eu)로 바꿉니다.

엔드포인트 연결 대상:
CONTROL_PLANE_LOCATION-apigee.googleapis.com 구성 새로고침마다 리전 Apigee 컨트롤 플레인 엔드포인트에서 조직의 현재 MCP 구성 참조를 가져옵니다.
storage.googleapis.com Google Cloud Storage에서 조직의 MCP 구성을 다운로드합니다. 버킷은 조직의 리전에 있으며 Cloud Storage는 자동으로 해당 버킷으로 라우팅합니다.

또한 사이드카는 포드가 실행되는 주변 사용자 인증 정보(워크로드 아이덴티티 또는 파일 기반 서비스 계정 키를 통해)에 대한 Google Cloud 액세스 토큰을 가져올 수 있어야 합니다. 특정 토큰 교환 엔드포인트는 인증 경로에 따라 다르며 다른 Apigee Hybrid 구성요소가 클러스터에서 이미 사용하는 것과 동일합니다. 이 네임스페이스에서 Google Cloud API로의 기존 Apigee Hybrid 트래픽이 성공하면 MCP 사이드카의 토큰 교환도 성공합니다.

또한 사이드카는 활성 및 준비 상태를 게시하기 위해 (표준 클러스터 내 서비스 주소를 통해) Kubernetes API 서버에 대한 클러스터 내 액세스가 필요합니다. 이 트래픽은 클러스터를 벗어나지 않습니다.

문제 해결

전체 진단 체크리스트는 Apigee Hybrid의 클러스터 측 진단 체크리스트가 포함된 MCP 배포 문제 해결을 참조하세요.

일반적인 설치 실패

증상 원인 및 해결 방법
helm upgrade가 완료되었지만 MCP 리소스가 표시되지 않습니다. 조직 차트가 오퍼레이터 차트보다 먼저 업그레이드되었습니다. 먼저 helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/를 실행한 후 helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/를 다시 실행합니다.
MCP 포드가 ContainerCreating 또는 1/2 Ready에서 멈춤 두 가지 일반적인 원인: MCP의 cert-manager Certificate가 아직 발급되지 않았거나 컨테이너 이미지 가져오기가 실패했습니다. 영향을 받는 포드에서 kubectl describe pod를 실행하여 정확한 이유를 확인합니다.
Sidecar(apigee-mcp-server-config)는 모든 폴링에서 no MCP config from CP yet; skipping tick, pod stays Ready via seed를 보고합니다. 조직에 MCP 검색 프록시가 아직 배포되지 않은 경우 예상되는 안정 상태입니다. Apigee 컨트롤 플레인은 빈 구성 참조를 반환하고 MCP 데이터 영역에는 포트 15021에 로드된 Kubernetes 준비 리스너만 있습니다. MCP 요청 포트 8443에는 아직 리스너가 없으며 https://mcp.apigee.internal/mcp에 대한 요청은 연결 거부를 수신합니다. 제공 상태로 전환하려면 MCP 빠른 시작에 따라 이 클러스터에서 제공하는 환경 그룹의 환경에 MCP 탐색 프록시를 배포합니다.
사이드카 로그는 삽입된 HTTP 403 또는 PermissionDenied와 함께 CP fetch failed를 보고합니다. Apigee 감시자 Google Cloud 서비스 계정이 Apigee 테넌트 프로젝트에서 roles/apigee.runtimeAgent 역할(사이드카에 필요한 apigee.runtimeconfigs.get 권한 부여)을 상실했습니다. 기본 Apigee Hybrid 설치는 이 역할을 자동으로 부여합니다. IAM 자동화 스윕으로 삭제된 경우 apigee-watcher Google Cloud 서비스 계정에 다시 적용합니다.
사이드카 로그는 context deadline exceeded, DNS 오류 또는 TLS 오류와 함께 CP fetch failed를 보고합니다. 사이드카가 클러스터 내부에서 apigee.googleapis.com 또는 storage.googleapis.com에 연결할 수 없습니다. 위의 아웃바운드 네트워크 요구사항에 나열된 세 개의 엔드포인트에 대해 이그레스를 확인합니다.
helm upgrade 이후 메시지 프로세서 포드가 다시 시작되지 않았습니다. 모든 MP 포드에 hostAliases 항목이 있는지 확인합니다. kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}' 포드가 비어 있으면 포드(kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime)를 삭제하여 새로 렌더링합니다. ApigeeDeployment 컨트롤러는 hostAliases 항목이 포함된 현재 사양에서 다시 만듭니다. kubectl rollout restart deploy를 사용하지 마세요. ApigeeDeployment에는 적용되지 않습니다.
MCP 도구 트래픽이 빠른 시작을 통해 흐르기 시작한 후 MP 포드 로그에 https://mcp.apigee.internal/ 또는 https://ORG_NAME.mcp.apigee.internal/를 호출하는 TLS 핸드셰이크 오류가 표시됩니다. MCP 데이터 영역 컨테이너가 주체 대체 이름(SAN)에 MP가 다이얼한 호스트 이름이 포함되지 않은 인증서를 제공하고 있습니다. 인증서를 확인합니다. kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server, kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml 인증서의 dnsNames에는 mcp.apigee.internal 및 소문자 ORG_NAME.mcp.apigee.internal가 모두 포함되어야 합니다. 그렇지 않으면 MCP Certificate 리소스를 삭제하고 cert-manager에서 다시 발급하도록 합니다.

다음 단계