AgentCore Gateway đến MCP Server

Generator connection có thể đăng ký một MCP server (có thể là TypeScript hoặc Python) làm target của một AgentCore Gateway.

Sau khi được kết nối, Gateway tổng hợp các công cụ của MCP server vào một endpoint MCP duy nhất, đánh giá các lời gọi dựa trên Cedar policy engine của nó, và ký lưu lượng truy cập đi ra đến MCP server bằng IAM SigV4.

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

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

1. Một dự án agentcore-gateway
2. Một component MCP server (ts#mcp-server hoặc py#mcp-server) được tạo với infra: agentcore và auth: iam

Gateway phải có protocol: mcp và MCP server phải có auth: iam — generator sẽ xác thực cả hai. Các MCP server không dùng IAM không thể được đính kèm vì Gateway ký lưu lượng truy cập đi ra bằng SigV4.

Cách sử dụng

Chạy Generator

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

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

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. 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

Chọn dự án Gateway làm nguồn và dự án MCP server làm target. Nếu dự án MCP server chứa nhiều component, hãy chỉ định targetComponent để phân biệt.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	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 generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	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 generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.
preferInstallDependencies	boolean	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 Generator

Generator kết nối các dự án hiện có với nhau thay vì tạo ra các file nguồn mới. Các file sau sẽ được sửa đổi:

• Thư mụcpackages/<gateway>

  • project.json target dev của Gateway có thêm dependency vào <mcp>-dev của MCP server
  • local-dev.ts ATTACHED_MCP_SERVERS được cập nhật để gateway cục bộ tổng hợp MCP server

Target dev của dự án Gateway có thêm dependency vào target <mcp>-dev của MCP server, do đó khi chạy Gateway cục bộ cũng sẽ khởi động MCP server. MCP server cũng được đăng ký trong local-dev.ts của dự án Gateway để gateway cục bộ tổng hợp các công cụ của nó.

Thêm MCP server target vào stack của bạn

Generator không thể tự động kết nối MCP server target vào cơ sở hạ tầng của bạn vì nó không biết stack hoặc module nào khởi tạo Gateway. Hãy tự thêm một lời gọi duy nhất gateway.addMcpServer(server).

CDK

Trong stack nơi bạn khởi tạo Gateway, hãy đăng ký MCP server làm target:

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);

Tên target của Gateway (mặc định là mcpServerName của MCP server) được sử dụng làm tiền tố cho tên action của Cedar — định dạng action là AgentCore::Action::"<targetName>___<toolName>". Xem phần Writing Policies. Giữ tên target ngắn gọn và ổn định; việc thay đổi nó sau này sẽ làm mất hiệu lực bất kỳ Cedar policy nào tham chiếu đến tên cũ.

Để ghi đè tên target mặc định, hãy truyền gatewayTargetName:

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

Construct cấu hình target với iamCredentialProvider.service = 'bedrock-agentcore' để Gateway ký các lời gọi đi ra bằng execution role của chính nó.

Terraform

Trong file Terraform nơi bạn khởi tạo Gateway, hãy kết nối MCP server target vào:

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 của target (my-mcp-server ở trên) được sử dụng làm tiền tố cho tên action của Cedar — xem phần Writing Policies. policy_dependencies đảm bảo các Cedar policy tham chiếu đến các action của target này được tạo sau khi target đã đăng ký chúng.

Phát triển cục bộ

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

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

khởi động một gateway cục bộ cùng với mọi MCP server được đính kèm trên cổng cục bộ được chỉ định của nó. Gateway cục bộ cung cấp một endpoint MCP duy nhất tổng hợp các công cụ của các server được đính kèm. Các agent được kết nối với Gateway thông qua generator kết nối gateway TypeScript hoặc Python sẽ trỏ đến nó khi chạy với LOCAL_DEV=true.

Độ trung thực cục bộ

Phát triển cục bộ sử dụng một gateway thay thế cục bộ — một MCP aggregator nhẹ được khởi động bởi dự án Gateway, không phải dịch vụ AgentCore Gateway. Do đó, các Cedar policy không được đánh giá cục bộ. Mọi agent đều thấy mọi công cụ trên mọi MCP server được đính kèm. Để thực thi các Cedar policy, hãy chạy target serve của agent thay thế (xem hướng dẫn kết nối agent TypeScript / Python) để agent chạy cục bộ gọi đến Gateway đã triển khai.

Tên công cụ vẫn được thêm tiền tố cục bộ là <target-name>___<tool-name> để khớp với cách đặt tên namespace của Gateway đã triển khai, do đó system prompt của agent và tên action Cedar mà bạn tham chiếu vẫn nhất quán giữa các lần chạy cục bộ và đã triển khai.