Serveur MCP Python

Générez un serveur Python Model Context Protocol (MCP) pour fournir du contexte aux grands modèles de langage (LLM), et déployez-le optionnellement sur Amazon Bedrock AgentCore.

Qu’est-ce que MCP ?

Le Model Context Protocol (MCP) est un standard ouvert qui permet aux assistants IA d’interagir avec des outils et des ressources externes. Il fournit une manière cohérente pour les LLM de :

• Exécuter des outils (fonctions) qui effectuent des actions ou récupèrent des informations
• Accéder à des ressources qui fournissent du contexte ou des données

Utilisation

Générer un serveur MCP

Vous pouvez générer un serveur MCP Python de deux manières :

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - py#mcp-server
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Prérequis du projet

Utilisez d’abord le générateur py#project pour créer un projet auquel ajouter votre serveur MCP.

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter un serveur MCP
name	string	-	Le nom de votre serveur MCP (par défaut : mcp-server)
auth	iam | cognito	iam	La méthode utilisée pour s'authentifier auprès de votre serveur MCP. Applicable uniquement lorsque infra est défini (ignoré lorsque infra est none).
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.
infra	agentcore | none	agentcore	Le type d'infrastructure pour héberger votre serveur MCP. Sélectionnez none pour aucun hébergement.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur ajoutera les fichiers suivants à votre projet Python existant :

• Répertoireyour-project/

  • Répertoireyour_module/

    • Répertoiremcp_server/ (ou nom personnalisé si spécifié)

      • __init__.py Initialisation du package Python
      • server.py Définition principale du serveur avec des outils et ressources d’exemple
      • stdio.py Point d’entrée pour le transport STDIO, utile pour les serveurs MCP locaux simples
      • http.py Point d’entrée pour le transport HTTP streamable, utile pour héberger votre serveur MCP
      • Dockerfile Point d’entrée pour héberger votre serveur MCP (exclu lorsque infra est défini sur None)
  • pyproject.toml Mis à jour avec les dépendances MCP
  • project.json Mis à jour avec les cibles de service du serveur MCP

Infrastructure

infra = agentcore

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app

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

Projet généré

Ce projet est généré en utilisant le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Répertoirecore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projet généré

Ce projet est généré en utilisant le générateur terraform#project et configure donc les mêmes cibles de build.

Pour déployer votre serveur MCP, les fichiers suivants sont générés :

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<mcp-server-name>

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

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<mcp-server-name>

        • <mcp-server-name>.tf Module for deploying your MCP Server
  • Répertoirecore

    • Répertoireagent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

infra = none

Si vous avez sélectionné none pour infra, aucun construct CDK ou module Terraform n’est généré — le serveur MCP est configuré uniquement pour une utilisation locale STDIO / HTTP. L’option auth est ignorée dans ce mode car il n’y a pas de point de terminaison hébergé à authentifier.

Architecture

Bedrock AgentCore Runtime

Lorsqu’il est déployé sur Bedrock AgentCore Runtime, le serveur MCP est construit dans une image de conteneur, poussé vers Amazon ECR et exécuté dans AgentCore Runtime. Les assistants IA invoquent le point de terminaison du plan de données AgentCore Runtime, qui transmet les appels tools/* et resources/* à votre serveur via le transport HTTP diffusable.

None (local only)

Avec infra: none, aucune infrastructure AWS n’est générée. Le serveur MCP est configuré uniquement pour les transports STDIO et HTTP locaux, et est consommé par des assistants IA s’exécutant sur la même machine.

Travailler avec votre serveur MCP

Ajouter des outils

Les outils sont des fonctions que l’assistant IA peut appeler pour effectuer des actions. Le serveur MCP Python utilise la bibliothèque MCP Python SDK (FastMCP), qui fournit une approche simple basée sur des décorateurs pour définir des outils.

Vous pouvez ajouter de nouveaux outils dans le fichier 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 bibliothèque FastMCP gère automatiquement :

• La validation de type basée sur les annotations de type de votre fonction
• La génération de schéma JSON pour le protocole MCP
• La gestion des erreurs et le formatage des réponses

Ajouter des ressources

Les ressources fournissent du contexte à l’assistant IA. Vous pouvez ajouter des ressources en utilisant le décorateur @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}"

Configuration avec les assistants IA

Fichiers de configuration

La plupart des assistants IA qui prennent en charge MCP utilisent une approche de configuration similaire. Vous devrez créer ou mettre à jour un fichier de configuration avec les détails de votre serveur MCP :

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

Résolution de chemin

Si vous recevez une erreur telle que ENOENT uv lors de la connexion à votre serveur, vous devrez peut-être spécifier le chemin complet vers uv, que vous pouvez obtenir en exécutant which uv dans votre terminal.

Configuration spécifique à l’assistant

Veuillez vous référer à la documentation suivante pour configurer MCP avec des assistants IA spécifiques :

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

Configuration de l’espace de travail

Certains assistants IA, tels que Kiro, vous permettent de spécifier une configuration de serveur MCP au niveau de l’espace de travail, ce qui est particulièrement utile pour définir les serveurs MCP pertinents pour un projet particulier.

Exécuter votre serveur MCP

Développement local

Pour exécuter votre serveur MCP (et tout ce qui y est connecté, comme une base de données locale) localement, utilisez la cible dev du projet :

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 vous avez ajouté plusieurs composants à votre projet (serveurs MCP, agents, etc.), cela les démarre tous. Pour exécuter uniquement ce serveur MCP, ciblez sa cible <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

Inspecteur

Le générateur configure une cible nommée <your-server-name>-inspect, qui démarre votre serveur MCP localement (via la cible <your-server-name>-dev, y compris toutes les dépendances connectées comme une base de données locale) et lance l’inspecteur MCP préconfiguré pour s’y connecter via le transport HTTP streamable.

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

Cela démarrera l’inspecteur sur http://localhost:6274. Commencez en cliquant sur le bouton “Connect”.

Astuce

Pour inspecter le serveur en utilisant le transport STDIO à la place, utilisez la cible <your-server-name>-inspect-stdio, qui lance l’inspecteur contre une instance STDIO de votre serveur.

STDIO

La façon la plus simple de tester et d’utiliser un serveur MCP est d’utiliser l’inspecteur ou de le configurer avec un assistant IA (comme ci-dessus).

Vous pouvez cependant exécuter votre serveur avec le transport STDIO directement en utilisant la cible <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

Cette commande utilise uv run pour exécuter votre serveur MCP avec le transport STDIO.

HTTP streamable

Si vous souhaitez exécuter votre serveur MCP localement en utilisant le transport HTTP streamable, vous pouvez utiliser la cible <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

Cette commande utilise uv run uvicorn --reload pour exécuter votre serveur MCP avec le transport HTTP (généralement sur le port 8000), et redémarre automatiquement lorsque les fichiers changent.

infra = agentcore

Déployer votre serveur MCP sur Bedrock AgentCore Runtime

Infrastructure as Code

Si vous avez sélectionné agentcore pour infra, l’infrastructure CDK ou Terraform pertinente est générée et vous pouvez l’utiliser pour déployer votre serveur MCP sur Amazon Bedrock AgentCore Runtime.

CDK

Un construct CDK est généré pour votre serveur MCP, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>McpServer par défaut.

Vous pouvez utiliser ce construct CDK dans une application 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');
  }
}

CDK Construct

Ce construct utilise le module aws-cdk-lib/aws-bedrockagentcore.

Terraform

Un module Terraform est généré pour vous, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>-mcp-server par défaut.

Passez les sorties du module partagé runtime_config_appconfig dans le module du serveur 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 requis

Docker est requis pour construire et déployer votre serveur MCP. Assurez-vous d’avoir installé et lancé Docker pour éviter des erreurs telles que :

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

Authentification

Le générateur fournit une option auth pour configurer l’authentification de votre serveur MCP. Vous pouvez choisir entre l’authentification IAM (par défaut) ou Cognito lors de la génération de votre serveur MCP.

IAM

Par défaut, votre serveur MCP sera sécurisé à l’aide de l’authentification IAM, déployez-le simplement sans aucun argument :

CDK

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

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

Vous pouvez accorder l’accès pour invoquer votre serveur MCP sur Bedrock AgentCore Runtime en utilisant la méthode grantInvokeAccess. Par exemple, vous pouvez souhaiter qu’un agent généré avec le générateur py#agent appelle votre serveur 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
}

Pour accorder l’accès pour invoquer votre serveur MCP, vous devrez ajouter une politique telle que la suivante, en référençant la sortie 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}/*"
  ]
}

Authentification Cognito

Lorsque vous sélectionnez l’authentification Cognito, le générateur configure le serveur MCP pour utiliser Cognito pour l’authentification.

CDK

Le construct généré accepte une prop identity qui configure l’authentification 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,
    });
  }
}

Le construct UserIdentity peut être généré en utilisant le générateur ts#website#auth, ou vous pouvez créer vos propres UserPool et UserPoolClient CDK.

Terraform

Le module généré accepte les variables user_pool_id et user_pool_client_ids pour l’authentification 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]
}

Fournisseurs OIDC personnalisés

Si vous avez besoin d’une authentification JWT personnalisée avec un fournisseur OIDC non-Cognito, vous pouvez modifier directement le construct CDK généré ou le module Terraform pour votre serveur MCP. Notez que le générateur de connexion ne prendra en charge que l’authentification IAM ou Cognito.

Bonnes pratiques de sécurité

Lors de l’implémentation de la logique métier de votre serveur MCP, consultez les bonnes pratiques de sécurité Bedrock AgentCore Runtime.

Cibles Bundle et Docker

Pour construire votre serveur MCP pour Bedrock AgentCore Runtime, une cible bundle est ajoutée à votre projet, qui :

• Exporte vos dépendances Python vers un fichier requirements.txt en utilisant uv export
• Installe les dépendances pour la plateforme cible (aarch64-manylinux_2_28) en utilisant uv pip install

Une cible docker spécifique à votre serveur MCP est également ajoutée, qui copie le Dockerfile et les artefacts empaquetés dans un répertoire de contexte docker. Cela co-localise le Dockerfile avec la sortie construite, permettant à CDK de construire l’image Docker directement en utilisant AgentRuntimeArtifact.fromAsset.

Analyse d’image

L’image Docker construite pour ce projet peut être analysée pour détecter les vulnérabilités à l’aide de Trivy, exécuté depuis l’image Trivy hébergée sur ECR.

Une cible trivy est ajoutée à votre projet qui analyse l’image construite et se termine avec un code non nul si une vulnérabilité de gravité HIGH ou CRITICAL est trouvée. Le Dockerfile généré utilise une image de base sans vulnérabilité corrigeable connue de ces gravités au moment de la génération, et met à niveau les outils fournis (tels que npm) pour maintenir cet état.

L’analyse utilise le même moteur de conteneur que votre construction d’image (docker ou finch), donc aucun outillage supplémentaire n’est requis. Étant donné que l’analyse n’est réexécutée que lorsque l’image change, une image inchangée n’est pas réanalysée. Le script racine trivy fourni analyse chaque image dans l’espace de travail :

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Exécuter Trivy en CI

L’analyse n’est intentionnellement pas intégrée à build car cela peut introduire des frictions inutiles lors de l’itération pendant le développement, car la base de données de vulnérabilités de Trivy est continuellement mise à jour avec de nouveaux CVE.

Nous recommandons plutôt d’exécuter la commande ci-dessus comme une étape dédiée dans votre pipeline CI avant le déploiement vers les environnements de production.

Les vulnérabilités non corrigeables sont ignorées

L’analyse s’exécute avec --ignore-unfixed, donc les vulnérabilités sans correctif disponible ne font pas échouer la construction, car elles ne peuvent pas être traitées en mettant à niveau les outils dans votre Dockerfile — elles ne sont pas signalées dans la sortie d’analyse de la construction. Au fur et à mesure que de nouvelles vulnérabilités sont divulguées, le résultat des analyses peut changer au fil du temps, alors examinez l’image périodiquement en exécutant trivy image <your-image> sans le flag, et reconstruisez avec une image de base plus récente (ou ajoutez des étapes de conteneur pour appliquer les correctifs disponibles) une fois qu’un correctif est publié.

Suppression des résultats Trivy

Il peut y avoir des cas où vous souhaitez supprimer une vulnérabilité spécifique, par exemple lorsqu’aucun correctif n’est encore disponible et que vous avez évalué le risque comme acceptable.

Ajoutez l’ID de vulnérabilité (un par ligne) au fichier .trivyignore à la racine de votre projet (c’est-à-dire à côté de votre project.json) :

.trivyignore

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

Pour plus de détails sur le filtrage des résultats, consultez la documentation de filtrage Trivy.

Observabilité

Votre serveur MCP est automatiquement configuré avec l’observabilité en utilisant AWS Distro for Open Telemetry (ADOT), en configurant l’auto-instrumentation dans votre Dockerfile.

Vous pouvez trouver les traces dans la console AWS CloudWatch, en sélectionnant « GenAI Observability » dans le menu. Notez que pour que les traces soient remplies, vous devrez activer Transaction Search.

Pour plus de détails, consultez la documentation AgentCore sur l’observabilité.

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre espace de travail. Les connexions suivantes impliquent ce projet :

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