Servidor MCP de Python

Genere un servidor de Model Context Protocol (MCP) de Python para proporcionar contexto a Modelos de Lenguaje Grande (LLMs), y opcionalmente despliéguelo 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

Puede generar un servidor MCP de Python de dos maneras:

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

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

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

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

Requisito Previo del Proyecto

Primero use el generador py#project para crear un proyecto al cual agregar su servidor MCP.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar un servidor MCP
name	string	-	El nombre de tu servidor MCP (predeterminado: mcp-server)
auth	iam | cognito	iam	El método utilizado para autenticar con tu servidor MCP. Solo aplicable cuando infra está configurado (se ignora cuando infra es none).
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
infra	agentcore | none	agentcore	El tipo de infraestructura para alojar tu servidor MCP. Selecciona none para no tener alojamiento.
preferInstallDependencies	boolean	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 su proyecto de Python existente:

• Directorioyour-project/

  • Directorioyour_module/

    • Directoriomcp_server/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete 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 su servidor MCP
      • Dockerfile Punto de entrada para alojar su servidor MCP (excluido cuando infra está configurado en None)
  • pyproject.toml Actualizado con dependencias MCP
  • project.json Actualizado con objetivos de servicio del servidor MCP

Infraestructura

infra = agentcore

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

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

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

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

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

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<project-name>

        • <project-name>.ts Constructo CDK para implementar tu MCP Server
        • Dockerfile Archivo Docker passthrough utilizado por el constructo CDK

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<project-name>

        • <project-name>.tf Módulo para implementar tu MCP Server
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Módulo genérico para implementar en Bedrock AgentCore Runtime

infra = none

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

Arquitectura

Bedrock AgentCore Runtime

Cuando se implementa en Bedrock AgentCore Runtime, el servidor MCP se construye en una imagen de contenedor, se envía a Amazon ECR y se ejecuta en AgentCore Runtime. 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.

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.

Trabajar con su 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.

Puede 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 anotaciones de tipo de su 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. Puede 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 admiten MCP utilizan un enfoque de configuración similar. Deberá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, posiblemente necesites especificar la ruta completa a uv, la cual puedes obtener ejecutando which uv en tu terminal.

Configuración específica del asistente

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 workspace

Algunos asistentes de IA, como Amazon Q Developer, permiten especificar configuraciones de 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 su Servidor MCP

Desarrollo Local

Para ejecutar su servidor MCP (y todo lo conectado a él, como una base de datos local) localmente, use 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 ha agregado múltiples componentes a su proyecto (servidores MCP, agentes, etc.), esto los inicia todos. Para ejecutar solo este servidor MCP, apunte 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 su 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 de 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. Comience haciendo clic en el botón “Connect”.

Consejo

Para inspeccionar el servidor usando transporte STDIO en su lugar, use el objetivo <your-server-name>-inspect-stdio, que lanza el inspector contra una instancia STDIO de su 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, puede ejecutar su 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 su servidor MCP con transporte STDIO.

Streamable HTTP

Si desea ejecutar su servidor MCP localmente usando transporte HTTP transmisible, puede 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 su servidor MCP con transporte HTTP (típicamente en el puerto 8000), y se reinicia automáticamente cuando los archivos cambian.

infra = agentcore

Desplegar su Servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste agentcore para infra, se generará la infraestructura correspondiente 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) {
    // Agrega el servidor MCP a tu stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Constructo CDK

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

Terraform

Se genera un módulo de Terraform para tu proyecto, 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:

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
}

Docker requerido

Se requiere Docker para construir y desplegar tu servidor MCP. Asegúrate de tener Docker instalado y en ejecución para evitar errores como:

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

Autenticación

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

IAM

Por defecto, tu servidor MCP estará protegido con autenticación IAM. Simplemente despliégalo sin argumentos adicionales:

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, quizás quieras que un agente generado con el generador py#agent pueda llamar 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

# Servidor MCP
module "my_project_mcp_server" {
  # Ruta relativa al módulo generado en el proyecto common/terraform
  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 al 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}/*"
  ]
}

Autenticación 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 propiedad identity que configura la autenticación 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 generarse 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 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 directamente el constructo CDK generado o el módulo Terraform para tu servidor MCP. 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 su servidor MCP para Bedrock AgentCore Runtime, se agrega un objetivo bundle a su proyecto, que:

• Exporta sus 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

También se agrega un objetivo docker específico para su 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 se escanea en busca de vulnerabilidades como parte de la construcción 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 falla la construcción si se encuentra alguna vulnerabilidad de severidad HIGH o CRITICAL. El Dockerfile generado utiliza 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 utiliza el mismo motor de contenedores que tu construcción de imagen (docker o finch), por lo que no se requieren herramientas adicionales. Dado que el escaneo solo se vuelve a ejecutar cuando la imagen cambia, una imagen sin cambios no se vuelve a escanear.

Las vulnerabilidades no corregibles se ignoran

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 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 reciente (o agrega pasos de contenedor para aplicar parches disponibles) una vez que se publique una corrección.

Supresión de Hallazgos de Trivy

Puede haber casos en los 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 se configura automáticamente con observabilidad utilizando la 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 rellenen, deberá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 workspace. Las siguientes conexiones involucran este proyecto:

TypeScript Agent a MCPConecta un TypeScript Agent a un servidor MCP

Python Agent a MCPConecta un Python Agent a un servidor MCP

Python MCP Server a Python DynamoDBConecta un Python MCP Server a una tabla DynamoDB

AgentCore Gateway a Servidor MCPAgrega un servidor MCP detrás de un AgentCore Gateway