Apigee에서 MCP 배포 문제 해결

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

Apigee Edge 문서 보기

이 페이지에서는 MCP 검색 프록시 배포와 관련된 문제를 해결하는 방법을 설명합니다. 이 페이지를 사용하여 MCP 배포의 비동기 프로비저닝 수명 주기를 이해하고, 오류 코드를 해결하고, 런타임 연결을 확인할 수 있습니다.

MCP 배포 이해

MCP 탐색 프록시 배포는 프록시 배포가 완료되기 전에 구성이 Apigee 및 Google Cloud 인프라 전반에 완전히 전파되도록 하는 비동기식 다단계 프로세스입니다.

이러한 다운스트림 프로비저닝 단계가 진행되는 동안 UI에는 프록시가 프로비저닝 상태로 표시됩니다. 프로세스가 완료되면 상태가 배포됨으로 변경됩니다. 이 상태는 모든 다운스트림 구성요소가 완전히 프로비저닝되었으며 프록시가 트래픽을 처리할 준비가 되었음을 확인합니다.

문제 해결

다음 섹션에서는 Apigee에서 MCP를 사용하는 동안 발생할 수 있는 오류와 알려진 문제를 설명합니다.

문제: 백엔드가 쿼리 문자열, 헤더, 쿠키 등 하나의 요청 위치에서 도구 인수를 읽지만 OpenAPI 사양이 매개변수 in를 다른 위치로 선언하므로 인수가 백엔드 요청의 다른 위치에 도착합니다. 호출이 실패하거나 인수가 없는 것처럼 작동합니다.

증상: tools/call 요청이 MCP 레이어에서 성공하고 MCP 클라이언트가 인수를 제공하지만 백엔드가 값이 누락된 것처럼 응답합니다(예: 필수 값의 경우 400 또는 전송된 값 대신 기본값이 적용됨).

원인: 파라미터가 OpenAPI 사양에서 in: header 또는 in: cookie로 선언되므로 Apigee는 해당 값을 쿼리 문자열이 아닌 요청 헤더 또는 Cookie 헤더로 전송합니다. 쿼리 문자열에서만 값을 읽는 백엔드에는 이 값이 표시되지 않습니다. 백엔드 요청의 도구 인수 배치를 참고하세요.

해결 방법: 값이 속하는 위치를 결정하고 사양과 백엔드가 일치하도록 합니다.

  • 쿼리 문자열에 값을 유지하려면 in: query 매개변수를 선언합니다.
  • 헤더 또는 쿠키로 전송하려면 선언을 그대로 두고 백엔드의 해당 위치에서 값을 읽습니다.

문제: MCP 클라이언트가 수행하는 HTTP 요청에 도착하는 쿠키(예: 브라우저 기반 클라이언트의 세션 쿠키)가 일부 도구 호출에서 백엔드에 도달하지 않습니다.

증상: 백엔드가 호출자가 인증되지 않았거나 세션에 없는 것처럼 동작하며 동작이 일관되지 않습니다. 동일한 작업이 일부 호출에서는 작동하고 다른 호출에서는 작동하지 않습니다.

원인: 작업에서 하나 이상의 in: cookie 매개변수를 선언하고 영향을 받는 호출에서 이 중 하나 이상을 제공했습니다. Cookie 헤더는 추가되는 것이 아니라 전체적으로 다시 작성되므로 이러한 호출에서는 선언된 쿠키 매개변수만 전달하고 다른 모든 쿠키는 삭제됩니다. 쿠키 매개변수를 제공하지 않은 호출은 헤더를 그대로 전달하므로 일부 호출만 실패합니다. 백엔드 요청의 쿠키를 참조하세요.

해결 방법: 백엔드에 필요한 모든 쿠키를 필요한 각 작업에서 in: cookie 매개변수로 선언하여 해당 값이 클라이언트 요청에서 상속되는 대신 항상 도구 호출에 의해 제공되도록 합니다. 선언되지 않은 쿠키를 보존하는 설정은 없습니다.

도구 호출 및 메타데이터의 오류 응답 상태 코드

Apigee MCP 엔드포인트는 모델 컨텍스트 프로토콜(MCP) 사양 및 관련 OAuth 표준을 따르는 HTTP 상태 코드를 반환합니다. 이 동작을 이해하면 MCP 클라이언트 또는 AI 에이전트의 오류를 올바르게 처리하는 데 도움이 됩니다.

다음 표에는 Apigee MCP 엔드포인트에서 반환하는 상태 코드가 요약되어 있습니다.

시나리오 HTTP 상태 코드 응답 본문
tools/call에서 도구 실행이 실패합니다(예: 백엔드 API가 검증 오류 또는 필수 입력란 누락과 같은 4xx 또는 5xx 오류를 반환함). 200 OK result.isError가 true로 설정되고 content에 오류 세부정보가 있는 CallToolResult입니다. 이렇게 하면 MCP 클라이언트와 LLM 에이전트가 오류를 읽고 세션을 종료하는 대신 복구할 수 있습니다(예: 누락된 입력을 다시 요청하고 다시 시도).
OAuth 보호 리소스 메타데이터(PRM)가 구성되지 않았거나 /.well-known/oauth-protected-resource/mcp에서 찾을 수 없습니다. 404 Not Found 요청된 위치에 보호된 리소스 메타데이터가 없음을 나타냅니다.
액세스 토큰이 누락되었거나 잘못되었거나 만료되었습니다. 401 Unauthorized OAuth 탐색 흐름을 유도하는 WWW-Authenticate 챌린지가 포함됩니다.
액세스 토큰의 범위가 부족합니다. 403 Forbidden 승격 승인 흐름을 유도하는 WWW-Authenticate 챌린지가 포함됩니다.

예시: 도구 실행 오류 응답 본문

도구 호출이 실패하면 Apigee MCP는 HTTP 200 OK를 반환하고 JSON-RPC result 객체에서 실패를 보고하며 isError는 true로 설정됩니다. 백엔드에서 반환된 원래 오류는 보존됩니다. 백엔드 응답 본문은 result.content[].text에 문자열로 그대로 배치됩니다. 예를 들어 백엔드가 본문 {"error":"User 42 not found"}과 함께 HTTP 404를 반환하는 경우 MCP 응답은 다음과 같습니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

id는 tools/call 요청의 id와 일치합니다. 백엔드가 응답 본문을 반환하지 않으면 text에 생성된 요약(예: Operation failed (HTTP 500).)이 대신 포함됩니다.

MCP 클라이언트는 HTTP 상태 코드가 아닌 result.isError를 검사하여 실패한 도구 호출을 감지해야 합니다. 클라이언트 코드가 도구 실행 오류를 알리기 위해 4xx 또는 5xx HTTP 상태를 구체적으로 예상하는 경우 오류를 감지하지 않습니다. 응답이 HTTP 200 OK이기 때문입니다. result.isError 및 content 배열을 읽도록 이러한 클라이언트를 업데이트합니다.

프로토콜 수준 오류(예: 잘못된 형식의 JSON-RPC 요청)는 도구 실행 오류와 구분됩니다. 이러한 오류는 result.isError가 아닌 JSON-RPC error 객체(예: {"jsonrpc": "2.0", "error": {"code": -32700, ...}})에서 계속 반환됩니다.

권장사항: 표준을 준수하는 MCP 클라이언트는 기본 로직을 통해 이러한 상태 코드를 처리하므로 변경할 필요가 없습니다. 이전에 비표준 상태 코드를 처리하기 위해 클라이언트 측 해결 방법을 추가한 경우(예: tools/call 오류에 대해 2xx가 아닌 응답 본문 파싱 또는 PRM 엔드포인트의 500 응답을 '메타데이터가 구성되지 않음'으로 처리) 해당 해결 방법을 삭제하는 것이 좋습니다. 그렇지 않으면 클라이언트가 수정된 상태 코드를 정상적으로 처리하는 대신 오래된 처리 로직을 계속 사용할 수 있습니다.

브라우저 기반 MCP 호출을 위한 CORS 정책

Apigee MCP 호출이 브라우저에서 직접 수행되는 경우(예: MCP 검사기가 '프록시를 통해' 대신 '직접' 설정을 사용하는 경우) 교차 출처 리소스 공유(CORS) 정책이 필요합니다. MCP 검색 프록시 템플릿에는 브라우저 기반 호출을 사용 설정하기 위해 기본적으로 프록시 번들의 프록시 엔드포인트 요청 PreFlow에 Apigee CORS 정책이 포함되어 있습니다.

브라우저에서 직접 호출할 때 CORS 관련 문제가 발생하면 MCP 검색 프록시 번들의 프록시 엔드포인트 요청 PreFlow에서 CORS 정책 설정을 조정해야 할 수 있습니다.

MCP 엔드포인트에 요청을 전송할 때 JSON 파싱 오류 발생

MCP 엔드포인트에 요청을 전송할 때 다음과 유사한 오류 메시지(또는 다른 오류 코드 및 메시지)가 표시될 수 있습니다.

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

이 경우 다음 정보를 확인하는 것이 좋습니다.

  • 올바른 MCP 엔드포인트 URL을 입력했습니다.
  • 요청 형식이 올바릅니다.
  • 지원되는 메서드에 액세스하고 있습니다.
  • 지원되는 지역에서 MCP 검색 프록시를 사용 설정하고 구성했습니다. 용량 제한이 있을 수 있는 리전 목록은 배포 실패를 참고하세요.

배포 실패

MCP 검색 프록시 배포가 UI에서 실패 상태로 실패하면 오류 메시지에서 자세한 내용을 확인하세요. 일반적인 오류는 다음과 같습니다.

  • 네트워킹 구성 실패 또는 OAS에서 지원되지 않는 스키마: 이러한 오류는 일반적으로 OpenAPI 사양에 문제가 있음을 나타냅니다. 사양이 유효하고 지원되는 버전을 사용하는지 확인합니다.
  • 리전 용량 한도(Apigee만 해당): 부하 분산기 프로비저닝 실패와 관련된 오류가 표시되거나 프로비저닝 상태가 배포됨으로 변경되지 않는 경우 다음 리전 중 하나의 일시적인 인프라 용량 한도 때문일 수 있습니다.
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    이 오류를 해결하려면 다른 리전의 환경에 프록시를 배포해 보세요. 이 오류 모드는 런타임 인프라가 자체 클러스터인 Apigee Hybrid에는 적용되지 않습니다.

  • 클러스터에서 MCP가 사용 설정되지 않음(Apigee Hybrid만 해당): MCP 프록시 배포가 무기한으로 프로비저닝 상태로 유지되고 배포됨 상태에 도달하지 않으면 클러스터에서 MCP가 사용 설정되어 있는지 확인합니다. 아래의 클러스터 측 진단을 참조하세요.

클러스터 측 진단(Apigee Hybrid만 해당)

Apigee Hybrid MCP 데이터 영역은 자체 Kubernetes 클러스터 내에서 실행되므로 클러스터 내 오류 모드는 클러스터에 대해 kubectl로 진단됩니다. 다음 진단 체크리스트를 순서대로 진행합니다.

1단계: 클러스터에서 MCP가 사용 설정되어 있는지 확인

MCP는 일반 Kubernetes Deployment가 아닌 ApigeeDeployment 커스텀 리소스(Apigee Operator에서 관리)로 배포됩니다. MCP ApigeeDeployment를 확인합니다.

kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server

예상 출력(리소스 이름에는 조직에서 파생된 서픽스가 포함되며 여기서는 ORG_CR_SUFFIX로 표시됨):

NAME                                     STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX       running                 1h

명령어가 No resources found in APIGEE_NAMESPACE namespace.를 반환하면 MCP가 사용 설정되지 않은 것입니다. Apigee Hybrid에서 MCP 사용 설정로 돌아가서 enableMcpServer: true가 overrides.yaml에서 최상위 키로 설정되어 있고 apigee-org 출시 전에 apigee-operator Helm 출시를 업그레이드했는지 확인합니다. 올바른 helm 명령어는 사용 설정 절차의 3단계 및 4단계를 참조하세요.

2단계: MCP 포드가 실행 중인지 확인

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server

예상 출력(포드 서픽스는 다를 수 있음):

NAME                                                              READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-1170-abcd1234   2/2     Running   0          1h
apigee-mcp-server-default-ORG_CR_SUFFIX-1170-efgh5678   2/2     Running   0          1h

포드 이름은 apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH 템플릿을 따릅니다. 여기서 REV은 4자리 하이브리드 출시 버전 버전(예: 하이브리드 1.17.0의 경우 1170)이고 POD_HASH은 포드마다 다른 8자 영숫자 서픽스입니다.

모든 포드는 READY 열에 2/2을, STATUS 열에 Running을 표시해야 합니다. 포드가 Running가 아니면 kubectl -n APIGEE_NAMESPACE describe pod POD_NAME에 이유가 표시됩니다. 일반적인 원인은 이미지 가져오기 실패(클러스터에서 overrides.yaml에 구성된 이미지 레지스트리로의 이그레스 확인) 및 CPU 또는 메모리 여유 공간 부족(overrides.yaml에서 mcpServer.resources.requests 증가)입니다.

3단계: 사이드카 구성 가져오기 상태 확인

각 MCP 포드의 apigee-mcp-server-config 사이드카 컨테이너는 Apigee 컨트롤 플레인에서 MCP 구성을 주기적으로 가져옵니다. 가져올 때마다 apigee.googleapis.com에서 현재 구성 참조를 가져온 다음 Cloud Storage에서 참조된 구성 번들을 가져옵니다. MCP 데이터 영역은 유효한 구성으로 가져오기가 완료되면 https://mcp.apigee.internal/mcp에서 MCP 도구 트래픽을 제공하기 시작합니다.

유효한 구성으로 첫 번째 가져오기가 성공하기 전에는(조직에 MCP 탐색 프록시가 아직 배포되지 않았거나 사이드카가 컨트롤 플레인에 도달할 수 없기 때문) MCP 포드가 Ready 상태로 유지되지만 https://mcp.apigee.internal/mcp에 대한 요청은 연결 거부됨으로 실패합니다.

사이드카 로그를 검사하여 어떤 경우에 해당하는지 확인합니다.

kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
  • 컨트롤 플레인에서 MCP 구성이 없음을 나타내는 info 줄 반복:
    {"level":"info","ts":1787582542.68,"caller":"mcpsidecar/sidecar.go:397","msg":"mcpsidecar: no MCP config from CP yet; skipping tick, pod stays Ready via seed","org":"YOUR_ORG","mcp_server_id":"default"}
    Apigee 컨트롤 플레인이 성공적인 응답을 반환했지만 조직에 MCP 검색 프록시가 아직 배포되지 않았습니다. 이는 온보딩 중에 예상되는 안정적인 상태입니다. MCP 데이터 영역을 서빙 상태로 전환하려면 MCP 빠른 시작에 따라 MCP 탐색 프록시를 배포합니다.
  • consecutive_failures 카운터가 있는 error 줄:
    {"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}
    사이드카 로그는 구조화된 JSON입니다. consecutive_failures 카운터가 증가하는 "level":"error"가 표시되면 사이드카가 구성 가져오기를 완료할 수 없습니다. 사이드카는 백오프를 사용하여 자동으로 재시도하고 다음 가져오기가 성공하면 카운터를 0으로 재설정합니다.

    이 카운터가 계속 증가할 때 확인해야 할 일반적인 근본 원인은 다음과 같습니다.

    • apigee-watcher Google Cloud 서비스 계정이 Apigee 조직의 controlPlaneAccess 리소스에 있는 watcher_identities 목록에 없습니다. 사용 설정 절차의 2단계: 컨트롤 플레인의 MCP 구성에 대한 감시자 ID 액세스 권한 부여를 참고하여 권한을 추가하고 적용되었는지 확인합니다.
    • 클러스터에서 apigee.googleapis.com 또는 storage.googleapis.com로의 이그레스가 차단됩니다. 두 엔드포인트 모두 MCP 포드에서 연결할 수 있어야 합니다(사용 설정 절차의 아웃바운드 네트워크 요구사항 참조).
    • apigee-watcher 서비스 계정은 이 클러스터에서 Google Cloud 액세스 토큰을 가져올 수 없습니다. 동일한 네임스페이스의 기존 Apigee Hybrid 구성요소에서도 인증 실패가 보고되는 경우 공유 인증 문제를 먼저 해결합니다.
    • 일시적인 Apigee 컨트롤 플레인 또는 Cloud Storage 오류입니다. 위의 원인을 배제한 후에도 카운터가 장기간 계속 상승하면 Apigee 지원팀에 문의하세요.

4단계: 메시지 프로세서 hostAliases가 삽입되었는지 확인

MCP를 사용 설정하면 Apigee 연산자가 메시지 프로세서(MP) 포드 사양에 hostAliases 항목 하나를 삽입합니다. 이 항목에는 IP 하나(MCP 서비스 ClusterIP)와 호스트 이름 두 개(mcp.apigee.internal 및 소문자 ORG_NAME.mcp.apigee.internal)가 포함됩니다. 삽입이 성공했는지 확인합니다.

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

나열된 모든 MP 포드에는 mcp.apigee.internal와 MCP 서비스 ClusterIP를 가리키는 소문자 ORG_NAME.mcp.apigee.internal가 모두 포함된 hostAliases 항목이 있어야 합니다. 비어 있거나 누락된 항목을 표시하는 MP 포드는 MCP가 사용 설정되기 전에 생성되었습니다. ApigeeDeployment 컨트롤러가 현재 포드 사양(삽입된 hostAliases 항목 포함)에서 다시 만들도록 영향을 받는 MP 포드를 삭제합니다.

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

5단계: 엔드 투 엔드 인증

MCP 데이터 영역을 통해 실제 MCP initialize 요청을 전송하는 엔드 투 엔드 테스트의 경우 MCP 탐색 프록시를 배포하고 MCP 빠른 시작을 따르세요. 조직에 MCP 검색 프록시가 배포되기 전에는 메시지 프로세서가 MCP 포드에 도달할 수 있는지 여부와 관계없이 https://mcp.apigee.internal/mcp에 대한 요청이 연결 거부됨으로 실패합니다(3단계 참조).

6단계: 인그레스 게이트웨이에 대한 mTLS 확인(구성된 경우)

이 단계는 환경 그룹에 virtualhosts[].mcpMtls를 구성한 경우에만 적용됩니다(Apigee Hybrid 1.17.4 이상). mTLS 문제의 일반적인 증상은 MCP 데이터 영역이 환경 그룹별로 인증서 구성을 유지하기 때문에 하나의 환경 그룹(일반적으로 503 Service Unavailable)에 대한 MCP 도구 호출은 실패하고 다른 환경 그룹에 대한 호출은 성공하는 것입니다.

  1. 사업자가 필드를 수락했는지 확인합니다. 환경 그룹의 라우팅 리소스는 mcpMtls 블록을 전달해야 합니다.
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    apigee-virtualhost 업그레이드 후 몇 분이 지나도 두 번째 열이 비어 있으면 일반적으로 클러스터의 Apigee 커스텀 리소스 정의가 1.17.4보다 오래되었고 mcpMtls를 선언하지 않으므로 API 서버가 필드를 삭제했음을 의미합니다. (감시자 이미지를 제공하는 apigee-org 차트가 1.17.4로 업그레이드되지 않은 경우도 있습니다.) 이는 업그레이드가 연산자 차트에 대해 helm upgrade를 실행했지만 업데이트된 Apigee CRD 설치 단계를 건너뛴 경우에 발생합니다. 그러면 MCP 데이터 영역은 여전히 단방향 TLS를 사용하고 MUTUAL 모드의 인그레스 게이트웨이는 이를 거부합니다. 동일한 비활성 CRD로 인해 다음 단계의 AIS_MCP_MTLS_* 문제가 보고되지 않습니다. 다음으로 확인하고 수정합니다.
    kubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls   # 0 means the CRDs are stale
    kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
    Helm 차트 디렉터리에서 kubectl apply를 실행한 후 환경 그룹에 대해 apigee-virtualhost 업그레이드를 다시 실행합니다.
  2. 클러스터에서 보고한 인증서 문제를 확인합니다. 감시자는 구성된 보안 비밀을 스캔하고 각 문제에 대해 ApigeeIssue를 만듭니다.
    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)'
    kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
    Spec.Details 필드는 문제가 속한 보안 비밀과 ApigeeRouteConfig(ORG_NAME-ENV_GROUP_NAME) 및 특정 결함의 이름을 지정합니다.
    이유 심각도 의미 수정
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR 클라이언트 인증서 보안 비밀이 존재하지 않거나(secret not found), cert 또는 key 항목이 누락되었거나, 항목이 비어 있거나 PEM이 아니거나, 인증서와 키가 일치하지 않거나, 인증서의 확장된 키 사용에서 clientAuth가 생략되었습니다. MCP 데이터 영역은 이를 로드하지 않습니다. 보안 비밀(옵션 2) 또는 helm upgrade 뒤에 오는 파일(옵션 1)을 만들거나 수정합니다. 확장 키 사용이 문제인 경우 clientAuth를 사용하여 인증서를 다시 발급합니다.
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY 만료 후 14일 이내 WARNING, 이후 ERROR 클라이언트 인증서가 곧 만료되거나 이미 만료되었습니다. 만료된 인증서가 계속 표시되고 인그레스 게이트웨이가 핸드셰이크를 거부합니다. 인증서 순환에 설명된 대로 인증서를 순환합니다.
    AIS_MCP_MTLS_CA_CERT_INVALID ERROR -cacert 보안 비밀이 존재하지 않거나(secret not found, sslSecret를 사용하여 직접 만듦) cacert 항목이 누락되었거나, 항목이 PEM이 아니거나, 블록이 인증서가 아니거나, 인증서가 CA 인증서가 아닙니다. 필요한 경우 보안 비밀을 만들고 인그레스 게이트웨이의 인증서에 서명한 CA 인증서(또는 체인)를 cacert 항목에 넣습니다.
    AIS_MCP_MTLS_CA_CERT_EXPIRY 만료 후 14일 이내 WARNING, 이후 ERROR -cacert 보안 비밀의 CA 인증서가 곧 만료되거나 만료되었습니다. 만료 후 MCP 데이터 영역은 더 이상 인그레스 게이트웨이의 인증서 체인을 신뢰하지 않습니다. -cacert 보안 비밀의 CA 인증서가 만료되기 전에 인그레스 게이트웨이의 자체 인증서와 함께 교체합니다(재발급되는 경우).
    보안 비밀이 수정되면 다음 스캔에서 문제가 자동으로 철회됩니다.
  3. 사이드카의 mTLS 메시지를 읽습니다. apigee-mcp-server-config 컨테이너는 환경 그룹의 인증서를 적용할 수 없을 때마다 error 줄을 로깅합니다. 각 줄에는 일반적으로 env_group, secret(체인 검증이 사용 설정된 경우 trust-Secret 필드), reason 코드, 래핑된 오류 텍스트와 같은 필드가 포함됩니다. 안정적인 식별자인 reason 코드 값으로 필터링합니다. 다른 필드 이름에 의존하지 마세요.
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    최근 기간이 아닌 전체 로그를 검색합니다. 잘못된 보안 비밀은 새로고침할 때마다 보고되는 것이 아니라 사이드카에서 처음 발견할 때(그리고 변경될 때 다시) 보고됩니다.

    다음 이유 코드는 현재 출시 버전에서 안정적입니다. 목록에 없는 코드가 표시되면 Google Cloud Customer Care에 문의하세요.

    reason 의미 작업
    MCP_MTLS_SECRET_NOT_FOUND 참조된 보안 비밀이 Apigee 네임스페이스에 없습니다. error 텍스트는 이름과 클라이언트 또는 트러스트 보안 비밀인지 여부를 지정합니다. 정확한 이름으로 보안 비밀을 만듭니다(트러스트 CA의 -cacert 서픽스 기억). 사이드카는 새 보안 비밀을 자체적으로 인식합니다.
    MCP_MTLS_MATERIAL_UNUSABLE 보안 비밀이 있지만 콘텐츠가 거부됨: 데이터 키가 누락되었거나 비어 있음, PEM이 아닌 콘텐츠, 페어링되지 않은 인증서 및 키, clientAuth가 없는 클라이언트 인증서 또는 CA 인증서가 없는 트러스트 보안 비밀 동일한 결함이 ApigeeIssue(이전 단계)로 보고됩니다. 보안 비밀 콘텐츠를 수정합니다. 보안 비밀을 수정하면 새 시도가 트리거됩니다.
    MCP_MTLS_SECRET_READ_FAILED, MCP_MTLS_SECRET_WATCH_FAILED, MCP_MTLS_SECRET_ACCESS_FAILED 사이드카가 Kubernetes API를 통해 보안 비밀을 읽거나 감시할 수 없습니다(API 서버를 사용할 수 없거나 MCP 역할이 secrets 권한을 상실함). MCP_MTLS_SECRET_READ_FAILED 줄에는 재시도 컨텍스트가 포함되며 사이드카는 백오프를 사용하여 재시도합니다. 다른 두 줄은 사이드카의 보안 비밀 감시 상태를 보고하고 액세스가 반환되면 MCP_MTLS_SECRET_READER_RECOVERED가 로깅됩니다. MCP 역할이 여전히 secrets에 대한 get, list, watch를 부여하는지(트러스트 경계 참조)와 네임스페이스의 다른 구성요소가 API 서버에 도달할 수 있는지 확인합니다. 역할 이름은 생성된 서픽스로 끝나므로 kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server로 찾습니다.
    MCP_MTLS_PUBLISH_FAILED 인증서가 유효하지만 MCP 포드의 메모리 내 볼륨에 쓸 수 없습니다. 사이드카는 백오프를 사용하여 다시 시도하고 쓰기가 성공하면 MCP_MTLS_PUBLISH_RECOVERED를 로깅합니다. 이는 정상적인 작동에서는 예상되지 않습니다. 반복되면 사이드카 로그를 수집하고 Google Cloud Customer Care에 문의하세요.
    MCP_MTLS_UNKEYABLE_ENV_GROUP 환경 그룹에 mcpMtls가 구성되어 있지만 envGroupId 라벨 값이 유효한 경로 요소가 아니므로 MCP 데이터 영역이 단방향 TLS를 통해 그룹을 제공하고 MUTUAL 모드의 인그레스 게이트웨이가 도구 호출을 거부합니다. Kubernetes 라벨 규칙은 일반적으로 이러한 값을 방지하므로 이 상태의 그룹은 클러스터에 직접 적용된 라우팅 리소스에서 가져온 것입니다. ApigeeIssue에서 신고하지 않습니다. 라우팅 리소스에 유효한 라벨(kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels)이 있는지 확인합니다. 리소스가 차트에서 다시 생성되도록 환경 그룹에 대해 apigee-virtualhost 업그레이드를 다시 실행합니다.
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION 환경 그룹은 disableChainValidation: true 및 disableSanValidation: false를 함께 설정합니다. SAN 일치는 체인 검증이 설정하는 검증 내에서 발생하므로 체인 검증이 사용 중지되면 일치시킬 항목이 없으며 설정이 무시됩니다. 차트에서 이 페어링을 거부하므로 이 상태의 그룹은 클러스터에 직접 적용된 커스텀 리소스에서 가져온 것입니다. 환경 그룹의 mcpMtls 블록에서 disableSanValidation를 삭제하거나 disableChainValidation를 다시 false로 설정하고 트러스트 CA를 제공합니다(disableSanValidation 참조).
    MCP_MTLS_CONFLICTING_CONFIG 동일한 환경 그룹의 두 라우팅 리소스는 서로 다른 mcpMtls 블록을 전달하므로 MCP 데이터 영역에서 사용하는 리소스는 경로가 처리되는 순서에 따라 달라집니다. 그룹은 구성한 것과 다른 클라이언트 인증서를 표시할 수 있으며 다운스트림은 어떤 블록이 이겼는지 기록하지 않습니다. 환경 그룹에 대해 apigee-virtualhost 업그레이드를 다시 실행한 후 1단계의 get apigeeroutes 명령어로 블록이 일치하는지 확인합니다. 그룹의 모든 경로는 해당 그룹의 단일 virtualhosts[] 항목에서 파생되므로 불일치는 리소스가 클러스터에 직접 적용되었거나 이전 업그레이드가 부분적으로만 전파되었음을 의미합니다.
    환경 그룹을 단방향 TLS로 전환하는 MCP_MTLS_UNKEYABLE_ENV_GROUP를 제외하고 환경 그룹은 사이드카가 마지막으로 성공적으로 로드한 인증서를 계속 사용합니다. 로드된 적이 없는 경우(첫 번째 사용 설정) 문제가 해결될 때까지 해당 환경 그룹에 대한 MCP 도구 호출이 실패합니다. 다른 환경 그룹은 영향을 받지 않습니다. 수정 후 포드를 다시 시작할 필요가 없습니다.

    나머지 MCP_MTLS_ 코드에는 별도의 조치가 필요하지 않습니다. MCP_MTLS_CHAIN_VALIDATION_DISABLED 및 MCP_MTLS_SAN_VALIDATION_DISABLED는 환경 그룹이 검증을 사용 중지했음을 기록하므로 Fleet 전체에서 선택 항목을 찾을 수 있습니다. MCP_MTLS_MATERIAL_REMOVED은 그룹이 선택 해제한 후의 정기적인 정리 작업이고, MCP_MTLS_COLLECTION_FAILED은 정리가 완료되지 않았으며 그룹의 인증서 파일이 아직 포드에 있음을 의미합니다. 다음 새로고침에서 정리를 다시 시도합니다.

  4. 클러스터에서 문제가 보고되지 않고 사이드카 로그가 깨끗하지만 환경 그룹에 대한 도구 호출이 여전히 실패하는 경우 한쪽에서 핸드셰이크가 거부되는 것입니다.
    • 인그레스 게이트웨이는 발급기관이 해당 환경 그룹(virtualhosts[].caCertPath 또는 INGRESS_SECRET_NAME-cacert)에 대해 인그레스 게이트웨이가 신뢰하는 CA에 없는 경우 클라이언트 인증서를 거부합니다. openssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE로 확인합니다.
    • MCP 데이터 영역은 mcpMtls.caCertPath 또는 MCP_CLIENT_SECRET_NAME-cacert의 CA에 연결되지 않거나 주체 대체 이름에 환경 그룹의 호스트 별칭이 포함되지 않은 경우 인그레스 게이트웨이의 인증서를 거부합니다. openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE로 확인하고 openssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName로 SAN을 검사합니다. 호스트 별칭을 포함하도록 인그레스 게이트웨이의 인증서를 재발급하는 것이 좋습니다. 불가능한 경우에만 해당 환경 그룹에 대해 mcpMtls.disableSanValidation: true를 설정합니다. 그러면 MCP 데이터 영역이 인그레스 게이트웨이 인증서의 이름을 확인하지 않습니다.

지원 케이스

Apigee Hybrid MCP 데이터 영역과 관련된 지원 케이스를 여는 경우 다음 출력을 첨부하여 진단을 가속화하세요.

  • kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server --all-containers --tail=1000
  • kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-server
  • kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wide 및 kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server
  • 최근 overrides.yaml 및 helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE 출력(여기서 APIGEE_ORG_RELEASE_NAME은 apigee-org 차트의 Helm 출시 버전 이름이며 helm list -n APIGEE_NAMESPACE | grep apigee-org로 찾을 수 있음). overrides.yaml를 공유하기 전에 다음을 포함한 보안 비밀 자료를 수정합니다.
    • gcp.workloadIdentity, envs[].serviceAccountPaths 또는 mcpServer.serviceAccountPath 아래의 모든 인라인 서비스 계정 키
    • virtualhosts 아래의 TLS 인증서 또는 비공개 키
    • cassandra.auth 비밀번호 입력란
    • 재정의가 연산자에 전달하는 모든 인라인 사용자 인증 정보입니다.
  • 문제를 재현하는 전체 curl 명령어 및 응답

API 허브에서 API 스타일을 MCP로 변경할 수 없음

기존 API 작업이 있는 API 리소스가 Apigee API 허브에 이미 있는 경우 해당 리소스의 API 스타일 속성을 MCP로 변경할 수 없습니다. Apigee API 허브에 API를 MCP API로 등록하려면 API를 처음 등록할 때 MCP 스타일을 선택하거나 스타일을 MCP로 변경하기 전에 API 리소스에 작업이 없는지 확인해야 합니다.

다른 문제가 발생하면 디버그 사용을 참고하여 Google Cloud 콘솔에서 디버그 도구를 사용하여 MCP 검색 프록시와의 요청 및 응답을 분석하는 방법에 관한 자세한 내용을 확인하세요.