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

先决条件

• 现有的 Amazon EKS 集群，其工作节点可以通过 TCP 443 端口访问 AgentCore 网关端点。

• 为目标 AWS 账户配置的 aws CLI。

• 为 EKS 集群配置的 kubectl。

• Docker 或其他兼容 OCI 的镜像构建器。

• 如果您仍需创建 EKS，请使用 Terraform 或您首选的 IaC 工作流。

• 容器镜像仓库，例如 Amazon ECR 或 GitHub Container Registry。

• 如果您希望 HPA 根据 CPU 指标进行扩展，则需要 Kubernetes Metrics Server。

• 以下已知值：

  • 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

创建身份验证令牌 Secret，而不将真实令牌存储在 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。

• 仅在与网关的 WebSocket 连接建立后，/readyz 才返回 200。

网关连接故障排除

检查 Pod 环境变量配置（不打印令牌）：

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

然后在 shell 中：

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 出站控制，请使用支持 FQDN 策略的 CNI（如 Cilium 或 Calico Enterprise），并将访问权限限制为确切的 AgentCore 网关主机名。

• 工具输入模式已完全内联，不使用 JSON Schema $ref 或 $defs。

参考资料

• Amazon Bedrock AgentCore 网关概述

• AgentCore 网关 MCP 使用方法

• AgentCore 网关 MCP 服务器目标

• MCP Python SDK 包