Amazon EKS上のAgentCore MCPリバースコネクタ

このプロジェクトは、Amazon EKS上で最小限のMCP互換Pythonツールサーバーをデプロイします。ポッドは AGENTCORE_GATEWAY_ENDPOINT へのアウトバウンドセキュアWebSocket接続を開き、 AGENTCORE_AUTH_TOKEN で認証を行います。

このコネクタは、ツール検出と呼び出しに必要なMCP JSON-RPCメソッドを実装しています：

• initialize

• tools/list

• tools/call

• ping

以下の2つのツールを公開します：

• get_system_info

• echo_data

アーキテクチャに関する注意点

Amazon Bedrock AgentCore Gatewayのドキュメントでは、Gatewayをエージェント用のMCPエンドポイントとして、またLambda、OpenAPI、Smithy、リモートMCPサーバーエンドポイントなどの構成済みターゲットを呼び出せるサービスとして説明しています。リバースダイヤルアウトWebSocketコネクタを使用するには、AgentCore Gatewayエンドポイント、リレー、またはフロントサービスが永続的なアウトバウンド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

前提条件

• TCP 443経由でAgentCore Gatewayエンドポイントへのエグレス（外部送信）が可能なワーカーノードを持つ、既存のAmazon EKSクラスター。

• ターゲットのAWSアカウント用に構成された aws CLI。

• EKSクラスター用に構成された kubectl。

• Dockerまたはその他のOCI互換イメージビルドツール。

• EKSをまだ作成していない場合は、Terraformまたは推奨のIaCワークフロー。

• コンテナレジストリ（例：Amazon ECRまたはGitHub Container Registry）。

• HPA（Horizontal Pod Autoscaler）で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 のDeploymentイメージを更新するか、Kustomizeを使用します：

kubectl kustomize k8s/base

Kubernetesの構成

Secretを安全に作成できるように、まず名前空間を作成します：

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 を返す。

• ゲートウェイへのWebSocket接続が確立された後にのみ /readyz が 200 を返す。

ゲートウェイ接続のトラブルシューティング

トークンを表示せずにポッドの環境変数の配線を確認します：

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 でDeploymentを再起動してください。

• Readinessが正常にならない: ゲートウェイがリバースWebSocketコネクタコントラクトをサポートしており、ソケット経由でMCP JSON-RPCメッセージを受け入れていることを確認してください。

• NetworkPolicyがトラフィックをブロックしている: まず networkpolicy.yaml なしでDeploymentを適用して接続を確認し、その後再適用して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を使用してください。

• コンテナは、読み取り専用のルートファイルシステムと制限されたLinuxケーパビリティを持つ非rootユーザーとして実行されます。

• デフォルトのサービスは ClusterIP です。サーバーが外部へダイヤルアウトするため、パブリックなインバウンドエンドポイントはありません。

• サンプルのNetworkPolicyはDNSとアウトバウンドHTTPSを許可しています。厳格なFQDNエグレス制御が必要な場合は、CiliumやCalico Enterpriseなど、FQDNポリシーをサポートするCNIを使用し、AgentCore Gatewayの正確なホスト名へのアクセスのみに制限してください。

• ツール入力スキーマは完全にインライン化されており、JSON Schemaの $ref や $defs は使用していません。

参考文献

• Amazon Bedrock AgentCore Gatewayの概要

• AgentCore Gateway MCPの使用方法

• AgentCore Gateway MCPサーバーターゲット

• MCP Python SDKパッケージ