Amazon EKS용 AgentCore MCP 리버스 커넥터

이 프로젝트는 Amazon EKS에서 최소한의 MCP 호환 Python 도구 서버를 배포합니다. 파드(Pod)는 AGENTCORE_GATEWAY_ENDPOINT로 아웃바운드 보안 WebSocket 연결을 열고 AGENTCORE_AUTH_TOKEN으로 인증합니다.

이 커넥터는 도구 검색 및 호출에 필요한 MCP JSON-RPC 메서드를 구현합니다:

• initialize

• tools/list

• tools/call

• ping

다음 두 가지 도구를 노출합니다:

• get_system_info

• echo_data

아키텍처 참고 사항

Amazon Bedrock AgentCore 게이트웨이 설명서에서는 게이트웨이를 에이전트를 위한 MCP 엔드포인트이자 Lambda, OpenAPI, Smithy 및 원격 MCP 서버 엔드포인트와 같은 구성된 대상을 호출할 수 있는 서비스로 설명합니다. 리버스 다이얼아웃 WebSocket 커넥터를 사용하려면 AgentCore 게이트웨이 엔드포인트, 릴레이 또는 프런트 서비스가 지속적인 아웃바운드 WebSocket 계약을 지원해야 합니다.

이 구현은 해당 계약이 존재하며 게이트웨이가 WebSocket을 통해 MCP JSON-RPC 요청 메시지를 보낸다고 가정합니다. 게이트웨이가 표준 MCP 서버 대상으로 구성된 경우, 이 서버를 일반 MCP HTTP/SSE 엔드포인트를 통해 노출하거나 내부/외부 로드 밸런서 뒤에 배치하고 해당 엔드포인트를 AgentCore에 등록하십시오.

프로젝트 트리

agentcore-mcp-eks/
├── .dockerignore
├── .gitignore
├── Dockerfile
├── Makefile
├── README.md
├── k8s/
│   ├── base/
│   │   ├── configmap.yaml
│   │   ├── deployment.yaml
│   │   ├── hpa.yaml
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── networkpolicy.yaml
│   │   ├── pdb.yaml
│   │   ├── service.yaml
│   │   └── serviceaccount.yaml
│   └── examples/
│       └── secret.example.yaml
├── requirements.txt
└── src/
    ├── pyproject.toml
    └── agentcore_mcp_server/
        ├── __init__.py
        ├── __main__.py
        ├── config.py
        ├── connector.py
        ├── health.py
        ├── protocol.py
        └── tools.py

사전 요구 사항

• TCP 443을 통해 AgentCore 게이트웨이 엔드포인트로 송신(egress)할 수 있는 워커 노드가 있는 기존 Amazon EKS 클러스터.

• 대상 AWS 계정에 대해 구성된 aws CLI.

• EKS 클러스터에 대해 구성된 kubectl.

• Docker 또는 기타 OCI 호환 이미지 빌더.

• EKS를 생성해야 하는 경우 Terraform 또는 선호하는 IaC 워크플로우.

• 컨테이너 레지스트리(예: Amazon ECR 또는 GitHub Container Registry).

• HPA가 CPU 메트릭을 기반으로 확장되기를 원하는 경우 Kubernetes 메트릭 서버.

• 다음 항목에 대한 알려진 값:

  • AGENTCORE_GATEWAY_ENDPOINT

  • AGENTCORE_AUTH_TOKEN

빌드 및 게시

이미지 이름을 설정합니다:

cd agentcore-mcp-eks
export IMAGE="123456789012.dkr.ecr.us-east-1.amazonaws.com/agentcore-mcp-server"
export TAG="0.1.0"

빌드 및 푸시:

docker build -t "${IMAGE}:${TAG}" .
docker push "${IMAGE}:${TAG}"

k8s/base/deployment.yaml에서 배포 이미지를 업데이트하거나 Kustomize를 사용합니다:

kubectl kustomize k8s/base

Kubernetes 구성

비밀(Secret)을 안전하게 생성할 수 있도록 먼저 네임스페이스를 생성합니다:

kubectl apply -f k8s/base/namespace.yaml

Git에 실제 토큰을 저장하지 않고 인증 토큰 비밀을 생성합니다:

kubectl -n mcp-system create secret generic agentcore-mcp-secret \
  --from-literal=AGENTCORE_AUTH_TOKEN='replace-with-real-token'

k8s/base/configmap.yaml을 편집하여 게이트웨이 엔드포인트를 설정합니다:

data:
  AGENTCORE_GATEWAY_ENDPOINT: "wss://gateway.example.com/mcp/reverse"
  MCP_SERVER_NAME: "eks-agentcore-mcp"

예제 비밀 매니페스트를 대신 사용하려면 k8s/examples/secret.example.yaml을 복사하고 자리 표시자를 바꾼 다음 안전한 개인 위치에서 적용하십시오.

배포

매니페스트를 적용합니다:

kubectl apply -k k8s/base

롤아웃을 확인합니다:

kubectl -n mcp-system rollout status deployment/agentcore-mcp-server
kubectl -n mcp-system get pods -l app.kubernetes.io/name=agentcore-mcp-server

로그를 확인합니다:

kubectl -n mcp-system logs deployment/agentcore-mcp-server -f

운영 확인

상태 확인을 위해 내부 서비스를 포트 포워딩합니다:

kubectl -n mcp-system port-forward svc/agentcore-mcp-server 8080:8080
curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/readyz

예상 동작:

• 프로세스가 실행 중일 때 /healthz는 200을 반환합니다.

• /readyz는 게이트웨이에 대한 WebSocket 연결이 설정된 후에만 200을 반환합니다.

게이트웨이 연결 문제 해결

토큰을 출력하지 않고 파드 환경 구성을 확인합니다:

kubectl -n mcp-system describe pod -l app.kubernetes.io/name=agentcore-mcp-server

커넥터 로그 메시지를 확인합니다:

kubectl -n mcp-system logs deployment/agentcore-mcp-server --tail=200

일반적인 문제:

• AGENTCORE_GATEWAY_ENDPOINT is required: ConfigMap이 없거나 키 철자가 틀렸습니다.

• AGENTCORE_AUTH_TOKEN is required: Secret이 없거나 키 철자가 틀렸습니다.

• 반복적인 연결 실패: 엔드포인트가 wss://로 시작하는지, 클러스터 내부에서 DNS가 확인되는지, 노드 보안 그룹/NACL이 TCP 443으로의 송신을 허용하는지 확인하십시오.

• 인증 실패: Secret을 교체하고 kubectl -n mcp-system rollout restart deployment/agentcore-mcp-server를 사용하여 배포를 다시 시작하십시오.

• 준비 상태가 정상으로 전환되지 않음: 게이트웨이가 리버스 WebSocket 커넥터 계약을 지원하고 소켓을 통해 MCP JSON-RPC 메시지를 수락하는지 확인하십시오.

• NetworkPolicy가 트래픽을 차단함: networkpolicy.yaml 없이 배포를 적용하여 연결을 확인한 다음, 다시 적용하고 CNI에 대한 송신을 강화하십시오.

클러스터 내 DNS/연결 테스트를 실행합니다:

kubectl -n mcp-system run netcheck --rm -it --restart=Never \
  --image=curlimages/curl:8.10.1 -- sh

그런 다음 셸 내부에서:

nslookup gateway.example.com
curl -vk https://gateway.example.com/

보안 참고 사항

• 실제 토큰을 커밋하지 마십시오. Kubernetes Secrets, External Secrets Operator, AWS Secrets Manager 또는 Sealed Secrets를 사용하십시오.

• 컨테이너는 읽기 전용 루트 파일 시스템과 삭제된 Linux 기능을 가진 비루트(non-root) 사용자로 실행됩니다.

• 기본 서비스는 ClusterIP입니다. 서버가 외부로 다이얼을 걸기 때문에 공용 인바운드 엔드포인트가 없습니다.

• 예제 NetworkPolicy는 DNS 및 아웃바운드 HTTPS를 허용합니다. 엄격한 FQDN 송신 제어를 위해서는 Cilium 또는 Calico Enterprise와 같이 FQDN 정책을 지원하는 CNI를 사용하고 정확한 AgentCore 게이트웨이 호스트 이름으로 액세스를 제한하십시오.

• 도구 입력 스키마는 완전히 인라인 처리되며 JSON Schema $ref 또는 $defs를 사용하지 않습니다.

참조

• Amazon Bedrock AgentCore 게이트웨이 개요

• AgentCore 게이트웨이 MCP 사용

• AgentCore 게이트웨이 MCP 서버 대상

• MCP Python SDK 패키지