Python MCP Server

Tạo một Python Model Context Protocol (MCP) server để cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLMs), và tùy chọn triển khai nó lên Amazon Bedrock AgentCore.

MCP là gì?

Model Context Protocol (MCP) là một tiêu chuẩn mở cho phép các trợ lý AI tương tác với các công cụ và tài nguyên bên ngoài. Nó cung cấp một cách nhất quán để các LLM có thể:

Thực thi các công cụ (hàm) để thực hiện các hành động hoặc truy xuất thông tin
Truy cập các tài nguyên cung cấp ngữ cảnh hoặc dữ liệu

Sử dụng

Tạo một MCP Server

Bạn có thể tạo một Python MCP server theo hai cách:

Chạy generator này@aws/nx-plugin:py#mcp-server

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:py#mcp-server

$ yarn nx g @aws/nx-plugin:py#mcp-server

$ npx nx g @aws/nx-plugin:py#mcp-server

$ bunx nx g @aws/nx-plugin:py#mcp-server

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - py#mcp-server
Điền các tham số bắt buộc
Nhấp Generate

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

projectBắt buộc

authinfra = agentcore | agentcore-ecr

iac

infra

name

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

Tùy chọn

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

projectBắt buộcstring: Dự án để thêm MCP server vào
authenuminfra = agentcore | agentcore-ecrMặc định: iam: Phương thức được sử dụng để xác thực với MCP server của bạn. Chỉ áp dụng khi infra được thiết lập (bị bỏ qua khi infra là none).
iamcognito
iacenumMặc định: inherit: Nhà cung cấp IaC ưu tiên. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
inheritcdkterraform
infraenumMặc định: agentcore: Loại hạ tầng để lưu trữ MCP server của bạn. agentcore triển khai mã của bạn dưới dạng zip đến môi trường runtime được quản lý bởi AgentCore để có chu kỳ build và deploy nhanh nhất. agentcore-ecr build và lưu trữ container image thay vào đó, để kiểm soát ở cấp độ hệ điều hành hoặc pipeline container đã thiết lập. Chọn none để không có hosting.
agentcoreagentcore-ecrnone
namestring: Tên của MCP server của bạn (mặc định: mcp-server)
preferInstallDependenciesbooleanMặc định: true: Có nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để 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 sẽ thêm các tệp sau vào dự án Python hiện có của bạn:

Thư mụcyour-project/
- Thư mụcyour_module/
  - Thư mụcmcp_server/ (or custom name if specified)
    __init__.py Python package initialization
    server.py Main server definition with sample tools and resources
    stdio.py Entry point for STDIO transport, useful for simple local MCP servers
    http.py Entry point for Streamable HTTP transport, useful for hosting your MCP server
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with MCP dependencies
- project.json Updated with MCP server serve targets

Hạ tầng

Tùy chọn infra chọn cách mã của bạn được đóng gói và lưu trữ trên Amazon Bedrock AgentCore Runtime:

agentcore (mặc định) sử dụng triển khai mã trực tiếp: mã đã build của bạn được đóng gói dưới dạng .zip, tải lên S3 và chạy trên runtime ngôn ngữ được quản lý bởi AgentCore. Không có container image để build, không có ECR repository để quản lý và không có image để push, điều này giúp chu kỳ build và deploy nhanh hơn đáng kể.
agentcore-ecr build một container image arm64 từ Dockerfile được cung cấp và lưu trữ nó từ registry core/asset-ecr được chia sẻ, cùng với mọi container khác trong workspace. Chọn tùy chọn này khi bạn cần kiểm soát image hệ điều hành — ví dụ để cài đặt các thư viện hệ thống gốc — hoặc khi bạn có một pipeline container đã thiết lập. Tùy chọn này cũng cung cấp thêm mục tiêu quét image Trivy (xem Image Scanning bên dưới).
none không tạo cơ sở hạ tầng nào cả, vì vậy dự án chỉ có thể chạy cục bộ.

Vì generator này cung cấp infrastructure as code dựa trên iac bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK
Terraform

Thư mụcpackages/common/constructs
- Thư mụcsrc
  - Thư mụcapp/ Constructs for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

Để triển khai MCP Server của bạn, các tệp sau được tạo ra:

CDK
Terraform

Thư mụcpackages/common/constructs/src
- Thư mụcapp
  - Thư mụcmcp-servers
    Thư mục<mcp-server-name>
    <mcp-server-name>.ts CDK construct for deploying your MCP Server

Thư mụcpackages/common/terraform/src
- Thư mụcapp
  - Thư mụcmcp-servers
    Thư mục<mcp-server-name>
    <mcp-server-name>.tf Module for deploying your MCP Server
- Thư mụccore
  - Thư mụcagent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - Thư mụcagent-core-code (when infra is agentcore)
    runtime.tf Packages your MCP Server’s code and delegates to agent-core
  - Thư mụcagent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your MCP Server’s image and delegates to agent-core

Nếu bạn chọn none cho infra, không có CDK constructs hoặc Terraform modules nào được tạo ra — MCP server được cấu hình chỉ để sử dụng STDIO / HTTP cục bộ. Tùy chọn auth bị bỏ qua trong chế độ này vì không có endpoint được lưu trữ để xác thực.

Kiến trúc

Khi triển khai lên Bedrock AgentCore Runtime, mã nguồn của server được đóng gói dưới dạng zip và chạy trong AgentCore managed runtime. Các trợ lý AI gọi đến data plane endpoint của AgentCore Runtime, endpoint này chuyển tiếp các lời gọi tools/* và resources/* đến server của bạn qua streamable HTTP transport.

Loading the diagram…

Với infra: agentcore-ecr, MCP server được xây dựng thành container image, đẩy lên Amazon ECR và chạy trong AgentCore Runtime. Điều này cho phép bạn kiểm soát môi trường runtime ở cấp độ hệ điều hành, với chi phí là chu kỳ build và deploy dài hơn so với đóng gói zip ở trên.

Loading the diagram…

Với infra: none, không có cơ sở hạ tầng AWS nào được tạo ra. MCP server được cấu hình chỉ cho STDIO và HTTP transports cục bộ, và được sử dụng bởi các trợ lý AI chạy trên cùng một máy.

Loading the diagram…

Làm việc với MCP Server của bạn

Thêm Công cụ

Công cụ là các hàm mà trợ lý AI có thể gọi để thực hiện các hành động. Python MCP server sử dụng thư viện MCP Python SDK (FastMCP), cung cấp một cách tiếp cận dựa trên decorator đơn giản để định nghĩa các công cụ.

Bạn có thể thêm các công cụ mới trong tệp server.py:

@mcp.tool(description="Your tool description")
def your_tool_name(param1: str, param2: int) -> str:
    """Tool implementation with type hints"""
    # Your tool logic here
    return f"Result: {param1} with {param2}"

Thư viện FastMCP tự động xử lý:

Xác thực kiểu dựa trên các gợi ý kiểu của hàm của bạn
Tạo JSON schema cho giao thức MCP
Xử lý lỗi và định dạng phản hồi

Thêm Tài nguyên

Tài nguyên cung cấp ngữ cảnh cho trợ lý AI. Bạn có thể thêm tài nguyên bằng cách sử dụng decorator @mcp.resource:

@mcp.resource("example://static-resource", description="Static resource example")
def static_resource() -> str:
    """Return static content"""
    return "This is static content that provides context to the AI"

@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
def dynamic_resource(item_id: str) -> str:
    """Return dynamic content based on parameters"""
    # Fetch data based on item_id
    data = fetch_data_for_item(item_id)
    return f"Dynamic content for {item_id}: {data}"

Cấu hình với Trợ lý AI

Tệp Cấu hình

Hầu hết các trợ lý AI hỗ trợ MCP đều sử dụng phương pháp cấu hình tương tự. Bạn sẽ cần tạo hoặc cập nhật tệp cấu hình với thông tin chi tiết về MCP server của mình:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "my_module.mcp_server.stdio"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/your/project/.venv"
      }
    }
  }
}

Cấu hình Dành riêng cho Trợ lý

Vui lòng tham khảo tài liệu sau để cấu hình MCP với các Trợ lý AI cụ thể:

Chạy MCP Server của bạn

Phát triển Cục bộ

Để chạy MCP server của bạn (và mọi thứ được kết nối với nó, chẳng hạn như cơ sở dữ liệu cục bộ) cục bộ, hãy sử dụng target dev của dự án:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Nếu bạn đã thêm nhiều thành phần vào dự án của mình (MCP servers, agents, v.v.), điều này sẽ khởi động tất cả chúng. Để chỉ chạy MCP server này, hãy nhắm đến target <your-server-name>-dev của nó:

pnpm nx your-server-name-dev your-project

yarn nx your-server-name-dev your-project

npx nx your-server-name-dev your-project

bunx nx your-server-name-dev your-project

Inspector

Trình tạo cấu hình một target có tên <your-server-name>-inspect, khởi động MCP server của bạn cục bộ (thông qua target <your-server-name>-dev, bao gồm bất kỳ phụ thuộc được kết nối nào như cơ sở dữ liệu cục bộ) và khởi chạy MCP Inspector được cấu hình sẵn để kết nối với nó qua Streamable HTTP transport.

pnpm nx your-server-name-inspect your-project

yarn nx your-server-name-inspect your-project

npx nx your-server-name-inspect your-project

bunx nx your-server-name-inspect your-project

Điều này sẽ khởi động inspector tại http://localhost:6274. Bắt đầu bằng cách nhấp vào nút “Connect”.

STDIO

Cách dễ nhất để kiểm tra và sử dụng một MCP server là sử dụng inspector hoặc cấu hình nó với một trợ lý AI (như trên).

Tuy nhiên, bạn có thể chạy server của mình với STDIO transport trực tiếp bằng cách sử dụng target <your-server-name>-serve-stdio.

pnpm nx your-server-name-serve-stdio your-project

yarn nx your-server-name-serve-stdio your-project

npx nx your-server-name-serve-stdio your-project

bunx nx your-server-name-serve-stdio your-project

Lệnh này sử dụng uv run để thực thi MCP server của bạn với STDIO transport.

Streamable HTTP

Nếu bạn muốn chạy MCP server của mình cục bộ bằng Streamable HTTP transport, bạn có thể sử dụng target <your-server-name>-serve.

pnpm nx your-server-name-serve your-project

yarn nx your-server-name-serve your-project

npx nx your-server-name-serve your-project

bunx nx your-server-name-serve your-project

Lệnh này sử dụng uv run uvicorn --reload để chạy MCP server của bạn với HTTP transport, và tự động khởi động lại khi các tệp thay đổi.

Mỗi MCP server được gán một cổng riêng, bắt đầu từ 8000, do đó nhiều server có thể chạy song song trong cùng một workspace. Đọc cổng mà server của bạn lắng nghe từ target <your-server-name>-serve của nó trong project.json.

Triển khai MCP Server của bạn lên Bedrock AgentCore Runtime

Infrastructure as Code

Nếu bạn chọn agentcore hoặc agentcore-ecr cho infra, cơ sở hạ tầng CDK hoặc Terraform liên quan sẽ được tạo ra mà bạn có thể sử dụng để triển khai MCP server của mình lên Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Một CDK construct được tạo ra cho MCP Server của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy generator, hoặc <ProjectName>McpServer theo mặc định.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

import { MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the MCP server to your stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Một Terraform module được tạo ra cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy generator, hoặc <ProjectName>-mcp-server theo mặc định.

Truyền các outputs của module runtime_config_appconfig được chia sẻ vào module MCP server, cùng với kho lưu trữ artefact được chia sẻ mà cách đóng gói của nó sử dụng. Với cách đóng gói agentcore mặc định, code của server được lưu trữ trong shared asset bucket, vì vậy hãy khởi tạo module core/asset-bucket một lần cho mỗi deployment, như các module Lambda và API đã làm:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

Với agentcore-ecr, image của server được xuất bản lên shared asset registry thay vì bucket, vì vậy hãy truyền các outputs của core/asset-ecr thay vì của bucket. Một registry phục vụ mọi container trong workspace, vì vậy không có MCP server nào cần repository riêng của mình:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

Xác thực

Generator cung cấp tùy chọn auth để cấu hình xác thực cho MCP server của bạn. Bạn có thể chọn giữa xác thực IAM (mặc định) hoặc Cognito khi tạo MCP server của mình.

IAM

Theo mặc định, MCP server của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần bất kỳ đối số nào:

CDK
Terraform

import { MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Bạn có thể cấp quyền truy cập để gọi MCP server của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvokeAccess. Ví dụ, bạn có thể muốn một agent được tạo bằng generator py#agent gọi MCP server của bạn:

import { MyProjectAgent, MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');

    mcpServer.grantInvokeAccess(agent);
  }
}

# MCP Server
module "my_project_mcp_server" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Để cấp quyền truy cập gọi MCP server của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output module.my_project_mcp_server.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_mcp_server.agent_core_runtime_arn,
    "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
  ]
}

Xác thực Cognito

Khi bạn chọn xác thực Cognito, generator sẽ cấu hình MCP server để sử dụng Cognito cho xác thực.

CDK
Terraform

Construct được tạo ra chấp nhận một prop identity để cấu hình xác thực Cognito:

import { MyProjectMcpServer, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      identity,
    });
  }
}

Construct UserIdentity có thể được tạo bằng generator ts#website#auth, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

Module được tạo ra chấp nhận các biến user_pool_id và user_pool_client_ids cho xác thực Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Bundle và Docker Targets

Để xây dựng MCP server của bạn cho Bedrock AgentCore Runtime, một target bundle được thêm vào dự án của bạn, thực hiện:

Xuất các phụ thuộc Python của bạn sang tệp requirements.txt bằng uv export
Cài đặt các phụ thuộc cho nền tảng đích (aarch64-manylinux_2_28) bằng uv pip install

Một target <your-server-name>-package cũng được thêm vào, tập hợp gói mã có thể triển khai: gói phụ thuộc aarch64, cây module Python của bạn và điểm vào main.py gốc. Hạ tầng được tạo ra tải thư mục này lên dưới dạng .zip — thông qua AgentRuntimeArtifact.fromCodeAsset trong CDK, hoặc được lưu trữ vào bucket tài sản dùng chung trong Terraform.

Một target docker cụ thể cho MCP server của bạn cũng được thêm vào, sao chép Dockerfile và các artifact được đóng gói vào một thư mục ngữ cảnh docker. Điều này đặt Dockerfile cùng vị trí với đầu ra được xây dựng, cho phép CDK xây dựng Docker image trực tiếp bằng AgentRuntimeArtifact.fromAsset.

Quét Image

Docker image được xây dựng cho dự án này có thể được quét để tìm các lỗ hổng bảo mật bằng cách sử dụng Trivy, chạy từ ECR-hosted Trivy image.

Một target trivy được thêm vào dự án của bạn để quét image đã xây dựng và thoát với mã khác không nếu phát hiện bất kỳ lỗ hổng bảo mật mức độ nghiêm trọng HIGH hoặc CRITICAL nào. Dockerfile được tạo ra sử dụng một base image không có lỗ hổng bảo mật có thể sửa chữa nào ở các mức độ nghiêm trọng này tại thời điểm tạo, và nâng cấp các công cụ đi kèm (chẳng hạn như npm) để duy trì trạng thái đó.

Quá trình quét sử dụng cùng container engine với quá trình xây dựng image của bạn (docker hoặc finch), do đó không cần công cụ bổ sung nào. Quá trình quét không được cache, vì image mà nó đọc tồn tại trong container engine thay vì trên đĩa — do đó nó luôn quét image thực tế, và thất bại rõ ràng thay vì báo cáo kết quả pass đã được cache cho một image không còn tồn tại. Do đó, mỗi lần chạy mất hàng chục giây cho mỗi image và làm mới cơ sở dữ liệu lỗ hổng bảo mật của Trivy, vì vậy nó cần truy cập mạng. Script root trivy được cung cấp sẽ quét mọi image trong workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Quá trình quét chạy với --ignore-unfixed, do đó các lỗ hổng bảo mật không có bản sửa lỗi khả dụng sẽ không làm thất bại quá trình build, vì chúng không thể được xử lý bằng cách nâng cấp công cụ trong Dockerfile của bạn — chúng không được báo cáo trong kết quả quét của build. Khi các lỗ hổng bảo mật mới được công bố, kết quả quét có thể thay đổi theo thời gian, vì vậy hãy xem xét image định kỳ bằng cách chạy trivy image <your-image> mà không có flag này, và xây dựng lại với base image mới hơn (hoặc thêm các bước container để áp dụng các bản vá khả dụng) khi một bản sửa lỗi được phát hành.

Loại Bỏ Các Phát Hiện Của Trivy

Có thể có những trường hợp bạn muốn loại bỏ một lỗ hổng bảo mật cụ thể, ví dụ như khi chưa có bản sửa lỗi và bạn đã đánh giá rủi ro là có thể chấp nhận được.

Thêm ID lỗ hổng bảo mật (mỗi dòng một ID) vào file .trivyignore trong thư mục gốc của dự án (tức là bên cạnh project.json của bạn):

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Để biết thêm chi tiết về việc lọc các phát hiện, hãy tham khảo tài liệu lọc của Trivy.

Khả năng quan sát

Máy chủ MCP của bạn được tự động cấu hình với khả năng quan sát bằng cách sử dụng AWS Distro for Open Telemetry (ADOT), thông qua việc cấu hình tự động ghi nhật ký trong Dockerfile của bạn.

Bạn có thể tìm thấy các dấu vết trong CloudWatch AWS Console, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các dấu vết được điền đầy đủ, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, hãy tham khảo tài liệu AgentCore về khả năng quan sát.

Kết nối

Sử dụng trình tạo connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

Python Agent to MCPConnect a Python Agent to an MCP server

Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway