TypeScript Agent đến MCP

Trình tạo connection có thể kết nối TypeScript Agent của bạn với máy chủ MCP (có thể là TypeScript hoặc Python).

Trình tạo này thiết lập tất cả các kết nối cần thiết để agent của bạn có thể khám phá và gọi các công cụ của máy chủ MCP, cả khi triển khai lên AWS (thông qua Bedrock AgentCore) và khi chạy cục bộ.

Điều kiện tiên quyết

Trước khi sử dụng trình tạo này, hãy đảm bảo bạn có:

1. Một dự án TypeScript với thành phần Strands Agent
2. Một dự án với thành phần máy chủ MCP (có thể là ts#mcp-server hoặc py#mcp-server)
3. Cả hai thành phần được tạo với infra: agentcore

Cách sử dụng

Chạy trình tạo

Chạy generator này@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. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

Xây dựng lệnh của bạn5

sourceProjectBắt buộc

targetProjectBắt buộc

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runBạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

Chọn dự án agent của bạn làm nguồn và dự án máy chủ MCP của bạn làm đích. Nếu các dự án của bạn chứa nhiều thành phần, hãy chỉ định các tùy chọn sourceComponent và targetComponent để phân biệt.

Tùy chọn

Tùy chọn của generator5 tùy chọn

sourceProjectBắt buộcstring

Dự án nguồn

targetProjectBắt buộcstring

Dự án đích để kết nối tới

sourceComponentstring

Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc id của generator). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.

targetComponentstring

Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc id của generator). Sử dụng '.' để chọn rõ ràng dự án làm đích.

preferInstallDependenciesbooleanMặc định: true

Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của trình tạo

Trình tạo tạo ra một gói agent-connection được chia sẻ và sửa đổi mã agent của bạn:

• Thư mụcpackages/common/agent-connection

  • Thư mụcsrc

    • Thư mụcapp

      • <mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
    • Thư mụccore

      • 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

Ngoài ra, nó:

• Chuyển đổi agent.ts của agent để import và sử dụng các công cụ của máy chủ MCP
• Cập nhật target dev của agent để phụ thuộc vào target serve của máy chủ MCP
• Cài đặt các phụ thuộc cần thiết

Sử dụng máy chủ MCP đã kết nối

Trình tạo chuyển đổi agent.ts của agent để sử dụng các công cụ của máy chủ 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],
  });
};

ID phiên AgentCore được truyền tự động đến máy chủ MCP thông qua header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, vì vậy create() không nhận tham số nào: máy chủ agent liên kết phiên của yêu cầu đến vào ngữ cảnh AsyncLocalStorage (enterSessionContext trong router.ts được tạo, hoặc runWithSessionId trong middleware phiên A2A/AG-UI), và fetch của client kết nối trong agentcore-fetch.ts đánh dấu nó trên mọi cuộc gọi đi — đảm bảo tính nhất quán cho Bedrock AgentCore Observability.

Cơ sở hạ tầng

Yêu cầu dự án hạ tầng

Các trình tạo agent, MCP server và Gateway cung cấp các construct và module của chúng vào packages/common, nhưng chúng không tạo ứng dụng để triển khai chúng — do đó packages/infra không tồn tại cho đến khi bạn tạo nó. Chạy trình tạo ts#infra (CDK) hoặc trình tạo terraform#project (Terraform) trước khi chỉnh sửa tệp bên dưới.

CDK

Sau khi chạy trình tạo kết nối, bạn cần cấp quyền cho agent để gọi máy chủ 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 kết nối các hành động gọi AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeForUser và InvokeAgentRuntimeWithWebSocketStream) trên ARN runtime của máy chủ MCP.

ARN runtime AgentCore của máy chủ MCP được tự động đăng ký trong namespace agentcore của Runtime Configuration bởi construct CDK được tạo, để agent có thể khám phá nó tại runtime.

Terraform

Sau khi chạy trình tạo kết nối, bạn cần cấp quyền cho agent để gọi máy chủ MCP trong cấu hình Terraform của bạn:

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
}

ARN runtime AgentCore của máy chủ MCP được tự động đăng ký trong namespace agentcore của Runtime Configuration bởi module Terraform được tạo, để agent có thể khám phá nó tại runtime.

Phát triển cục bộ

Trình tạo cấu hình target dev của agent để:

1. Tự động khởi động (các) máy chủ MCP đã kết nối
2. Đặt LOCAL_DEV=true để client được tạo sử dụng truyền tải HTTP trực tiếp thay vì AgentCore

Chạy agent cục bộ với:

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>

Điều này sẽ khởi động cả agent và tất cả các máy chủ MCP đã kết nối, với agent kết nối trực tiếp đến các máy chủ MCP qua HTTP trên các cổng cục bộ được chỉ định của chúng.