Python MCP Server
Genera un server Python Model Context Protocol (MCP) per fornire contesto ai Large Language Model (LLM), e opzionalmente distribuiscilo su Amazon Bedrock AgentCore.
Cos’è MCP?
Sezione intitolata “Cos’è MCP?”Il Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un modo coerente per gli LLM di:
- Eseguire strumenti (funzioni) che eseguono azioni o recuperano informazioni
- Accedere a risorse che forniscono contesto o dati
Utilizzo
Sezione intitolata “Utilizzo”Generare un MCP Server
Sezione intitolata “Generare un MCP Server”Puoi generare un server MCP Python in due modi:
Esegui questo generatore@aws/nx-plugin:py#mcp-server
pnpm nx g @aws/nx-plugin:py#mcp-server yarn nx g @aws/nx-plugin:py#mcp-server npx nx g @aws/nx-plugin:py#mcp-server bunx nx g @aws/nx-plugin:py#mcp-server- Installa il Nx Console VSCode Plugin se non l'hai già fatto
- Apri la console Nx in VSCode
- Clicca su
Generate (UI)nella sezione "Common Nx Commands" - Cerca
@aws/nx-plugin - py#mcp-server - Compila i parametri richiesti
- Clicca su
Generate
Componi il tuo comando6
Obbligatorio
infra = agentcore | agentcore-ecr
Opzioni
Sezione intitolata “Opzioni”projectObbligatoriostringIl progetto a cui aggiungere un server MCP
authenuminfra = agentcore | agentcore-ecrPredefinito:iamIl metodo utilizzato per autenticare con il tuo server MCP. Applicabile solo quando infra è impostato (ignorato quando infra è none).
iamcognitoiacenumPredefinito:inheritIl provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
inheritcdkterraforminfraenumPredefinito:agentcoreIl tipo di infrastruttura per ospitare il tuo server MCP. agentcore distribuisce il tuo codice come zip in un runtime gestito da AgentCore per il ciclo di build e deploy più veloce. agentcore-ecr costruisce e ospita un'immagine container invece, per il controllo a livello di sistema operativo o una pipeline container consolidata. Seleziona none per nessun hosting.
agentcoreagentcore-ecrnonenamestringIl nome del tuo server MCP (predefinito: mcp-server)
preferInstallDependenciesbooleanPredefinito:trueSe preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.
Output del Generatore
Sezione intitolata “Output del Generatore”Il generatore aggiungerà i seguenti file al tuo progetto Python esistente:
Directoryyour-project/
Directoryyour_module/
Directorymcp_server/ (o nome personalizzato se specificato)
- __init__.py Inizializzazione del pacchetto Python
- server.py Definizione principale del server con strumenti e risorse di esempio
- stdio.py Punto di ingresso per il trasporto STDIO, utile per server MCP locali semplici
- http.py Punto di ingresso per il trasporto HTTP Streamable, utile per l’hosting del tuo server MCP
- Dockerfile Definizione dell’immagine del container (solo quando
infraèagentcore-ecr)
- pyproject.toml Aggiornato con le dipendenze MCP
- project.json Aggiornato con i target di serve del server MCP
Infrastruttura
Sezione intitolata “Infrastruttura”L’opzione infra seleziona come il tuo codice viene impacchettato e ospitato su Amazon Bedrock AgentCore Runtime:
agentcore(predefinito) utilizza il deployment diretto del codice: il tuo codice compilato viene impacchettato come un file.zip, caricato su S3 ed eseguito su un runtime del linguaggio gestito da AgentCore. Non c’è alcuna immagine container da costruire, nessun repository ECR da gestire e nessuna immagine da inviare, il che rende il ciclo di build e deploy sostanzialmente più veloce.agentcore-ecrcostruisce un’immagine containerarm64da unDockerfilefornito e la ospita dal registro condivisocore/asset-ecr, insieme a tutti gli altri container nel workspace. Scegli questa opzione quando hai bisogno di controllare l’immagine del sistema operativo — ad esempio per installare librerie di sistema native — o quando hai una pipeline di container consolidata. Questa opzione fornisce inoltre un target di scansione immagini Trivy (vedi Image Scanning di seguito).nonenon genera alcuna infrastruttura, quindi il progetto può essere eseguito solo localmente.
Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.
Il progetto comune di infrastruttura come codice è strutturato come segue:
Directorypackages/common/constructs
Directorysrc
Directoryapp/ Constructs for infrastructure specific to a project/generator
- …
Directorycore/ Generic constructs which are reused by constructs in
app- …
- index.ts Entry point exporting constructs from
app
- project.json Project build targets and configuration
Directorypackages/common/terraform
Directorysrc
Directoryapp/ Terraform modules for infrastructure specific to a project/generator
- …
Directorycore/ Generic modules which are reused by modules in
app- …
- project.json Project build targets and configuration
Per il deployment del tuo MCP Server, vengono generati i seguenti file:
Directorypackages/common/constructs/src
Directoryapp
Directorymcp-servers
Directory<mcp-server-name>
- <mcp-server-name>.ts CDK construct for deploying your MCP Server
Directorypackages/common/terraform/src
Directoryapp
Directorymcp-servers
Directory<mcp-server-name>
- <mcp-server-name>.tf Module for deploying your MCP Server
Directorycore
Directoryagent-core
- runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
Directoryagent-core-code (when
infraisagentcore)- runtime.tf Packages your MCP Server’s code and delegates to
agent-core
- runtime.tf Packages your MCP Server’s code and delegates to
Directoryagent-core-container (when
infraisagentcore-ecr)- runtime.tf Builds and publishes your MCP Server’s image and delegates to
agent-core
- runtime.tf Builds and publishes your MCP Server’s image and delegates to
Se hai selezionato none per infra, non vengono generati costrutti CDK o moduli Terraform — il server MCP è configurato solo per l’uso locale STDIO / HTTP. L’opzione auth viene ignorata in questa modalità poiché non esiste un endpoint ospitato da autenticare.
Architettura
Sezione intitolata “Architettura”Quando viene distribuito su Bedrock AgentCore Runtime, il codice del tuo server viene impacchettato come zip ed eseguito nel runtime gestito di AgentCore. Gli assistenti AI invocano l’endpoint del data plane di AgentCore Runtime, che inoltra le chiamate tools/* e resources/* al tuo server tramite il trasporto HTTP streamable.
Con infra: agentcore-ecr, il server MCP viene costruito in un’immagine container, caricato su Amazon ECR ed eseguito in AgentCore Runtime. Questo ti offre il controllo a livello di sistema operativo sull’ambiente di runtime, al costo di un ciclo di build e deploy più lungo rispetto al packaging zip sopra descritto.
Con infra: none, non viene generata alcuna infrastruttura AWS. Il server MCP è configurato solo per i trasporti STDIO e HTTP locali, ed è utilizzato da assistenti AI in esecuzione sulla stessa macchina.
Lavorare con il Tuo Server MCP
Sezione intitolata “Lavorare con il Tuo Server MCP”Aggiungere Strumenti
Sezione intitolata “Aggiungere Strumenti”Gli strumenti sono funzioni che l’assistente AI può chiamare per eseguire azioni. Il server MCP Python utilizza la libreria MCP Python SDK (FastMCP), che fornisce un approccio semplice basato su decoratori per definire gli strumenti.
Puoi aggiungere nuovi strumenti nel file 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 libreria FastMCP gestisce automaticamente:
- Validazione dei tipi basata sui type hint della tua funzione
- Generazione dello schema JSON per il protocollo MCP
- Gestione degli errori e formattazione delle risposte
Aggiungere Risorse
Sezione intitolata “Aggiungere Risorse”Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse utilizzando il decoratore @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}"Configurazione con Assistenti AI
Sezione intitolata “Configurazione con Assistenti AI”File di Configurazione
Sezione intitolata “File di Configurazione”La maggior parte degli assistenti AI che supportano MCP utilizza un approccio di configurazione simile. Dovrai creare o aggiornare un file di configurazione con i dettagli del tuo server MCP:
{ "mcpServers": { "your-mcp-server": { "command": "uv", "args": [ "run", "python", "-m", "my_module.mcp_server.stdio" ], "env": { "VIRTUAL_ENV": "/path/to/your/project/.venv" } } }}Configurazione Specifica per Assistente
Sezione intitolata “Configurazione Specifica per Assistente”Consulta la seguente documentazione per configurare MCP con specifici Assistenti AI:
Eseguire il Tuo Server MCP
Sezione intitolata “Eseguire il Tuo Server MCP”Sviluppo Locale
Sezione intitolata “Sviluppo Locale”Per eseguire il tuo server MCP (e tutto ciò che è connesso ad esso, come un database locale) localmente, utilizza il target dev del progetto:
pnpm nx dev your-projectyarn nx dev your-projectnpx nx dev your-projectbunx nx dev your-projectSe hai aggiunto più componenti al tuo progetto (server MCP, agenti, ecc.), questo li avvia tutti. Per eseguire solo questo server MCP, utilizza il suo target <your-server-name>-dev:
pnpm nx your-server-name-dev your-projectyarn nx your-server-name-dev your-projectnpx nx your-server-name-dev your-projectbunx nx your-server-name-dev your-projectInspector
Sezione intitolata “Inspector”Il generatore configura un target denominato <your-server-name>-inspect, che avvia il tuo server MCP localmente (tramite il target <your-server-name>-dev, incluse eventuali dipendenze connesse come un database locale) e lancia l’MCP Inspector preconfigurato per connettersi ad esso tramite trasporto HTTP Streamable.
pnpm nx your-server-name-inspect your-projectyarn nx your-server-name-inspect your-projectnpx nx your-server-name-inspect your-projectbunx nx your-server-name-inspect your-projectQuesto avvierà l’inspector su http://localhost:6274. Inizia cliccando sul pulsante “Connect”.
Il modo più semplice per testare e utilizzare un server MCP è utilizzare l’inspector o configurarlo con un assistente AI (come sopra).
Puoi tuttavia eseguire il tuo server con trasporto STDIO direttamente utilizzando il target <your-server-name>-serve-stdio.
pnpm nx your-server-name-serve-stdio your-projectyarn nx your-server-name-serve-stdio your-projectnpx nx your-server-name-serve-stdio your-projectbunx nx your-server-name-serve-stdio your-projectQuesto comando utilizza uv run per eseguire il tuo server MCP con trasporto STDIO.
Streamable HTTP
Sezione intitolata “Streamable HTTP”Se desideri eseguire il tuo server MCP localmente utilizzando trasporto HTTP Streamable, puoi utilizzare il target <your-server-name>-serve.
pnpm nx your-server-name-serve your-projectyarn nx your-server-name-serve your-projectnpx nx your-server-name-serve your-projectbunx nx your-server-name-serve your-projectQuesto comando utilizza uv run uvicorn --reload per eseguire il tuo server MCP con trasporto HTTP, e si riavvia automaticamente quando i file cambiano.
Ogni server MCP viene assegnato alla propria porta, a partire da 8000, in modo che diversi server possano essere eseguiti fianco a fianco nello stesso workspace. Leggi la porta su cui il tuo server è in ascolto dal suo target <your-server-name>-serve in project.json.
Distribuire il Tuo Server MCP su Bedrock AgentCore Runtime
Sezione intitolata “Distribuire il Tuo Server MCP su Bedrock AgentCore Runtime”Infrastructure as Code
Sezione intitolata “Infrastructure as Code”Se hai selezionato agentcore o agentcore-ecr per infra, viene generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo server MCP su Amazon Bedrock AgentCore Runtime.
Viene generato un costrutto CDK per il tuo server MCP, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>McpServer per impostazione predefinita.
Puoi utilizzare questo costrutto CDK in un’applicazione 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'); }}Viene generato un modulo Terraform per te, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>-mcp-server per impostazione predefinita.
Passa gli output del modulo runtime_config_appconfig condiviso nel modulo del server MCP, insieme all’archivio di artefatti condiviso utilizzato dal suo packaging. Con il packaging agentcore predefinito, il codice del server viene preparato nel bucket di asset condiviso, quindi istanzia il modulo core/asset-bucket una volta per distribuzione, come già fanno i moduli Lambda e API:
module "asset_bucket" { source = "../../common/terraform/src/core/asset-bucket"}
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
asset_bucket_name = module.asset_bucket.bucket_name asset_bucket_arn = module.asset_bucket.bucket_arn}Con agentcore-ecr l’immagine del server viene invece pubblicata nel registro di asset condiviso, quindi passa gli output di core/asset-ecr anziché quelli del bucket. Un registro serve tutti i container nel workspace, quindi nessun server MCP necessita di un proprio repository:
module "asset_ecr" { source = "../../common/terraform/src/core/asset-ecr"}
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
asset_ecr_repository_url = module.asset_ecr.repository_url asset_ecr_repository_arn = module.asset_ecr.repository_arn}Autenticazione
Sezione intitolata “Autenticazione”Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo server MCP. Puoi scegliere tra autenticazione IAM (predefinita) o Cognito durante la generazione del tuo server MCP.
Per impostazione predefinita, il tuo server MCP sarà protetto utilizzando l’autenticazione IAM, semplicemente distribuiscilo senza alcun argomento:
import { MyProjectMcpServer } from '@my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { new MyProjectMcpServer(this, 'MyProjectMcpServer'); }}Puoi concedere l’accesso per invocare il tuo server MCP su Bedrock AgentCore Runtime utilizzando il metodo grantInvokeAccess. Ad esempio, potresti desiderare che un agente generato con il generatore py#agent chiami il tuo server 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); }}# MCP Servermodule "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}Per concedere l’accesso per invocare il tuo server MCP, dovrai aggiungere una policy come la seguente, facendo riferimento all’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}/*" ]}Autenticazione Cognito
Sezione intitolata “Autenticazione Cognito”Quando selezioni l’autenticazione Cognito, il generatore configura il server MCP per utilizzare Cognito per l’autenticazione.
Il costrutto generato accetta una prop identity che configura l’autenticazione 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, }); }}Il costrutto UserIdentity può essere generato utilizzando il generatore ts#website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.
Il modulo generato accetta le variabili user_pool_id e user_pool_client_ids per l’autenticazione 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]}Target Bundle e Docker
Sezione intitolata “Target Bundle e Docker”Per costruire il tuo server MCP per Bedrock AgentCore Runtime, viene aggiunto un target bundle al tuo progetto, che:
- Esporta le tue dipendenze Python in un file
requirements.txtutilizzandouv export - Installa le dipendenze per la piattaforma di destinazione (
aarch64-manylinux_2_28) utilizzandouv pip install
Viene anche aggiunto un target <your-server-name>-package, che assembla il pacchetto di codice distribuibile: il bundle di dipendenze aarch64, l’albero del modulo Python e un punto di ingresso main.py radice. L’infrastruttura generata carica questa directory come .zip — tramite AgentRuntimeArtifact.fromCodeAsset sotto CDK, o archiviata nel bucket di asset condiviso sotto Terraform.
Viene anche aggiunto un target docker specifico per il tuo server MCP, che copia il Dockerfile e gli artefatti raggruppati in una directory di contesto docker. Questo co-localizza il Dockerfile con l’output costruito, consentendo a CDK di costruire l’immagine Docker direttamente utilizzando AgentRuntimeArtifact.fromAsset.
Scansione delle Immagini
Sezione intitolata “Scansione delle Immagini”L’immagine Docker costruita per questo progetto può essere scansionata per vulnerabilità utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.
Un target trivy viene aggiunto al tuo progetto che scansiona l’immagine costruita ed esce con codice diverso da zero se viene trovata qualsiasi vulnerabilità di gravità HIGH o CRITICAL. Il Dockerfile generato utilizza un’immagine base senza vulnerabilità risolvibili note di queste gravità al momento della generazione, e aggiorna gli strumenti inclusi (come npm) per mantenerla tale.
La scansione utilizza lo stesso motore container della tua build dell’immagine (docker o finch), quindi non sono richiesti strumenti aggiuntivi. La scansione non è memorizzata in cache, poiché l’immagine che legge risiede nel motore container anziché su disco — quindi scansiona sempre l’immagine reale e fallisce in modo evidente anziché riportare un successo memorizzato in cache per un’immagine che non è più presente. Ogni esecuzione richiede quindi decine di secondi per immagine e aggiorna il database delle vulnerabilità di Trivy, quindi necessita di accesso alla rete. Lo script root trivy fornito scansiona ogni immagine nel workspace:
pnpm trivyyarn trivynpm run trivybun trivySoppressione dei Risultati di Trivy
Sezione intitolata “Soppressione dei Risultati di Trivy”Potrebbero esserci casi in cui desideri sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e hai valutato il rischio come accettabile.
Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella root del tuo progetto (cioè accanto al tuo project.json):
# node-tar arbitrary file write - not exploitable in our usageCVE-2024-XXXXXPer maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.
Osservabilità
Sezione intitolata “Osservabilità”Il tuo server MCP è configurato automaticamente con l’osservabilità utilizzando AWS Distro for Open Telemetry (ADOT), configurando l’auto-strumentazione nel tuo Dockerfile.
Puoi trovare le tracce nella Console AWS CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.
Per maggiori dettagli, consulta la documentazione AgentCore sull’osservabilità.
Connessioni
Sezione intitolata “Connessioni”Utilizza il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto: