AgentCore MCP Reverse Connector auf Amazon EKS

Dieses Projekt stellt einen minimalen MCP-kompatiblen Python-Tool-Server auf Amazon EKS bereit. Der Pod öffnet eine ausgehende, sichere WebSocket-Verbindung zu AGENTCORE_GATEWAY_ENDPOINT und authentifiziert sich mit AGENTCORE_AUTH_TOKEN.

Der Connector implementiert die für die Tool-Erkennung und den Aufruf erforderlichen MCP JSON-RPC-Methoden:

• initialize

• tools/list

• tools/call

• ping

Er stellt zwei Tools bereit:

• get_system_info

• echo_data

Architekturhinweis

Die Dokumentation zu Amazon Bedrock AgentCore Gateway beschreibt das Gateway als MCP-Endpunkt für Agenten und als Dienst, der konfigurierte Ziele wie Lambda, OpenAPI, Smithy und Remote-MCP-Server-Endpunkte aufrufen kann. Ein Reverse-Dial-out-WebSocket-Connector erfordert, dass Ihr AgentCore Gateway-Endpunkt, Relay oder Fronting-Dienst einen persistenten ausgehenden WebSocket-Vertrag unterstützt.

Diese Implementierung setzt voraus, dass dieser Vertrag existiert und dass das Gateway MCP JSON-RPC-Anforderungsnachrichten über den WebSocket sendet. Wenn Ihr Gateway stattdessen für ein Standard-MCP-Server-Ziel konfiguriert ist, stellen Sie diesen Server über einen normalen MCP-HTTP/SSE-Endpunkt bereit oder platzieren Sie ihn hinter einem internen/externen Load Balancer und registrieren Sie diesen Endpunkt bei AgentCore.

Projektstruktur

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

Voraussetzungen

• Ein bestehender Amazon EKS-Cluster mit Worker-Nodes, die ausgehenden Datenverkehr zum AgentCore Gateway-Endpunkt über TCP 443 zulassen.

• aws CLI, konfiguriert für das Ziel-AWS-Konto.

• kubectl, konfiguriert für den EKS-Cluster.

• Docker oder ein anderer OCI-kompatibler Image-Builder.

• Terraform oder Ihr bevorzugter IaC-Workflow, falls Sie EKS noch erstellen müssen.

• Eine Container-Registry, zum Beispiel Amazon ECR oder GitHub Container Registry.

• Kubernetes Metrics Server, falls Sie den HPA basierend auf CPU-Metriken skalieren möchten.

• Bekannte Werte für:

  • AGENTCORE_GATEWAY_ENDPOINT

  • AGENTCORE_AUTH_TOKEN

Erstellen und Veröffentlichen

Legen Sie Ihren Image-Namen fest:

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

Erstellen und pushen:

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

Aktualisieren Sie das Deployment-Image in k8s/base/deployment.yaml oder verwenden Sie Kustomize:

kubectl kustomize k8s/base

Kubernetes konfigurieren

Erstellen Sie zuerst den Namespace, damit das Secret sicher erstellt werden kann:

kubectl apply -f k8s/base/namespace.yaml

Erstellen Sie das Auth-Token-Secret, ohne ein echtes Token in Git zu speichern:

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

Legen Sie den Gateway-Endpunkt fest, indem Sie k8s/base/configmap.yaml bearbeiten:

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

Wenn Sie stattdessen das Beispiel-Secret-Manifest verwenden möchten, kopieren Sie k8s/examples/secret.example.yaml, ersetzen Sie den Platzhalter und wenden Sie es von einem sicheren privaten Speicherort aus an.

Bereitstellung

Wenden Sie die Manifeste an:

kubectl apply -k k8s/base

Überprüfen Sie den Rollout:

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

Logs verfolgen:

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

Betriebsprüfungen

Leiten Sie den internen Dienst für Gesundheitsprüfungen weiter (Port-Forwarding):

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

Erwartetes Verhalten:

• /healthz gibt 200 zurück, wenn der Prozess läuft.

• /readyz gibt 200 erst zurück, nachdem die WebSocket-Verbindung zum Gateway hergestellt wurde.

Fehlerbehebung bei der Gateway-Konnektivität

Überprüfen Sie die Pod-Umgebungskonfiguration, ohne das Token auszugeben:

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

Suchen Sie nach Connector-Log-Meldungen:

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

Häufige Probleme:

• AGENTCORE_GATEWAY_ENDPOINT is required: Die ConfigMap fehlt oder der Schlüssel ist falsch geschrieben.

• AGENTCORE_AUTH_TOKEN is required: Das Secret fehlt oder der Schlüssel ist falsch geschrieben.

• Wiederholte Verbindungsfehler: Überprüfen Sie, ob der Endpunkt mit wss:// beginnt, DNS innerhalb des Clusters aufgelöst wird und Node-Security-Groups/NACLs den ausgehenden Datenverkehr zu TCP 443 zulassen.

• Authentifizierungsfehler: Rotieren Sie das Secret und starten Sie das Deployment mit kubectl -n mcp-system rollout restart deployment/agentcore-mcp-server neu.

• Bereitschaft wird nie erreicht: Bestätigen Sie, dass das Gateway den Reverse-WebSocket-Connector-Vertrag unterstützt und MCP JSON-RPC-Nachrichten über den Socket akzeptiert.

• NetworkPolicy blockiert Datenverkehr: Beginnen Sie mit der Anwendung des Deployments ohne networkpolicy.yaml, bestätigen Sie die Konnektivität und wenden Sie sie dann erneut an, um den ausgehenden Datenverkehr für Ihr CNI einzuschränken.

Führen Sie einen DNS-/Konnektivitätstest innerhalb des Clusters durch:

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

Dann innerhalb der Shell:

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

Sicherheitshinweise

• Committen Sie keine echten Token. Verwenden Sie Kubernetes Secrets, External Secrets Operator, AWS Secrets Manager oder Sealed Secrets.

• Der Container läuft als Nicht-Root-Benutzer mit einem schreibgeschützten Root-Dateisystem und eingeschränkten Linux-Capabilities.

• Der Standard-Dienst ist ClusterIP; es gibt keinen öffentlichen eingehenden Endpunkt, da der Server nach außen wählt.

• Die Beispiel-NetworkPolicy erlaubt DNS und ausgehendes HTTPS. Für strikte FQDN-Egress-Kontrollen verwenden Sie ein CNI, das FQDN-Richtlinien unterstützt, wie Cilium oder Calico Enterprise, und beschränken Sie den Zugriff auf den exakten AgentCore Gateway-Hostnamen.

• Tool-Eingabeschemata sind vollständig inline und verwenden kein JSON Schema $ref oder $defs.

Referenzen

• Amazon Bedrock AgentCore Gateway Übersicht

• AgentCore Gateway MCP-Nutzung

• AgentCore Gateway MCP-Server-Ziele

• MCP Python SDK Paket