AgentCore Gateway tới MCP Server

Trình tạo connection có thể đăng ký một MCP server (có thể là TypeScript hoặc Python) làm đích 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 điểm cuối MCP duy nhất, đánh giá các lệnh gọi dựa trên công cụ chính sách Cedar của nó, và ký lưu lượng truy cập đi ra tới MCP server bằng IAM SigV4.

Đ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 agentcore-gateway
2. Một thành phần 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 — trình tạo xác thực cả hai. Các MCP server không sử dụng IAM không thể được gắn kết vì Gateway ký lưu lượng truy cập đi ra bằng SigV4.

Cách sử dụng

Chạy Trình tạo

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

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

Chọn dự án Gateway làm nguồn và dự án MCP server làm đích. Nếu dự án MCP server chứa nhiều thành phần, 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 Trình tạo

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

• Thư mụcpackages/<gateway>

  • project.json <gateway>-dev có thêm phụ thuộc 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 phụ thuộc 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 target MCP server vào stack của bạn

Trình tạo không thể tự động kết nối target MCP server 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ệnh 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 construct's id in kebab-case (`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 hành động Cedar — định dạng hành động là AgentCore::Action::"<targetName>___<toolName>". Xem phần Viết Chính sách. Giữ tên target ngắn gọn và ổn định; thay đổi nó sau này sẽ làm mất hiệu lực bất kỳ chính sách Cedar 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ệnh gọi đi ra bằng vai trò thực thi của chính nó.

Terraform

Trong tệp Terraform nơi bạn khởi tạo Gateway, hãy kết nối target MCP server 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 = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(module.my_mcp_server.agent_core_runtime_arn)}/invocations?qualifier=DEFAULT"
      }
    }
  }

  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 hành động Cedar — xem phần Viết Chính sách. policy_dependencies đảm bảo các chính sách Cedar tham chiếu đến các hành động 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 gắn kết trên cổng cục bộ được chỉ định của nó. Gateway cục bộ cung cấp một điểm cuối MCP duy nhất tổng hợp các công cụ của các server được gắn kết. Các agent được kết nối với Gateway thông qua các trình tạo kết nối gateway TypeScript hoặc Python sẽ trỏ đến nó khi chạy với SERVE_LOCAL=true.

Độ chính xác cục bộ

Phát triển cục bộ sử dụng một gateway cục bộ thay thế — một bộ tổng hợp MCP nhẹ được khởi động bởi dự án Gateway, không phải dịch vụ AgentCore Gateway. Do đó, các chính sách Cedar 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 gắn kết. Để thực thi các chính sách Cedar, hãy chạy target serve của agent thay thế (xem hướng dẫn kết nối agent TypeScript / Python) để agent đang chạy cục bộ gọi 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 không gian của Gateway đã triển khai, do đó lời nhắc hệ thống của agent và tên hành động 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.