Máy chủ MCP Python

Tạo một máy chủ Model Context Protocol (MCP) bằng Python để cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLM), 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

Cách sử dụng

Tạo một Máy chủ MCP

Bạn có thể tạo một máy chủ MCP bằng Python theo hai cách:

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 - py#mcp-server
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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:py#mcp-server --dry-run

yarn

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

npm

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

bun

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

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

Trước tiên hãy sử dụng trình tạo py#project để tạo một dự án để thêm máy chủ MCP của bạn vào.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm MCP server vào
computeType	string	BedrockAgentCoreRuntime	Loại compute để host MCP server của bạn. Chọn None nếu không cần hosting.
name	string	-	Tên của MCP server của bạn (mặc định: mcp-server)
auth	string	IAM	Phương thức được sử dụng để xác thực với MCP server của bạn. Chọn giữa IAM (mặc định) hoặc Cognito.
iacProvider	string	Inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.

Kết quả từ 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/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • __init__.py Khởi tạo gói Python
      • server.py Định nghĩa máy chủ chính với các công cụ và tài nguyên mẫu
      • stdio.py Điểm vào cho giao vận STDIO, hữu ích cho các máy chủ MCP cục bộ đơn giản
      • http.py Điểm vào cho giao vận HTTP có thể stream, hữu ích cho việc lưu trữ máy chủ MCP của bạn
      • Dockerfile Điểm vào cho việc lưu trữ máy chủ MCP của bạn (loại trừ khi computeType được đặt thành None)
  • pyproject.toml Đã cập nhật với các phụ thuộc MCP
  • project.json Đã cập nhật với các target phục vụ máy chủ MCP

Hạ tầng

Triển khai serverless

Nếu bạn chọn None cho computeType, trình tạo sẽ không cung cấp bất kỳ mã hạ tầng nào.

Vì generator này cung cấp infrastructure as code dựa trên iacProvider 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

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

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

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.ts CDK construct để triển khai MCP Server của bạn
        • Dockerfile Tệp docker passthrough được sử dụng bởi CDK construct

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai MCP Server của bạn
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.tf Module chung để triển khai lên Bedrock AgentCore Runtime

Làm việc với Máy chủ MCP 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. Máy chủ MCP Python 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="Mô tả công cụ của bạn")
def your_tool_name(param1: str, param2: int) -> str:
    """Triển khai công cụ với gợi ý kiểu"""
    # Logic công cụ của bạn ở đây
    return f"Kết quả: {param1} với {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
• 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="Ví dụ tài nguyên tĩnh")
def static_resource() -> str:
    """Trả về nội dung tĩnh"""
    return "Đây là nội dung tĩnh cung cấp ngữ cảnh cho AI"

@mcp.resource("dynamic://resource/{item_id}", description="Ví dụ tài nguyên động")
def dynamic_resource(item_id: str) -> str:
    """Trả về nội dung động dựa trên tham số"""
    # Lấy dữ liệu dựa trên item_id
    data = fetch_data_for_item(item_id)
    return f"Nội dung động cho {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 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"
      }
    }
  }
}

Giải quyết đường dẫn

Nếu bạn nhận được lỗi như ENOENT uv khi kết nối với server của mình, bạn có thể cần chỉ định đường dẫn đầy đủ đến uv, có thể lấy bằng cách chạy lệnh which uv trong terminal của bạn.

Cấu hình Theo Trợ lý Cụ thể

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ể:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Cấu hình workspace

Một số Trợ lý AI, chẳng hạn như Amazon Q Developer, cho phép bạn chỉ định cấu hình MCP server ở cấp độ workspace, điều này đặc biệt hữu ích để xác định các MCP server liên quan cho một dự án cụ thể.

Chạy Máy chủ MCP của bạn

Inspector

Trình tạo cấu hình một target có tên <your-server-name>-inspect, khởi động MCP Inspector với cấu hình để kết nối với máy chủ MCP của bạn bằng giao vận STDIO.

pnpm

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

yarn

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

npm

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

bun

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

Lệnh 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áy chủ MCP 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 máy chủ của mình với giao vận STDIO trực tiếp bằng cách sử dụng target <your-server-name>-serve-stdio.

pnpm

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

yarn

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

npm

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

bun

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

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

Streamable HTTP

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

pnpm

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

yarn

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

npm

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

bun

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

Lệnh này sử dụng uv run uvicorn --reload để chạy máy chủ MCP của bạn với giao vận HTTP (thường trên cổng 8000), và tự động khởi động lại khi các tệp thay đổi.

Triển khai Máy chủ MCP của bạn lên Bedrock AgentCore Runtime

Cơ sở hạ tầng dưới dạng mã (Infrastructure as Code)

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

CDK

Một CDK construct được tạo cho MCP Server của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, 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) {
    // Thêm MCP server vào stack của bạn
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

CDK Construct Alpha

Construct này sử dụng module @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

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

Bạn có thể sử dụng terraform module này trong một dự án Terraform:

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Yêu cầu Docker

Docker là bắt buộc để xây dựng và triển khai MCP server của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Xác thực

Trình tạo 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 tham số nào:

CDK

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 trình tạo py#strands-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.agentCoreRuntime);
  }
}

Terraform

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Để 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, trình tạo sẽ cấu hình MCP server để sử dụng Cognito cho xác thực.

CDK

Construct được tạo chấp nhận 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 trình tạo ts#react-website#auth, hoặc bạn có thể tự tạo CDK UserPool và UserPoolClient của riêng mình.

Terraform

Module được tạo 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"

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

Nhà cung cấp OIDC tùy chỉnh

Nếu bạn cần xác thực JWT tùy chỉnh với OIDC provider không phải Cognito, bạn có thể chỉnh sửa trực tiếp CDK construct hoặc Terraform module được tạo cho MCP server của mình. Lưu ý rằng trình tạo kết nối sẽ chỉ hỗ trợ xác thực IAM hoặc Cognito.

Target Bundle và Docker

Để xây dựng máy chủ MCP 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-manylinux2014) bằng uv pip install

Một target docker cụ thể cho máy chủ MCP của bạn cũng được thêm vào, thực hiện:

• Xây dựng một docker image từ Dockerfile chạy máy chủ MCP của bạn trên cổng 8000, theo hợp đồng giao thức MCP

Tag ảnh Docker

Docker image được xây dựng bằng cách sử dụng một tag (ví dụ my-scope-my-project-mcp-server:latest), được tham chiếu bởi hạ tầng CDK hoặc Terraform của bạn, cho phép Dockerfile của bạn được đặt cùng vị trí với dự án máy chủ MCP của bạn.

Khả năng quan sát

MCP server 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 auto-instrumentation trong Dockerfile của bạn.

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

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