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. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - py#mcp-server
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Mẹo

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

Parameter	Type	Default	Description
project Required	string	-	The project to add an MCP server to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your MCP server. Select None for no hosting.
name	string	-	The name of your MCP server (default: mcp-server)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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

Ghi chú

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

Ghi chú

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

Ghi chú

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
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.ts CDK construct chung để triển khai lên Bedrock AgentCore Runtime

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"
      }
    }
  }
}

Chú ý

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

Mẹo

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 run your-project:your-server-name-inspect

yarn

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

npm

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

bun

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

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 run your-project:your-server-name-serve-stdio

yarn

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

npm

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

bun

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

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 run your-project:your-server-name-serve

yarn

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

npm

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

bun

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

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 HTTP, thường chạy trên cổng 8000.

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

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"
}

Chú ý

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

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 của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvoke. 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.agentCoreRuntime.grantInvoke(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 agent 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 JWT

Phần dưới đây minh họa cách cấu hình xác thực Cognito cho agent của bạn.

CDK

Để cấu hình xác thực JWT, bạn có thể truyền thuộc tính authorizerConfiguration vào MCP server construct của mình. Đây là một ví dụ cấu hình Cognito user pool và client để bảo mật MCP server:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

Để cấu hình xác thực JWT, bạn có thể chỉnh sửa MCP Server module của mình để cấu hình biến customJWTAuthorizer như sau:

packages/common/terraform/src/app/mcp-servers/my-project-mcp-server/my-project-mcp-server.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Thay thế bằng user pool và client ids của bạn hoặc expose dưới dạng biến
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectMcpServer"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "MCP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

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

Mẹo

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.