TypeScript Agent 到 MCP

connection 生成器可以将您的 TypeScript Agent 连接到 MCP 服务器（TypeScript 或 Python）。

该生成器设置所有必要的连接，使您的 agent 能够发现和调用 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您还可以执行试运行以查看哪些文件会被更改

选择您的 agent 项目作为源，选择您的 MCP 服务器项目作为目标。如果您的项目包含多个组件，请指定 sourceComponent 和 targetComponent 选项以消除歧义。

选项

生成器选项5 个选项

sourceProject必需string

源项目

targetProject必需string

要连接到的目标项目

sourceComponentstring

要连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。

targetComponentstring

要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。

preferInstallDependenciesboolean默认值: true

是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器会创建一个共享的 agent-connection 包并修改您的 agent 代码：

• 文件夹packages/common/agent-connection

  • 文件夹src

    • 文件夹app

      • <mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
    • 文件夹core

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
      • agentcore-transport.ts Shared AgentCore transport plumbing
      • agentcore-mcp-transport.ts Framework-agnostic MCP transport
      • agentcore-mcp-client-strands.ts Strands MCP client wrapping the transport
    • index.ts Exports all clients
  • project.json
  • tsconfig.json

此外，它还会：

• 转换您的 agent 的 agent.ts 以导入和使用 MCP 服务器的工具
• 更新 agent 的 dev 目标以依赖 MCP 服务器的 serve 目标
• 安装所需的依赖项

使用已连接的 MCP 服务器

生成器会转换您的 agent 的 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() 不需要参数：agent 服务器将入站请求的会话绑定到 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

运行连接生成器后，您需要授予 agent 调用 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 构造自动注册到 运行时配置 的 agentcore 命名空间中，以便 agent 可以在运行时发现它。

Terraform

运行连接生成器后，您需要在 Terraform 配置中授予 agent 调用 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 模块自动注册到 运行时配置 的 agentcore 命名空间中，以便 agent 可以在运行时发现它。

本地开发

生成器会配置 agent 的 dev 目标以：

1. 自动启动已连接的 MCP 服务器
2. 设置 LOCAL_DEV=true，使生成的客户端使用直接 HTTP 传输而不是 AgentCore

使用以下命令在本地运行 agent：

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>

这将启动 agent 和所有已连接的 MCP 服务器，agent 将通过 HTTP 在其分配的本地端口上直接连接到 MCP 服务器。