Servidor MCP de Python

Genera un servidor de Model Context Protocol (MCP) de Python para proporcionar contexto a Modelos de Lenguaje Grande (LLMs), y opcionalmente despliégalo en Amazon Bedrock AgentCore.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA interactuar con herramientas y recursos externos. Proporciona una forma consistente para que los LLMs puedan:

• Ejecutar herramientas (funciones) que realizan acciones o recuperan información
• Acceder a recursos que proporcionan contexto o datos

Uso

Generar un Servidor MCP

Puedes generar un servidor MCP de Python de dos maneras:

Ejecute este generador@aws/nx-plugin:py#mcp-server

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - py#mcp-server
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando6

projectRequerido

authinfra = agentcore | agentcore-ecr

iamcognito

iac

inheritcdkterraform

infra

agentcoreagentcore-ecrnone

name

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Requisito Previo del Proyecto

Primero usa el generador py#project para crear un proyecto al que agregar tu servidor MCP.

Opciones

Opciones del generador6 opciones

projectRequeridostring

El proyecto al que agregar un servidor MCP

authenuminfra = agentcore | agentcore-ecrPredeterminado: iam

El método utilizado para autenticar con tu servidor MCP. Solo aplicable cuando infra está configurado (se ignora cuando infra es none).

iamcognito

iacenumPredeterminado: inherit

El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.

inheritcdkterraform

infraenumPredeterminado: agentcore

El tipo de infraestructura para alojar tu servidor MCP. agentcore despliega tu código como un zip en un runtime administrado por AgentCore para el ciclo de construcción y despliegue más rápido. agentcore-ecr construye y aloja una imagen de contenedor en su lugar, para control a nivel de sistema operativo o un pipeline de contenedores establecido. Selecciona none para no tener alojamiento.

agentcoreagentcore-ecrnone

namestring

El nombre de tu servidor MCP (predeterminado: mcp-server)

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al procesar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador agregará los siguientes archivos a tu proyecto de Python existente:

• Directorioyour-project/

  • Directorioyour_module/

    • Directoriomcp_server/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete de Python
      • server.py Definición principal del servidor con herramientas y recursos de ejemplo
      • stdio.py Punto de entrada para transporte STDIO, útil para servidores MCP locales simples
      • http.py Punto de entrada para transporte HTTP transmisible, útil para alojar tu servidor MCP
      • Dockerfile Definición de imagen de contenedor (solo cuando infra es agentcore-ecr)
  • pyproject.toml Actualizado con dependencias de MCP
  • project.json Actualizado con objetivos de servicio del servidor MCP

Infraestructura

La opción infra selecciona cómo se empaqueta y aloja tu código en Amazon Bedrock AgentCore Runtime:

• agentcore (predeterminado) utiliza despliegue directo de código: tu código compilado se empaqueta como un .zip, se sube a S3 y se ejecuta en un runtime de lenguaje administrado por AgentCore. No hay imagen de contenedor que construir, no hay repositorio ECR que administrar y no hay imagen que enviar, lo que resulta en un ciclo de compilación e implementación sustancialmente más rápido.
• agentcore-ecr construye una imagen de contenedor arm64 a partir de un Dockerfile proporcionado y la aloja desde el registro compartido core/asset-ecr, junto con todos los demás contenedores en el workspace. Elige esta opción cuando necesites control sobre la imagen del sistema operativo — por ejemplo, para instalar bibliotecas nativas del sistema — o cuando tengas un pipeline de contenedores establecido. Esta opción también proporciona un objetivo de escaneo de imagen Trivy (consulta Escaneo de Imágenes a continuación).
• none no genera ninguna infraestructura, por lo que el proyecto solo se puede ejecutar localmente.

infra = agentcore | agentcore-ecr

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu MCP Server, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<mcp-server-name>

        • <mcp-server-name>.ts CDK construct for deploying your MCP Server

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<mcp-server-name>

        • <mcp-server-name>.tf Module for deploying your MCP Server
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
    • Directorioagent-core-code (when infra is agentcore)

      • runtime.tf Packages your MCP Server’s code and delegates to agent-core
    • Directorioagent-core-container (when infra is agentcore-ecr)

      • runtime.tf Builds and publishes your MCP Server’s image and delegates to agent-core

infra = none

Si seleccionaste none para infra, no se generan construcciones de CDK ni módulos de Terraform: el servidor MCP está configurado solo para uso local de STDIO / HTTP. La opción auth se ignora en este modo ya que no hay un punto final alojado para autenticar.

Arquitectura

AgentCore Runtime

Cuando se despliega en Bedrock AgentCore Runtime, el código de tu servidor se empaqueta como un zip y se ejecuta en el runtime administrado de AgentCore. Los asistentes de IA invocan el endpoint del plano de datos de AgentCore Runtime, que reenvía las llamadas tools/* y resources/* a tu servidor a través del transporte HTTP transmisible.

Loading the diagram…

AgentCore Runtime (container)

Con infra: agentcore-ecr, el servidor MCP se construye en una imagen de contenedor, se envía a Amazon ECR y se ejecuta en AgentCore Runtime. Esto te da control a nivel de sistema operativo sobre el entorno de ejecución, a costa de un ciclo de construcción y despliegue más largo que el empaquetado zip anterior.

Loading the diagram…

None (local only)

Con infra: none, no se genera infraestructura de AWS. El servidor MCP está configurado solo para transportes STDIO y HTTP locales, y es consumido por asistentes de IA que se ejecutan en la misma máquina.

Loading the diagram…

Trabajar con tu Servidor MCP

Agregar Herramientas

Las herramientas son funciones que el asistente de IA puede llamar para realizar acciones. El servidor MCP de Python utiliza la biblioteca MCP Python SDK (FastMCP), que proporciona un enfoque simple basado en decoradores para definir herramientas.

Puedes agregar nuevas herramientas en el archivo 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}"

La biblioteca FastMCP maneja automáticamente:

• Validación de tipos basada en las sugerencias de tipo de tu función
• Generación de esquema JSON para el protocolo MCP
• Manejo de errores y formato de respuesta

Agregar Recursos

Los recursos proporcionan contexto al asistente de IA. Puedes agregar recursos usando el decorador @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}"

Configurar con Asistentes de IA

Archivos de Configuración

La mayoría de los asistentes de IA que soportan MCP utilizan un enfoque de configuración similar. Necesitarás crear o actualizar un archivo de configuración con los detalles de tu servidor MCP:

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

Resolución de Rutas

Si recibes un error como ENOENT uv al conectarte a tu servidor, es posible que necesites especificar la ruta completa a uv, la cual puedes obtener ejecutando which uv en tu terminal.

Configuración Específica del Asistente

Por favor, consulta la siguiente documentación para configurar MCP con Asistentes de IA específicos:

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

Configuración del Espacio de Trabajo

Algunos Asistentes de IA, como Kiro, te permiten especificar la configuración del servidor MCP a nivel de espacio de trabajo, lo cual es particularmente útil para definir los servidores MCP relevantes para un proyecto en particular.

Ejecutar tu Servidor MCP

Desarrollo Local

Para ejecutar tu servidor MCP (y todo lo conectado a él, como una base de datos local) localmente, usa el objetivo dev del proyecto:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Si has agregado múltiples componentes a tu proyecto (servidores MCP, agentes, etc.), esto los inicia todos. Para ejecutar solo este servidor MCP, apunta a su objetivo <your-server-name>-dev:

pnpm

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

yarn

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

npm

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

bun

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

Inspector

El generador configura un objetivo llamado <your-server-name>-inspect, que inicia tu servidor MCP localmente (a través del objetivo <your-server-name>-dev, incluyendo cualquier dependencia conectada como una base de datos local) y lanza el MCP Inspector preconfigurado para conectarse a él a través del transporte HTTP transmisible.

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

Esto iniciará el inspector en http://localhost:6274. Comienza haciendo clic en el botón “Connect”.

Consejo

Para inspeccionar el servidor usando transporte STDIO en su lugar, usa el objetivo <your-server-name>-inspect-stdio, que lanza el inspector contra una instancia STDIO de tu servidor.

STDIO

La forma más fácil de probar y usar un servidor MCP es usando el inspector o configurándolo con un asistente de IA (como se indicó anteriormente).

Sin embargo, puedes ejecutar tu servidor con transporte STDIO directamente usando el objetivo <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

Este comando usa uv run para ejecutar tu servidor MCP con transporte STDIO.

HTTP Transmisible

Si deseas ejecutar tu servidor MCP localmente usando transporte HTTP transmisible, puedes usar el objetivo <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

Este comando usa uv run uvicorn --reload para ejecutar tu servidor MCP con transporte HTTP, y se reinicia automáticamente cuando los archivos cambian.

Cada servidor MCP tiene asignado su propio puerto, comenzando en 8000, por lo que varios servidores pueden ejecutarse uno al lado del otro en el mismo espacio de trabajo. Lee el puerto en el que escucha tu servidor desde su objetivo <your-server-name>-serve en project.json.

infra = agentcore | agentcore-ecr

Desplegar tu Servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste agentcore o agentcore-ecr para infra, se genera la infraestructura relevante de CDK o Terraform que puedes usar para desplegar tu servidor MCP en Amazon Bedrock AgentCore Runtime.

CDK

Se genera un constructo CDK para tu servidor MCP, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>McpServer por defecto.

Puedes usar este constructo CDK en una aplicación 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');
  }
}

Constructo CDK

Este constructo usa el módulo aws-cdk-lib/aws-bedrockagentcore.

Terraform

Se genera un módulo Terraform para ti, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>-mcp-server por defecto.

Pasa las salidas del módulo compartido runtime_config_appconfig al módulo del servidor MCP, junto con el almacén de artefactos compartido que usa su empaquetado. Bajo el empaquetado predeterminado agentcore, el código del servidor se almacena en el bucket de activos compartido, así que instancia el módulo core/asset-bucket una vez por despliegue, como ya lo hacen los módulos Lambda y API:

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
}

Bajo agentcore-ecr la imagen del servidor se publica en el registro de activos compartido en su lugar, así que pasa las salidas de core/asset-ecr en lugar de las del bucket. Un registro sirve a todos los contenedores en el espacio de trabajo, por lo que ningún servidor MCP necesita un repositorio propio:

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
}

Autenticación

El generador proporciona una opción auth para configurar la autenticación de tu servidor MCP. Puedes elegir entre autenticación IAM (predeterminada) o Cognito al generar tu servidor MCP.

IAM

Por defecto, tu servidor MCP estará asegurado usando autenticación IAM, simplemente despliégalo sin ningún argumento:

CDK

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

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

Puedes otorgar acceso para invocar tu servidor MCP en Bedrock AgentCore Runtime usando el método grantInvokeAccess. Por ejemplo, es posible que desees que un agente generado con el generador py#agent llame a tu servidor 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);
  }
}

Terraform

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

Para otorgar acceso para invocar tu servidor MCP, necesitarás agregar una política como la siguiente, haciendo referencia a la salida 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}/*"
  ]
}

Autenticación con Cognito

Cuando seleccionas autenticación Cognito, el generador configura el servidor MCP para usar Cognito para la autenticación.

CDK

El constructo generado acepta una prop identity que configura la autenticación con 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,
    });
  }
}

El constructo UserIdentity puede ser generado usando el generador ts#website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

Terraform

El módulo generado acepta las variables user_pool_id y user_pool_client_ids para la autenticación con 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]
}

Proveedores OIDC Personalizados

Si requieres autenticación JWT personalizada con un proveedor OIDC que no sea Cognito, puedes modificar el constructo CDK generado o el módulo Terraform para tu servidor MCP directamente. Ten en cuenta que el generador de conexiones solo admitirá autenticación IAM o Cognito.

Mejores Prácticas de Seguridad

Al implementar la lógica de negocio de tu servidor MCP, revisa las mejores prácticas de seguridad de Bedrock AgentCore Runtime.

Objetivos de Bundle y Docker

Para construir tu servidor MCP para Bedrock AgentCore Runtime, se agrega un objetivo bundle a tu proyecto, que:

• Exporta tus dependencias de Python a un archivo requirements.txt usando uv export
• Instala dependencias para la plataforma de destino (aarch64-manylinux_2_28) usando uv pip install

infra = agentcore

También se agrega un objetivo <your-server-name>-package, que ensambla el paquete de código desplegable: el paquete de dependencias aarch64, tu árbol de módulos de Python y un punto de entrada raíz main.py. La infraestructura generada sube este directorio como un .zip — a través de AgentRuntimeArtifact.fromCodeAsset bajo CDK, o archivado en el bucket de activos compartidos bajo Terraform.

infra = agentcore-ecr

También se agrega un objetivo docker específico para tu servidor MCP, que copia el Dockerfile y los artefactos empaquetados en un directorio de contexto de docker. Esto coloca el Dockerfile junto con la salida construida, permitiendo que CDK construya la imagen de Docker directamente usando AgentRuntimeArtifact.fromAsset.

Escaneo de Imágenes

La imagen Docker construida para este proyecto puede ser escaneada en busca de vulnerabilidades usando Trivy, ejecutándose desde la imagen Trivy alojada en ECR.

Se agrega un target trivy a tu proyecto que escanea la imagen construida y termina con código distinto de cero si se encuentra alguna vulnerabilidad de severidad HIGH o CRITICAL. El Dockerfile generado usa una imagen base sin vulnerabilidades corregibles conocidas de estas severidades al momento de la generación, y actualiza las herramientas incluidas (como npm) para mantenerlo así.

El escaneo usa el mismo motor de contenedores que tu construcción de imagen (docker o finch), por lo que no se requieren herramientas adicionales. El escaneo no se almacena en caché, ya que la imagen que lee vive en el motor de contenedores en lugar de en el disco — por lo que siempre escanea la imagen real, y falla ruidosamente en lugar de reportar un pase en caché para una imagen que ya no está allí. Por lo tanto, cada ejecución toma decenas de segundos por imagen y actualiza la base de datos de vulnerabilidades de Trivy, por lo que necesita acceso a la red. El script raíz trivy proporcionado escanea cada imagen en el workspace:

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Ejecuta Trivy en CI

El escaneo intencionalmente no está conectado a build ya que esto puede introducir fricción innecesaria al iterar durante el desarrollo, ya que la base de datos de vulnerabilidades de Trivy se actualiza continuamente con nuevos CVEs.

En su lugar, recomendamos ejecutar el comando anterior como un paso dedicado en tu pipeline de CI antes del despliegue a entornos de producción.

Las vulnerabilidades no corregibles son ignoradas

El escaneo se ejecuta con --ignore-unfixed, por lo que las vulnerabilidades sin una corrección disponible no fallan la construcción, ya que no pueden ser accionadas actualizando las herramientas en tu Dockerfile — no se reportan en la salida del escaneo de la construcción. A medida que se divulgan nuevas vulnerabilidades, el resultado de los escaneos puede cambiar con el tiempo, así que revisa la imagen periódicamente ejecutando trivy image <your-image> sin la bandera, y reconstruye contra una imagen base más nueva (o agrega pasos de contenedor para aplicar parches disponibles) una vez que se publique una corrección.

Suprimiendo Hallazgos de Trivy

Puede haber instancias en las que desees suprimir una vulnerabilidad específica, por ejemplo cuando aún no hay una corrección disponible y has evaluado el riesgo como aceptable.

Agrega el ID de vulnerabilidad (uno por línea) al archivo .trivyignore en la raíz de tu proyecto (es decir, junto a tu project.json):

.trivyignore

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

Para más detalles sobre el filtrado de hallazgos, consulta la documentación de filtrado de Trivy.

Observabilidad

Tu servidor MCP está configurado automáticamente con observabilidad utilizando AWS Distro for Open Telemetry (ADOT), mediante la configuración de auto-instrumentación en tu Dockerfile.

Puedes encontrar trazas en la consola de AWS CloudWatch, seleccionando “GenAI Observability” en el menú. Ten en cuenta que para que las trazas se completen necesitarás habilitar Transaction Search.

Para más detalles, consulta la documentación de AgentCore sobre observabilidad.

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

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