Python MCP 服务器

生成一个Python 模型上下文协议（MCP）服务器，用于为大型语言模型（LLMs）提供上下文，并可选择部署到Amazon Bedrock AgentCore。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，允许AI助手与外部工具和资源交互。它为LLMs提供了一致的方式来：

执行执行操作或检索信息的工具（函数）
访问提供上下文或数据的资源

使用方式

生成MCP服务器

您可以通过两种方式生成Python MCP服务器：

VSCode
CLI

安装 Nx Console VSCode Plugin 如果您尚未安装
在VSCode中打开Nx控制台
点击 Generate (UI) 在"Common Nx Commands"部分
搜索 @aws/nx-plugin - py#mcp-server
填写必需参数
点击 Generate

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

您还可以执行试运行以查看哪些文件会被更改

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

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

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

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

选项参数

参数	类型	默认值	描述
project 必需	string	-	要添加 MCP 服务器的项目
computeType	string	BedrockAgentCoreRuntime	托管 MCP 服务器的计算类型。选择 None 表示不托管。
name	string	-	MCP 服务器的名称（默认：mcp-server）
auth	string	IAM	用于与 MCP 服务器进行身份验证的方法。可选择 IAM（默认）或 Cognito。
iacProvider	string	Inherit	首选的 IaC 提供商。默认情况下，这将继承您的初始选择。

生成器输出

生成器将在现有Python项目中添加以下文件：

文件夹your-project/
- 文件夹your_module/
  - 文件夹mcp_server/ （或指定的自定义名称）
    __init__.py Python包初始化文件
    server.py 主服务器定义，包含示例工具和资源
    stdio.py STDIO传输入口点，适用于简单本地MCP服务器
    http.py 可流式HTTP传输入口点，适用于托管MCP服务器
    Dockerfile MCP服务器托管入口点（当computeType设为None时排除）
- pyproject.toml 更新了MCP依赖项
- project.json 更新了MCP服务器服务目标

基础设施

由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

通用的基础设施即代码项目结构如下：

CDK
Terraform

文件夹packages/common/constructs
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的基础设施构造体
    …
  - 文件夹core/ 被 app 目录构造体重用的通用构造体
    …
  - index.ts 导出 app 目录构造体的入口文件
- project.json 项目构建目标与配置

文件夹packages/common/terraform
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的 Terraform 模块
    …
  - 文件夹core/ 被 app 目录模块重用的通用模块
    …
- project.json 项目构建目标与配置

部署 MCP 服务器时将会生成以下文件：

CDK
Terraform

文件夹packages/common/constructs/src
- 文件夹app
  - 文件夹mcp-servers
    文件夹<project-name>
    <project-name>.ts 用于部署 MCP 服务器的 CDK 构造
    Dockerfile CDK 构造使用的直通式 docker 文件

使用MCP服务器

添加工具

工具是AI助手可以调用的执行操作的函数。Python MCP服务器使用MCP Python SDK (FastMCP)库，该库提供了基于装饰器的工具定义方式。

在server.py文件中添加新工具：

@mcp.tool(description="工具描述")
def your_tool_name(param1: str, param2: int) -> str:
    """带类型提示的工具实现"""
    # 工具逻辑
    return f"结果：{param1} 与 {param2}"

FastMCP库自动处理：

基于函数类型提示的类型验证
MCP协议的JSON模式生成
错误处理和响应格式化

添加资源

资源为AI助手提供上下文。使用@mcp.resource装饰器添加资源：

@mcp.resource("example://static-resource", description="静态资源示例")
def static_resource() -> str:
    """返回静态内容"""
    return "这是为AI提供上下文的静态内容"

@mcp.resource("dynamic://resource/{item_id}", description="动态资源示例")
def dynamic_resource(item_id: str) -> str:
    """根据参数返回动态内容"""
    # 根据item_id获取数据
    data = fetch_data_for_item(item_id)
    return f"{item_id}的动态内容：{data}"

配置AI助手

配置文件

大多数支持 MCP 的 AI 助手都采用相似的配置方式。您需要创建或更新包含 MCP 服务器详细信息的配置文件：

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

特定助手配置

请参考以下文档配置特定 AI 助手的 MCP 设置：

运行MCP服务器

检查器

生成器配置了名为<your-server-name>-inspect的目标，用于启动MCP检查器并通过STDIO传输连接到MCP服务器。

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

检查器将运行在http://localhost:6274。点击”Connect”按钮开始使用。

STDIO模式

测试和使用MCP服务器最简单的方式是使用检查器或按上述方式配置AI助手。

您也可以通过<your-server-name>-serve-stdio目标直接使用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

该命令使用uv run通过STDIO传输执行MCP服务器。

可流式HTTP

如需使用可流式HTTP传输在本地运行MCP服务器，可使用<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

该命令使用uv run uvicorn --reload通过HTTP传输运行MCP服务器（默认在8000端口），并在文件更改时自动重启。

部署到Bedrock AgentCore运行时

基础设施即代码

如果您为 computeType 选择了 BedrockAgentCoreRuntime，系统会生成相应的 CDK 或 Terraform 基础设施代码，您可以用其将 MCP 服务器部署到 Amazon Bedrock AgentCore Runtime。

CDK
Terraform

系统会为您的 MCP 服务器生成一个 CDK 构造，其名称基于生成器运行时指定的 name（默认为 <ProjectName>McpServer）。

您可以在 CDK 应用中使用该 CDK 构造：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // 将 MCP 服务器添加到您的堆栈
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

系统会基于生成器运行时指定的 name（默认为 <ProjectName>-mcp-server）生成一个 Terraform 模块。

您可以在 Terraform 项目中使用该模块：

# MCP 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

认证

生成器提供了 auth 选项来为您的 MCP 服务器配置认证。在生成 MCP 服务器时，您可以在 IAM（默认）或 Cognito 认证之间进行选择。

IAM 认证

默认情况下，您的 MCP 服务器将使用 IAM 认证进行保护，直接部署时无需额外参数：

CDK
Terraform

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

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

您可以使用 grantInvokeAccess 方法授予调用 Bedrock AgentCore Runtime 上 MCP 服务器的权限。例如，您可能希望允许通过 py#strands-agent 生成器创建的代理调用您的 MCP 服务器：

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 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

要授予调用 MCP 服务器的权限，您需要添加如下策略，并引用 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}/*"
  ]
}

Cognito 认证

当您选择 Cognito 认证时，生成器会配置 MCP 服务器使用 Cognito 进行认证。

CDK
Terraform

生成的构造接受一个 identity 属性来配置 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,
    });
  }
}

UserIdentity 构造可以使用 ts#react-website#auth 生成器生成，或者您可以创建自己的 CDK UserPool 和 UserPoolClient。

生成的模块接受 user_pool_id 和 user_pool_client_ids 变量用于 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]
}

打包和Docker目标

要为Bedrock AgentCore Runtime构建MCP服务器，项目中添加了bundle目标，该目标：

使用uv export将Python依赖导出到requirements.txt文件
使用uv pip install为目标平台（aarch64-manylinux2014）安装依赖

同时添加了特定于MCP服务器的docker目标，该目标：

从Dockerfile构建docker镜像，根据MCP协议约定在8000端口运行MCP服务器

可观测性

您的MCP服务器通过配置Dockerfile中的自动检测功能，使用AWS Distro for Open Telemetry (ADOT) 实现了开箱即用的可观测性。

您可以在CloudWatch AWS控制台的菜单中选择”GenAI Observability”查看追踪数据。注意：要使追踪数据正常显示，需先启用Transaction Search功能。

更多详细信息，请参考AgentCore可观测性配置文档。