Server MCP Python

Genera un server Python per il Model Context Protocol (MCP) per fornire contesto ai Large Language Model (LLM), con opzione di deploy su Amazon Bedrock AgentCore.

Cos’è l’MCP?

Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un modo consistente per i LLM di:

• Eseguire strumenti (funzioni) che compiono azioni o recuperano informazioni
• Accedere a risorse che forniscono contesto o dati

Utilizzo

Genera un Server MCP

Puoi generare un server MCP Python in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - py#mcp-server
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Prerequisito del progetto

Prima utilizza il generatore py#project per creare un progetto a cui aggiungere il tuo server MCP.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	Il progetto a cui aggiungere un server MCP
computeType	string	BedrockAgentCoreRuntime	Il tipo di compute per ospitare il tuo server MCP. Seleziona None per nessun hosting.
name	string	-	Il nome del tuo server MCP (predefinito: mcp-server)
auth	string	IAM	Il metodo utilizzato per autenticarsi con il server MCP. Scegli tra IAM (predefinito) o Cognito.
iacProvider	string	Inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

Output del Generatore

Il generatore aggiungerà questi file al tuo progetto Python esistente:

• Directoryyour-project/

  • Directoryyour_module/

    • Directorymcp_server/ (o nome personalizzato se specificato)

      • __init__.py Inizializzazione pacchetto Python
      • server.py Definizione principale del server con strumenti e risorse di esempio
      • stdio.py Punto d’ingresso per trasporto STDIO, utile per server MCP locali semplici
      • http.py Punto d’ingresso per trasporto HTTP Streamable, utile per hosting del server MCP
      • Dockerfile Punto d’ingresso per hosting del server MCP (escluso se computeType è impostato a None)
  • pyproject.toml Aggiornato con dipendenze MCP
  • project.json Aggiornato con target di servizio del server MCP

Infrastruttura

Deploy serverless

Se hai selezionato None per computeType, il generatore non produrrà alcuna infrastruttura come codice.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Per il deployment del tuo MCP Server, vengono generati i seguenti file:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.ts Costrutto CDK per il deployment del tuo MCP Server
        • Dockerfile File Docker passthrough utilizzato dal costrutto CDK

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.tf Modulo per il deployment del tuo MCP Server
  • Directorycore

    • Directoryagent-core

      • runtime.tf Modulo generico per il deployment su Bedrock AgentCore Runtime

Lavorare con il Tuo Server MCP

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 basato su decoratori per definire gli strumenti.

Puoi aggiungere nuovi strumenti nel file server.py:

@mcp.tool(description="Descrizione del tuo strumento")
def your_tool_name(param1: str, param2: int) -> str:
    """Implementazione dello strumento con type hints"""
    # Logica dello strumento qui
    return f"Risultato: {param1} con {param2}"

La libreria FastMCP gestisce automaticamente:

• Validazione dei tipi basata sui type hint della funzione
• Generazione dello schema JSON per il protocollo MCP
• Gestione errori e formattazione delle risposte

Aggiungere Risorse

Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse usando il decoratore @mcp.resource:

@mcp.resource("example://static-resource", description="Esempio risorsa statica")
def static_resource() -> str:
    """Restituisce contenuto statico"""
    return "Questo è contenuto statico che fornisce contesto all'AI"

@mcp.resource("dynamic://resource/{item_id}", description="Esempio risorsa dinamica")
def dynamic_resource(item_id: str) -> str:
    """Restituisce contenuto dinamico basato su parametri"""
    # Recupera dati basati su item_id
    data = fetch_data_for_item(item_id)
    return f"Contenuto dinamico per {item_id}: {data}"

Configurazione con Assistenti AI

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

Risoluzione del percorso

Se ricevi un errore come ENOENT uv durante la connessione al server, potrebbe essere necessario specificare il percorso completo di uv, che puoi ottenere eseguendo which uv nel terminale.

Configurazione specifica dell’assistente

Consulta la seguente documentazione per configurare MCP con assistenti AI specifici:

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

Configurazione del workspace

Alcuni assistenti AI, come Amazon Q Developer, consentono di specificare una configurazione del server MCP a livello di workspace, particolarmente utile per definire i server MCP rilevanti per un progetto specifico.

Esecuzione del Server MCP

Inspector

Il generatore configura un target chiamato <your-server-name>-inspect che avvia l’MCP Inspector con la configurazione per connettersi al tuo server MCP usando il trasporto 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

Questo avvierà l’inspector su http://localhost:6274. Inizia cliccando sul pulsante “Connect”.

STDIO

Il modo più semplice per testare e usare un server MCP è utilizzare l’inspector o configurarlo con un assistente AI (come sopra).

Puoi comunque eseguire il server con il trasporto STDIO direttamente usando il target <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

Questo comando usa uv run per eseguire il server MCP con trasporto STDIO.

HTTP Streamable

Se vuoi eseguire il server MCP localmente usando il trasporto HTTP Streamable, puoi usare il target <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

Questo comando usa uv run uvicorn --reload per eseguire il server MCP con trasporto HTTP (tipicamente sulla porta 8000), e riavvia automaticamente quando i file cambiano.

Deploy del Server MCP su Bedrock AgentCore Runtime

Infrastruttura come Codice

Se hai selezionato BedrockAgentCoreRuntime per computeType, verrà generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo server MCP su Amazon Bedrock AgentCore Runtime.

CDK

Viene generato un costrutto CDK per il tuo server MCP, denominato in base al name 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) {
    // Aggiungi il server MCP al tuo stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Costrutto CDK Alpha

Questo costrutto utilizza il modulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Viene generato un modulo Terraform per il tuo progetto, denominato in base al name scelto durante l’esecuzione del generatore, o <ProjectName>-mcp-server per impostazione predefinita.

Puoi utilizzare questo modulo Terraform in un progetto Terraform:

# Server MCP
module "my_project_mcp_server" {
  # Percorso relativo al modulo generato nel progetto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Docker richiesto

Docker è necessario per costruire e distribuire il tuo server MCP. Assicurati di aver installato e avviato Docker per evitare errori come:

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

Autenticazione

Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo server MCP. Puoi scegliere tra l’autenticazione IAM (predefinita) o Cognito durante la generazione del tuo server MCP.

IAM

Per impostazione predefinita, il tuo server MCP sarà protetto utilizzando l’autenticazione IAM. Basta distribuirlo senza alcun argomento:

CDK

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 voler consentire a un agent generato con il generatore py#strands-agent di chiamare 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);
  }
}

Terraform

# Server MCP
module "my_project_mcp_server" {
  # Percorso relativo al modulo generato nel progetto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Per concedere l’accesso a invocare il tuo server MCP, dovrai aggiungere una policy come la seguente, riferendoti 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

Quando selezioni l’autenticazione Cognito, il generatore configura il server MCP per utilizzare Cognito per l’autenticazione.

CDK

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#react-website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

Terraform

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"

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Provider OIDC personalizzati

Se hai bisogno di un’autenticazione JWT personalizzata con un provider OIDC non-Cognito, puoi modificare direttamente il costrutto CDK o il modulo Terraform generato per il tuo server MCP. Nota che il generatore di connessione supporterà solo l’autenticazione IAM o Cognito.

Target Bundle e Docker

Per costruire il tuo server MCP per Bedrock AgentCore Runtime, viene aggiunto un target bundle che:

• Esporta le dipendenze Python in un file requirements.txt usando uv export
• Installa le dipendenze per la piattaforma target (aarch64-manylinux2014) usando uv pip install

Viene anche aggiunto un target docker specifico per il tuo server MCP che:

• Costruisce un’immagine docker dal Dockerfile che esegue il server MCP sulla porta 8000, secondo il contratto di servizio MCP

Tag immagine Docker

L’immagine docker è costruita usando un tag (esempio my-scope-my-project-mcp-server:latest), referenziato dalla tua infrastruttura CDK o Terraform, permettendo al tuo Dockerfile di rimanere co-locato con il progetto del server MCP.

Osservabilità

Il tuo server MCP viene configurato automaticamente con l’osservabilità utilizzando AWS Distro for Open Telemetry (ADOT), tramite la configurazione dell’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 ulteriori dettagli, consulta la documentazione di AgentCore sull’osservabilità.