AgentCore Gateway から MCP サーバーへ

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

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

前提条件

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

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

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

使用方法

ジェネレーターの実行

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

VSCode

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

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

オプション

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

ジェネレーターの出力

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

• Directorypackages/<gateway>

  • project.json Gateway の dev ターゲットが MCP サーバーの <mcp>-dev への依存関係を取得
  • local-dev.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');

// Register the MCP server as a target of the Gateway. The target name
// defaults to the MCP server's `mcpServerName` (its class name in
// kebab-case, e.g. `MyMcpServer` -> `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]
}

# Register the MCP server as a target of the 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 = module.my_mcp_server.invocation_url
      }
    }
  }

  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 エージェント接続ガイドを参照）。これにより、ローカルで実行されているエージェントがデプロイされた Gateway を呼び出します。

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