TypeScript Agent から MCP へ

connection ジェネレーターは、TypeScript Agent を MCP サーバー（TypeScript または Python）に接続できます。

このジェネレーターは、エージェントが MCP サーバーのツールを検出して呼び出すために必要なすべての配線を設定します。これは、AWS にデプロイされた場合（Bedrock AgentCore 経由）とローカルで実行される場合の両方で機能します。

前提条件

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

1. Strands Agent コンポーネントを持つ TypeScript プロジェクト
2. MCP サーバーコンポーネント（ts#mcp-server または py#mcp-server）を持つプロジェクト
3. 両方のコンポーネントが infra: agentcore で作成されていること

使用方法

ジェネレーターの実行

このジェネレーターを実行@aws/nx-plugin:connection

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

VSCode

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

オプション

ジェネレーターオプション5 オプション

sourceProject必須string

ソース プロジェクト

targetProject必須string

接続先のターゲット プロジェクト

sourceComponentstring

接続元のソースコンポーネント（コンポーネント名、ソースプロジェクトルートからの相対パス、またはジェネレーターID）。プロジェクトをソースとして明示的に選択するには '.' を使用します。

targetComponentstring

接続先のターゲットコンポーネント（コンポーネント名、ターゲットプロジェクトルートからの相対パス、またはジェネレーターID）。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。

preferInstallDependenciesbooleanデフォルト: true

ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは共有の agent-connection パッケージを作成し、エージェントコードを変更します：

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directoryapp

      • <mcp-server-name>-client-strands.ts 接続された MCP サーバー用の高レベル Strands クライアント
    • Directorycore

      • agentcore-endpoints.ts フレームワークに依存しない ARN/URL 解決
      • agentcore-fetch.ts フレームワークに依存しない SigV4 / JWT / セッション転送 fetch
      • agentcore-transport.ts 共有 AgentCore トランスポート配管
      • agentcore-mcp-transport.ts フレームワークに依存しない MCP トランスポート
      • agentcore-mcp-client-strands.ts トランスポートをラップする Strands MCP クライアント
    • index.ts すべてのクライアントをエクスポート
  • project.json
  • tsconfig.json

さらに、以下を行います：

• エージェントの agent.ts を変換して、MCP サーバーのツールをインポートして使用する
• エージェントの dev ターゲットを更新して、MCP サーバーの serve ターゲットに依存させる
• 必要な依存関係をインストールする

接続された MCP サーバーの使用

ジェネレーターは、エージェントの agent.ts を変換して MCP サーバーのツールを使用します：

packages/example/src/my-agent/agent.ts

import { Agent, tool } from '@strands-agents/sdk';
import { MyMcpServerClientStrands } from '@my-scope/agent-connection';

export const getAgent = async () => {
  const myMcpServerClient = await MyMcpServerClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myMcpServerClient],
  });
};

AgentCore セッション ID は、X-Amzn-Bedrock-AgentCore-Runtime-Session-Id ヘッダーを介して MCP サーバーに自動的に伝播されるため、create() は引数を取りません。エージェントサーバーは、受信リクエストのセッションを AsyncLocalStorage コンテキスト（生成された router.ts の enterSessionContext、または A2A/AG-UI セッションミドルウェアの runWithSessionId）にバインドし、agentcore-fetch.ts の接続クライアントの fetch がすべての送信呼び出しにそれをスタンプします。これにより、Bedrock AgentCore Observability の一貫性が確保されます。

インフラストラクチャ

インフラストラクチャプロジェクトが必要

agent、MCP server、Gateway ジェネレーターは、それらのコンストラクトとモジュールを packages/common に提供しますが、それらをデプロイするためのアプリケーションは作成しません。そのため、packages/infra は生成するまで存在しません。以下のファイルを編集する前に、ts#infra ジェネレーター（CDK）または terraform#project ジェネレーター（Terraform）を実行してください。

CDK

接続ジェネレーターを実行した後、エージェントに MCP サーバーを呼び出す権限を付与する必要があります：

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

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

grantInvokeAccess は、MCP サーバーのランタイム ARN に対して AgentCore の呼び出しアクション（InvokeAgentRuntime、InvokeAgentRuntimeForUser、InvokeAgentRuntimeWithWebSocketStream）を設定します。

MCP サーバーの AgentCore ランタイム ARN は、生成された CDK コンストラクトによって Runtime Configuration の agentcore 名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

Terraform

接続ジェネレーターを実行した後、Terraform 設定でエージェントに MCP サーバーを呼び出す権限を付与する必要があります：

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.inventory_mcp_server.agent_core_runtime_arn,
        "${module.inventory_mcp_server.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

MCP サーバーの AgentCore ランタイム ARN は、生成された Terraform モジュールによって Runtime Configuration の agentcore 名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

ローカル開発

ジェネレーターは、エージェントの dev ターゲットを次のように設定します：

1. 接続された MCP サーバーを自動的に起動する
2. LOCAL_DEV=true を設定して、生成されたクライアントが AgentCore の代わりに直接 HTTP トランスポートを使用するようにする

エージェントをローカルで実行するには：

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

これにより、エージェントとすべての接続された MCP サーバーが起動し、エージェントは割り当てられたローカルポートで HTTP 経由で MCP サーバーに直接接続します。