Aller au contenu

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.

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

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

Exécuter ce générateur@aws/nx-plugin:py#mcp-server

pnpm nx g @aws/nx-plugin:py#mcp-server
Composez votre commande6

Requis

infra = agentcore | agentcore-ecr

Options du générateur6 options
projectRequisstring

Le projet auquel ajouter un serveur MCP

authenuminfra = agentcore | agentcore-ecrPar défaut: 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).

iamcognito
iacenumPar défaut: inherit

Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.

inheritcdkterraform
infraenumPar défaut: agentcore

Le type d'infrastructure pour héberger votre serveur MCP. agentcore déploie votre code sous forme de zip vers un runtime géré par AgentCore pour le cycle de build et déploiement le plus rapide. agentcore-ecr construit et héberge une image conteneur à la place, pour un contrôle au niveau de l'OS ou un pipeline de conteneurs établi. Sélectionnez none pour aucun hébergement.

agentcoreagentcore-ecrnone
namestring

Le nom de votre serveur MCP (par défaut : mcp-server)

preferInstallDependenciesbooleanPar défaut: 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.

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 Définition de l’image conteneur (uniquement lorsque infra est agentcore-ecr)
    • pyproject.toml Mis à jour avec les dépendances MCP
    • project.json Mis à jour avec les cibles de service du serveur MCP

L’option infra sélectionne la manière dont votre code est empaqueté et hébergé sur Amazon Bedrock AgentCore Runtime :

  • agentcore (par défaut) utilise le déploiement direct de code : votre code compilé est empaqueté sous forme de .zip, téléchargé vers S3, et exécuté sur un runtime de langage géré par AgentCore. Il n’y a pas d’image de conteneur à construire, pas de dépôt ECR à gérer, et pas d’image à pousser, ce qui permet un cycle de construction et de déploiement nettement plus rapide.
  • agentcore-ecr construit une image de conteneur arm64 à partir d’un Dockerfile fourni et l’héberge depuis le registre partagé core/asset-ecr, aux côtés de tous les autres conteneurs de l’espace de travail. Choisissez cette option lorsque vous avez besoin de contrôler l’image du système d’exploitation — par exemple pour installer des bibliothèques système natives — ou lorsque vous disposez d’un pipeline de conteneurs établi. Cette option fournit également une cible d’analyse d’image Trivy (voir Analyse d’image ci-dessous).
  • none ne génère aucune infrastructure, de sorte que le projet ne peut être exécuté que localement.
infra = agentcore | agentcore-ecr

É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 :

  • 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

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

  • 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
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.

Lorsqu’il est déployé sur Bedrock AgentCore Runtime, le code de votre serveur est empaqueté sous forme de zip et exécuté dans le runtime géré AgentCore. 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.

Loading the diagram…

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

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

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

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

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 :

Terminal window
pnpm 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 :

Terminal window
pnpm nx your-server-name-dev your-project

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.

Terminal window
pnpm nx your-server-name-inspect your-project

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

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.

Terminal window
pnpm nx your-server-name-serve-stdio your-project

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

Si vous souhaitez exécuter votre serveur MCP localement en utilisant le transport HTTP streamable, vous pouvez utiliser la cible <your-server-name>-serve.

Terminal window
pnpm nx your-server-name-serve your-project

Cette commande utilise uv run uvicorn --reload pour exécuter votre serveur MCP avec le transport HTTP, et redémarre automatiquement lorsque les fichiers changent.

Chaque serveur MCP se voit attribuer son propre port, à partir de 8000, de sorte que plusieurs serveurs peuvent fonctionner côte à côte dans le même espace de travail. Lisez le port sur lequel votre serveur écoute depuis sa cible <your-server-name>-serve dans project.json.

infra = agentcore | agentcore-ecr

Déployer votre serveur MCP sur Bedrock AgentCore Runtime

Section intitulée « Déployer votre serveur MCP sur Bedrock AgentCore Runtime »

Si vous avez sélectionné agentcore ou agentcore-ecr 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.

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');
}
}

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.

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

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);
}
}

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

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.

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
infra = agentcore

Une cible <your-server-name>-package est également ajoutée, qui assemble le package de code déployable : le bundle de dépendances aarch64, votre arborescence de modules Python et un point d’entrée main.py racine. L’infrastructure générée télécharge ce répertoire sous forme de .zip — via AgentRuntimeArtifact.fromCodeAsset sous CDK, ou archivé dans le bucket d’actifs partagé sous Terraform.

infra = agentcore-ecr

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.

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. L’analyse n’est pas mise en cache, car l’image qu’elle lit se trouve dans le moteur de conteneur plutôt que sur le disque — elle analyse donc toujours l’image réelle et échoue bruyamment plutôt que de signaler un succès mis en cache pour une image qui n’est plus là. Chaque exécution prend donc des dizaines de secondes par image et actualise la base de données de vulnérabilités de Trivy, elle nécessite donc un accès réseau. Le script racine trivy fourni analyse chaque image dans l’espace de travail :

Terminal window
pnpm 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.

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é.

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 :

Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsPythonModel Context Protocol
Python Agent to MCPConnect a Python Agent to an MCP server
Model Context ProtocolPythonAmazon DynamoDBPython
Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table
Amazon Bedrock AgentCore GatewayModel Context Protocol
AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway