Servidor Python MCP

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

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a 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 proveen contexto o datos

Uso

Generar un servidor MCP

Puedes generar un servidor MCP en Python de dos formas:

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

Consejo

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	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	CDK	The preferred IaC provider

Salida del generador

El generador añadirá los siguientes archivos a tu proyecto Python existente:

• Directoryyour-project/

  • Directoryyour_module/

    • Directorymcp_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 transmitible, útil para alojar tu servidor MCP
      • Dockerfile Punto de entrada para alojar tu servidor MCP (excluido cuando computeType se establece en None)
  • pyproject.toml Actualizado con dependencias MCP
  • project.json Actualizado con objetivos de servicio del servidor MCP

Infraestructura

Nota

Si seleccionaste None para computeType, el generador no proporcionará ningún Infrastructure as Code.

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

• Directorypackages/common/constructs

  • Directorysrc

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

      • …
    • Directorycore/ 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

Nota

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

Terraform

• Directorypackages/common/terraform

  • Directorysrc

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

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

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

Nota

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

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

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

    • Directoryagent-core

      • runtime.ts Constructo CDK genérico para implementar en Bedrock AgentCore Runtime

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

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

    • Directoryagent-core

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

Trabajando con tu servidor MCP

Añadiendo herramientas

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

Puedes añadir nuevas herramientas en el archivo server.py:

@mcp.tool(description="Descripción de tu herramienta")
def your_tool_name(param1: str, param2: int) -> str:
    """Implementación de la herramienta con sugerencias de tipo"""
    # Tu lógica de herramienta aquí
    return f"Resultado: {param1} con {param2}"

La biblioteca FastMCP maneja automáticamente:

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

Añadiendo recursos

Los recursos proveen contexto al asistente de IA. Puedes añadir recursos usando el decorador @mcp.resource:

@mcp.resource("example://static-resource", description="Ejemplo de recurso estático")
def static_resource() -> str:
    """Retorna contenido estático"""
    return "Este es contenido estático que provee contexto a la IA"

@mcp.resource("dynamic://resource/{item_id}", description="Ejemplo de recurso dinámico")
def dynamic_resource(item_id: str) -> str:
    """Retorna contenido dinámico basado en parámetros"""
    # Obtiene datos basados en item_id
    data = fetch_data_for_item(item_id)
    return f"Contenido dinámico para {item_id}: {data}"

Configuración 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"
      }
    }
  }
}

Precaución

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:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Consejo

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.

Ejecutando tu servidor MCP

Inspector

El generador configura un objetivo llamado <your-server-name>-inspect, que inicia el MCP Inspector con la configuración para conectarse a tu servidor MCP usando transporte 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

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

STDIO

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

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

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

HTTP transmitible

Si prefieres ejecutar tu servidor MCP localmente usando transporte HTTP transmitible, puedes usar el objetivo <your-server-name>-serve-http.

pnpm

pnpm nx run your-project:your-server-name-serve-http

yarn

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

npm

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

bun

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

Este comando usa uv run para ejecutar tu servidor MCP con transporte HTTP, típicamente en el puerto 8000.

Implementación de tu servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se generará 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 de CDK para tu proyecto, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>McpServer por defecto.

Puedes usar este constructo de 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 pila
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

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.

Puedes usar este módulo de Terraform en un proyecto 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"
}

Precaución

Docker es requerido 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

IAM

Por defecto, tu servidor MCP estará protegido usando 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 MCP en Bedrock AgentCore Runtime usando el método grantInvoke. Por ejemplo, quizás quieras que un agente generado con el generador py#strands-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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

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

Para otorgar acceso para invocar tu agente, necesitarás agregar una política como la siguiente, referenciando el 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 JWT con Cognito

El siguiente ejemplo demuestra cómo configurar autenticación Cognito para tu agente.

CDK

Para configurar autenticación JWT, puedes pasar la propiedad authorizerConfiguration a tu constructo de servidor MCP. Este ejemplo configura un grupo de usuarios y cliente Cognito para proteger el servidor MCP:

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

Para configurar autenticación JWT, puedes editar tu módulo de Servidor MCP para configurar la variable customJWTAuthorizer de la siguiente manera:

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

  # Reemplaza con tus IDs de grupo de usuarios y cliente o expón como variables
  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
}

Objetivos de bundle y Docker

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

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

También se añade un objetivo docker específico para tu servidor MCP, que:

• Construye una imagen Docker desde el Dockerfile que ejecuta tu servidor MCP en el puerto 8000, según el contrato de protocolo MCP

Consejo

La imagen Docker se construye usando una etiqueta (por ejemplo my-scope-my-project-mcp-server:latest), que es referenciada por tu infraestructura CDK o Terraform, permitiendo que tu Dockerfile esté ubicado junto a tu proyecto de servidor MCP.

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.