Conector Inverso MCP de AgentCore en Amazon EKS

Este proyecto despliega un servidor de herramientas de Python compatible con MCP mínimo en Amazon EKS. El pod abre una conexión WebSocket segura saliente hacia AGENTCORE_GATEWAY_ENDPOINT y se autentica con AGENTCORE_AUTH_TOKEN.

El conector implementa los métodos JSON-RPC de MCP necesarios para el descubrimiento e invocación de herramientas:

• initialize

• tools/list

• tools/call

• ping

Expone dos herramientas:

• get_system_info

• echo_data

Nota sobre la arquitectura

La documentación de Amazon Bedrock AgentCore Gateway describe el Gateway como un endpoint MCP para agentes y como un servicio que puede invocar destinos configurados como Lambda, OpenAPI, Smithy y endpoints de servidores MCP remotos. Un conector WebSocket de marcado saliente inverso requiere que su endpoint de AgentCore Gateway, relay o servicio de front-end soporte un contrato de WebSocket saliente persistente.

Esta implementación asume que dicho contrato existe y que el gateway envía mensajes de solicitud JSON-RPC de MCP a través del WebSocket. Si su Gateway está configurado para un destino de servidor MCP estándar, exponga este servidor a través de un endpoint HTTP/SSE de MCP normal o colóquelo detrás de un balanceador de carga interno/externo y registre ese endpoint con AgentCore.

Árbol del proyecto

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

Requisitos previos

• Un clúster de Amazon EKS existente con nodos de trabajo que puedan tener salida hacia el endpoint de AgentCore Gateway a través de TCP 443.

• CLI de aws configurada para la cuenta de AWS de destino.

• kubectl configurado para el clúster de EKS.

• Docker u otro constructor de imágenes compatible con OCI.

• Terraform o su flujo de trabajo de IaC preferido si aún necesita crear EKS.

• Un registro de contenedores, por ejemplo, Amazon ECR o GitHub Container Registry.

• Kubernetes Metrics Server si desea que el HPA escale según las métricas de CPU.

• Valores conocidos para:

  • AGENTCORE_GATEWAY_ENDPOINT

  • AGENTCORE_AUTH_TOKEN

Construcción y publicación

Establezca el nombre de su imagen:

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

Construya y envíe:

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

Actualice la imagen de Deployment en k8s/base/deployment.yaml o utilice Kustomize:

kubectl kustomize k8s/base

Configuración de Kubernetes

Cree el espacio de nombres primero para que el Secret pueda crearse de forma segura:

kubectl apply -f k8s/base/namespace.yaml

Cree el secreto del token de autenticación sin almacenar un token real en Git:

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

Establezca el endpoint del gateway editando k8s/base/configmap.yaml:

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

Si desea utilizar el manifiesto de Secret de ejemplo, copie k8s/examples/secret.example.yaml, reemplace el marcador de posición y aplíquelo desde una ubicación privada segura.

Despliegue

Aplique los manifiestos:

kubectl apply -k k8s/base

Compruebe el despliegue:

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

Siga los registros:

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

Comprobaciones operativas

Realice un reenvío de puertos del servicio interno para comprobaciones de estado:

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

Comportamiento esperado:

• /healthz devuelve 200 cuando el proceso está en ejecución.

• /readyz devuelve 200 solo después de que se establezca la conexión WebSocket con el gateway.

Solución de problemas de conectividad del Gateway

Compruebe la configuración del entorno del pod sin imprimir el token:

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

Busque mensajes de registro del conector:

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

Problemas comunes:

• AGENTCORE_GATEWAY_ENDPOINT is required: falta el ConfigMap o la clave está mal escrita.

• AGENTCORE_AUTH_TOKEN is required: falta el Secret o la clave está mal escrita.

• Fallos de conexión repetidos: verifique que el endpoint comience con wss://, que el DNS se resuelva desde dentro del clúster y que los grupos de seguridad/NACL de los nodos permitan la salida hacia TCP 443.

• Fallos de autenticación: rote el Secret y reinicie el Deployment con kubectl -n mcp-system rollout restart deployment/agentcore-mcp-server.

• La preparación nunca se vuelve saludable: confirme que el gateway soporta el contrato del conector WebSocket inverso y acepta mensajes JSON-RPC de MCP a través del socket.

• NetworkPolicy bloquea el tráfico: comience aplicando el Deployment sin networkpolicy.yaml, confirme la conectividad, luego vuelva a aplicar y restrinja la salida para su CNI.

Ejecute una prueba de DNS/conectividad dentro del clúster:

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

Luego, dentro del shell:

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

Notas de seguridad

• No confirme tokens reales. Utilice Kubernetes Secrets, External Secrets Operator, AWS Secrets Manager o Sealed Secrets.

• El contenedor se ejecuta como un usuario no root con un sistema de archivos raíz de solo lectura y capacidades de Linux restringidas.

• El servicio predeterminado es ClusterIP; no hay un endpoint de entrada público porque el servidor realiza llamadas salientes.

• La NetworkPolicy de ejemplo permite DNS y HTTPS saliente. Para controles de salida FQDN estrictos, utilice un CNI que soporte políticas FQDN como Cilium o Calico Enterprise y restrinja el acceso al nombre de host exacto de AgentCore Gateway.

• Los esquemas de entrada de herramientas están completamente integrados y no utilizan $ref o $defs de JSON Schema.

Referencias

• Descripción general de Amazon Bedrock AgentCore Gateway

• Uso de MCP en AgentCore Gateway

• Destinos de servidor MCP de AgentCore Gateway

• Paquete SDK de Python para MCP