AgentCore MCP Reverse Connector on Amazon EKS

This project deploys a minimal MCP-compatible Python tool server on Amazon EKS. The pod opens an outbound secure WebSocket connection to AGENTCORE_GATEWAY_ENDPOINT and authenticates with AGENTCORE_AUTH_TOKEN.

The connector implements the MCP JSON-RPC methods required for tool discovery and invocation:

initialize
tools/list
tools/call
ping

It exposes two tools:

get_system_info
echo_data

Architecture Note

Amazon Bedrock AgentCore Gateway documentation describes Gateway as an MCP endpoint for agents and as a service that can invoke configured targets such as Lambda, OpenAPI, Smithy, and remote MCP server endpoints. A reverse dial-out WebSocket connector requires your AgentCore Gateway endpoint, relay, or fronting service to support a persistent outbound WebSocket contract.

This implementation assumes that contract exists and that the gateway sends MCP JSON-RPC request messages over the WebSocket. If your Gateway is configured for a standard MCP server target instead, expose this server through a normal MCP HTTP/SSE endpoint or put it behind an internal/external load balancer and register that endpoint with AgentCore.

Project Tree

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

Prerequisites

An existing Amazon EKS cluster with worker nodes that can egress to the AgentCore Gateway endpoint over TCP 443.
aws CLI configured for the target AWS account.
kubectl configured for the EKS cluster.
Docker or another OCI-compatible image builder.
Terraform or your preferred IaC workflow if you still need to create EKS.
A container registry, for example Amazon ECR or GitHub Container Registry.
Kubernetes Metrics Server if you want the HPA to scale on CPU metrics.
Known values for:
- AGENTCORE_GATEWAY_ENDPOINT
- AGENTCORE_AUTH_TOKEN

Build and Publish

Set your image name:

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

Build and push:

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

Update the Deployment image in k8s/base/deployment.yaml or use Kustomize:

kubectl kustomize k8s/base

Configure Kubernetes

Create the namespace first so the Secret can be created safely:

kubectl apply -f k8s/base/namespace.yaml

Create the auth token secret without storing a real token in Git:

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

Set the gateway endpoint by editing k8s/base/configmap.yaml:

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

If you want to use the example Secret manifest instead, copy k8s/examples/secret.example.yaml, replace the placeholder, and apply it from a secure private location.

Deploy

Apply the manifests:

kubectl apply -k k8s/base

Check 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

Tail logs:

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

Operational Checks

Port-forward the internal service for health checks:

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

Expected behavior:

/healthz returns 200 when the process is running.
/readyz returns 200 only after the WebSocket connection to the gateway is established.

Troubleshooting Gateway Connectivity

Check pod environment wiring without printing the token:

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

Look for connector log messages:

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

Common issues:

AGENTCORE_GATEWAY_ENDPOINT is required: the ConfigMap is missing or the key is misspelled.
AGENTCORE_AUTH_TOKEN is required: the Secret is missing or the key is misspelled.
Repeated connect failures: verify the endpoint starts with wss://, DNS resolves from inside the cluster, and node security groups/NACLs permit egress to TCP 443.
Authentication failures: rotate the Secret and restart the Deployment with kubectl -n mcp-system rollout restart deployment/agentcore-mcp-server.
Readiness never becomes healthy: confirm the gateway supports the reverse WebSocket connector contract and accepts MCP JSON-RPC messages over the socket.
NetworkPolicy blocks traffic: start by applying the Deployment without networkpolicy.yaml, confirm connectivity, then reapply and tighten egress for your CNI.

Run an in-cluster DNS/connectivity test:

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

Then inside the shell:

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

Security Notes

Do not commit real tokens. Use Kubernetes Secrets, External Secrets Operator, AWS Secrets Manager, or Sealed Secrets.
The container runs as a non-root user with a read-only root filesystem and dropped Linux capabilities.
The default Service is ClusterIP; there is no public inbound endpoint because the server dials out.
The example NetworkPolicy allows DNS and outbound HTTPS. For strict FQDN egress controls, use a CNI that supports FQDN policies such as Cilium or Calico Enterprise and restrict access to the exact AgentCore Gateway hostname.
Tool input schemas are fully inlined and do not use JSON Schema $ref or $defs.

AgentCore MCP Reverse Connector