AgentCore MCP Reverse Connector в Amazon EKS

Этот проект развертывает минимальный Python-сервер инструментов, совместимый с MCP, в Amazon EKS. Под открывает исходящее защищенное WebSocket-соединение с AGENTCORE_GATEWAY_ENDPOINT и проходит аутентификацию с помощью AGENTCORE_AUTH_TOKEN.

Коннектор реализует методы MCP JSON-RPC, необходимые для обнаружения и вызова инструментов:

• initialize

• tools/list

• tools/call

• ping

Он предоставляет два инструмента:

• get_system_info

• echo_data

Замечание по архитектуре

Документация Amazon Bedrock AgentCore Gateway описывает Gateway как MCP-эндпоинт для агентов и как сервис, который может вызывать настроенные цели, такие как Lambda, OpenAPI, Smithy и удаленные эндпоинты MCP-серверов. Коннектор с обратным вызовом через WebSocket требует, чтобы ваш эндпоинт AgentCore Gateway, ретранслятор или фронтенд-сервис поддерживали постоянное исходящее WebSocket-соединение.

Данная реализация предполагает, что такой контракт существует и что шлюз отправляет запросы MCP JSON-RPC через WebSocket. Если ваш шлюз настроен на стандартную цель 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

Предварительные требования

• Существующий кластер Amazon EKS с рабочими узлами, имеющими доступ к эндпоинту AgentCore Gateway по протоколу TCP 443.

• aws CLI, настроенный для целевой учетной записи AWS.

• kubectl, настроенный для кластера EKS.

• Docker или другой OCI-совместимый сборщик образов.

• Terraform или ваш предпочтительный рабочий процесс IaC, если вам еще нужно создать EKS.

• Реестр контейнеров, например Amazon ECR или GitHub Container Registry.

• Kubernetes Metrics Server, если вы хотите, чтобы HPA масштабировался на основе метрик CPU.

• Известные значения для:

  • 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}"

Обновите образ Deployment в k8s/base/deployment.yaml или используйте Kustomize:

kubectl kustomize k8s/base

Настройка Kubernetes

Сначала создайте пространство имен, чтобы секрет можно было создать безопасно:

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"

Если вы хотите использовать пример манифеста Secret, скопируйте 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 возвращает 200 только после того, как установлено WebSocket-соединение со шлюзом.

Устранение неполадок подключения к шлюзу

Проверьте настройки окружения пода, не выводя токен:

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 и перезапустите Deployment с помощью kubectl -n mcp-system rollout restart deployment/agentcore-mcp-server.

• Состояние готовности не становится успешным: подтвердите, что шлюз поддерживает контракт обратного WebSocket-коннектора и принимает сообщения MCP JSON-RPC через сокет.

• NetworkPolicy блокирует трафик: начните с применения Deployment без 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.

• Контейнер работает от имени пользователя без прав root с файловой системой в режиме только для чтения и ограниченными возможностями Linux.

• Сервис по умолчанию — ClusterIP; публичного входящего эндпоинта нет, так как сервер сам инициирует исходящее соединение.

• Пример NetworkPolicy разрешает DNS и исходящий HTTPS. Для строгого контроля исходящего трафика по FQDN используйте CNI, поддерживающий политики FQDN, такие как Cilium или Calico Enterprise, и ограничьте доступ точным именем хоста AgentCore Gateway.

• Схемы ввода инструментов полностью встроены и не используют JSON Schema $ref или $defs.

Ссылки

• Обзор Amazon Bedrock AgentCore Gateway

• Использование MCP в AgentCore Gateway

• Цели MCP-серверов в AgentCore Gateway

• Пакет MCP Python SDK