Serveur Python MCP

Générez un serveur Python Model Context Protocol (MCP) pour fournir du contexte aux Grands Modèles de Langage (LLMs), avec option de déploiement sur Amazon Bedrock AgentCore.

Qu’est-ce que le MCP ?

Le Model Context Protocol (MCP) est un standard ouvert permettant aux assistants IA d’interagir avec des outils et ressources externes. Il fournit une méthode cohérente pour que les LLMs puissent :

• Exécuter des outils (fonctions) réalisant des actions ou récupérant des informations
• Accéder à des ressources fournissant du contexte ou des données

Utilisation

Générer un serveur MCP

Vous pouvez générer un serveur MCP Python de deux façons :

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

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

Prérequis du projet

Utilisez d’abord le py#project pour créer un projet avant d’y ajouter votre serveur MCP.

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter un serveur MCP
computeType	string	BedrockAgentCoreRuntime	Le type de calcul pour héberger votre serveur MCP. Sélectionnez None pour aucun hébergement.
name	string	-	Le nom de votre serveur MCP (par défaut : mcp-server)
auth	string	IAM	La méthode utilisée pour s'authentifier auprès de votre serveur MCP. Choisissez entre IAM (par défaut) ou Cognito.
iacProvider	string	Inherit	Le fournisseur IaC préféré. Par défaut, ceci est hérité de votre sélection initiale.

Résultat 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 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 l’hébergement du serveur MCP
      • Dockerfile Point d’entrée pour l’hébergement du serveur MCP (exclu si computeType est None)
  • pyproject.toml Mis à jour avec les dépendances MCP
  • project.json Mis à jour avec les cibles de service du serveur MCP

Infrastructure

Déploiement serverless

Si vous avez sélectionné None pour computeType, le générateur ne fournira aucune infrastructure-as-code.

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

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

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

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

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

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

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

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

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

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<project-name>

        • <project-name>.ts Construct CDK pour déployer votre serveur MCP
        • Dockerfile Fichier Docker transmis directement utilisé par le construct CDK

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<project-name>

        • <project-name>.tf Module pour déployer votre serveur MCP
  • Répertoirecore

    • Répertoireagent-core

      • runtime.tf Module générique pour le déploiement sur Bedrock AgentCore Runtime

Utilisation de votre serveur MCP

Ajout d’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 propose une approche 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="Description de votre outil")
def your_tool_name(param1: str, param2: int) -> str:
    """Implémentation de l'outil avec annotations de type"""
    # Logique de l'outil ici
    return f"Résultat : {param1} avec {param2}"

La bibliothèque FastMCP gère automatiquement :

• La validation des types selon les annotations de votre fonction
• La génération du schéma JSON pour le protocole MCP
• La gestion des erreurs et le formatage des réponses

Ajout de ressources

Les ressources fournissent du contexte à l’assistant IA. Vous pouvez les ajouter avec le décorateur @mcp.resource :

@mcp.resource("example://static-resource", description="Exemple de ressource statique")
def static_resource() -> str:
    """Retourne un contenu statique"""
    return "Ce contenu statique fournit du contexte à l'IA"

@mcp.resource("dynamic://resource/{item_id}", description="Exemple de ressource dynamique")
def dynamic_resource(item_id: str) -> str:
    """Retourne un contenu dynamique basé sur des paramètres"""
    # Récupération des données selon item_id
    data = fetch_data_for_item(item_id)
    return f"Contenu dynamique pour {item_id} : {data}"

Configuration avec les assistants IA

Fichiers de configuration

La plupart des assistants IA compatibles avec 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 rencontrez une erreur comme 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

Consultez la documentation suivante pour configurer MCP avec des assistants IA spécifiques :

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

Configuration du workspace

Certains assistants IA, comme Amazon Q Developer, 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 spécifique.

Exécution de votre serveur MCP

Inspector

Le générateur configure une cible nommée <your-server-name>-inspect qui lance l’MCP Inspector avec la configuration pour se connecter à votre serveur MCP via le transport STDIO.

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

Ceci démarre l’inspector sur http://localhost:6274. Cliquez sur le bouton “Connect” pour commencer.

STDIO

La méthode la plus simple pour tester et utiliser un serveur MCP est d’utiliser l’inspector ou de le configurer avec un assistant IA (comme ci-dessus).

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

Pour exécuter votre serveur MCP localement avec le transport HTTP Streamable, utilisez 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.

Déploiement sur Bedrock AgentCore Runtime

Infrastructure en tant que code

Si vous avez sélectionné BedrockAgentCoreRuntime pour computeType, l’infrastructure CDK ou Terraform correspondante est générée. 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é d’après le name 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) {
    // Ajoutez le serveur MCP à votre stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Construct CDK Alpha

Ce construct utilise le module @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

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

Vous pouvez utiliser ce module Terraform dans un projet Terraform :

# Serveur MCP
module "my_project_mcp_server" {
  # Chemin relatif vers le module généré dans le projet common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Docker requis

Docker est requis pour construire et déployer votre serveur MCP. Assurez-vous qu’il est installé et lancé pour éviter des erreurs comme :

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é via l’authentification IAM. Déployez-le simplement sans arguments :

CDK

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

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

Vous pouvez autoriser l’invocation de votre serveur MCP sur Bedrock AgentCore Runtime avec la méthode grantInvokeAccess. Par exemple, pour permettre à un agent généré avec le générateur py#strands-agent d’appeler 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

# Serveur MCP
module "my_project_mcp_server" {
  # Chemin relatif vers le module généré dans le projet common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Pour autoriser l’invocation de votre serveur MCP, ajoutez une politique IAM faisant référence à 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#react-website#auth, ou vous pouvez créer votre propre 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"

  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 ou le module Terraform généré pour votre serveur MCP. Notez que le générateur de connexion ne prendra en charge que l’authentification IAM ou Cognito.

Cibles Bundle et Docker

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

• Exporte vos dépendances Python dans un fichier requirements.txt via uv export
• Installe les dépendances pour la plateforme cible (aarch64-manylinux2014) via uv pip install

Une cible docker spécifique à votre serveur MCP est aussi ajoutée. Elle :

• Construit une image Docker depuis le Dockerfile exécutant votre serveur MCP sur le port 8000, conformément au contrat de service MCP

Tags d’image Docker

L’image Docker est construite avec un tag (ex: my-scope-my-project-mcp-server:latest), référencé par votre infrastructure CDK/Terraform, permettant à votre Dockerfile de rester colocalisé avec votre projet de serveur MCP.

Observabilité

Votre serveur MCP est automatiquement configuré avec de l’observabilité grâce à 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 peuplées, vous devrez activer Transaction Search.

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