AgentCore Gateway から MCP サーバーへの接続

connection ジェネレーターは、MCP サーバー（TypeScript または Python）を AgentCore Gateway のターゲットとして登録できます。

接続されると、Gateway は MCP サーバーのツールを単一の MCP エンドポイントに集約し、Cedar ポリシーエンジンに対して呼び出しを評価し、IAM SigV4 を使用して MCP サーバーへのアウトバウンドトラフィックに署名します。

前提条件

このジェネレーターを使用する前に、以下を確認してください：

1. agentcore-gateway プロジェクト
2. infra: agentcore および auth: iam で作成された MCP サーバーコンポーネント（ts#mcp-server または py#mcp-server）

Gateway は protocol: mcp を持ち、MCP サーバーは auth: iam を持つ必要があります — ジェネレーターは両方を検証します。Gateway は SigV4 でアウトバウンドトラフィックに署名するため、非 IAM の MCP サーバーは接続できません。

使用方法

ジェネレーターの実行

VSCode

1. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - connection
5. 必須パラメータを入力
6. クリック Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Gateway プロジェクトをソースとして、MCP サーバープロジェクトをターゲットとして選択します。MCP サーバープロジェクトに複数のコンポーネントが含まれている場合は、targetComponent を指定して明確にします。

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソース プロジェクト
targetProject 必須	string	-	接続先のターゲット プロジェクト
sourceComponent	string	-	接続元のソース コンポーネント (コンポーネント名、ソース プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲット コンポーネント (コンポーネント名、ターゲット プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、新しいソースファイルを生成するのではなく、既存のプロジェクトを接続します。以下のファイルが変更されます：

• Directorypackages/<gateway>

  • project.json <gateway>-serve-local が MCP サーバーの <mcp>-serve-local への依存関係を取得
  • serve-local.ts ATTACHED_MCP_SERVERS が更新され、ローカル gateway が MCP サーバーを集約

Gateway プロジェクトの dev ターゲットは、MCP サーバーの <mcp>-dev ターゲットへの依存関係を取得するため、Gateway をローカルで実行すると MCP サーバーも起動します。MCP サーバーは Gateway プロジェクトの local-dev.ts にも登録されるため、ローカル gateway がそのツールを集約します。

スタックへの MCP サーバーターゲットの追加

ジェネレーターは、Gateway をインスタンス化するスタックやモジュールを知らないため、MCP サーバーターゲットをインフラストラクチャに自動的に接続できません。gateway.addMcpServer(server) の呼び出しを自分で追加してください。

CDK

Gateway をインスタンス化するスタックで、MCP サーバーをターゲットとして登録します：

packages/infra/src/stacks/application-stack.ts

const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
const myGateway = new MyGateway(this, 'MyGateway');

// MCP サーバーを Gateway のターゲットとして登録します。ターゲット名は
// デフォルトで MCP サーバーコンストラクトの id をケバブケースにしたもの（`my-mcp-server`）になります。
myGateway.addMcpServer(myMcpServer);

Gateway ターゲット名（デフォルトでは MCP サーバーの mcpServerName）は、Cedar アクション名のプレフィックスとして使用されます — アクション形式は AgentCore::Action::"<targetName>___<toolName>" です。ポリシーの記述セクションを参照してください。ターゲット名は短く安定したものにしてください。後で変更すると、古い名前を参照する Cedar ポリシーが無効になります。

デフォルトのターゲット名を上書きするには、gatewayTargetName を渡します：

myGateway.addMcpServer(myMcpServer, { gatewayTargetName: 'my-mcp' });

コンストラクトは iamCredentialProvider.service = 'bedrock-agentcore' でターゲットを構成するため、Gateway は自身の実行ロールを使用してアウトバウンド呼び出しに署名します。

Terraform

Gateway をインスタンス化する Terraform ファイルで、MCP サーバーターゲットを接続します：

packages/infra/src/main.tf

module "my_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
}

module "my_gateway" {
  source              = "../../common/terraform/src/app/gateways/my-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

# MCP サーバーを Gateway のターゲットとして登録
resource "aws_bedrockagentcore_gateway_target" "my_mcp_server" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-mcp-server"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(module.my_mcp_server.agent_core_runtime_arn)}/invocations?qualifier=DEFAULT"
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

ターゲット name（上記の my-mcp-server）は、Cedar アクション名のプレフィックスとして使用されます — ポリシーの記述セクションを参照してください。policy_dependencies は、このターゲットのアクションを参照する Cedar ポリシーが、ターゲットがそれらを登録した後に作成されることを保証します。

ローカル開発

Gateway をローカルで実行するには：

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

これにより、ローカル gateway と、接続されているすべての MCP サーバーが割り当てられたローカルポートで起動します。ローカル gateway は、接続されたサーバーのツールを集約する単一の MCP エンドポイントを公開します。TypeScript または Python gateway-connection ジェネレーターを介して Gateway に接続されたエージェントは、LOCAL_DEV=true で実行する際にそれを参照します。

ローカルの忠実性

ローカル開発では ローカル代替 gateway を使用します — Gateway プロジェクトによって起動される軽量な MCP アグリゲーターであり、AgentCore Gateway サービスではありません。その結果、Cedar ポリシーはローカルでは評価されません。すべてのエージェントは、接続されているすべての MCP サーバーのすべてのツールを参照できます。Cedar ポリシーを実行するには、代わりにエージェントの serve ターゲットを実行して（TypeScript / Python agent-connection ガイドを参照）、ローカルで実行されているエージェントがデプロイされた Gateway を呼び出すようにします。

ツール名は、デプロイされた Gateway の名前空間に合わせて、ローカルでも <target-name>___<tool-name> としてプレフィックスが付けられるため、エージェントのシステムプロンプトと参照する Cedar アクション名は、ローカル実行とデプロイ実行の間で一貫性が保たれます。

�が保たれます。 :::