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:

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

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

Requisito Previo del Proyecto

Primero usa el generador py#project para crear un proyecto al que agregar tu 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 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 Punto de entrada para alojar tu servidor MCP (excluido cuando infra está configurado en None)
  • pyproject.toml Actualizado con dependencias de 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 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

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

Bedrock AgentCore Runtime

Cuando se despliega 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 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 (típicamente en el puerto 8000), y se reinicia automáticamente cuando los archivos cambian.

infra = agentcore

Desplegar tu Servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste agentcore 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:

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

Docker es necesario para construir y desplegar tu servidor MCP. Asegúrate de haber instalado e iniciado Docker 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 (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

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. Dado que el escaneo solo se vuelve a ejecutar cuando la imagen cambia, una imagen sin cambios no se vuelve a escanear. 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