Server MCP TypeScript

Genera un server TypeScript 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

Generare un server MCP

Puoi generare un server MCP TypeScript 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 - ts#mcp-server
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server

npm

npx nx g @aws/nx-plugin:ts#mcp-server

bun

bunx nx g @aws/nx-plugin:ts#mcp-server

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:ts#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run

Prerequisito del progetto

Prima utilizza il generatore ts#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
name	string	-	Il nome del tuo server MCP (default: mcp-server)
auth	iam | cognito	iam	Il metodo utilizzato per autenticare con il tuo server MCP. Applicabile solo quando infra è impostato (ignorato quando infra è none).
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
infra	agentcore | none	agentcore	Il tipo di infrastruttura per ospitare il tuo server MCP. Seleziona none per nessun hosting.
preferInstallDependencies	boolean	true	Se 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

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

• Directoryyour-project/

  • Directorysrc/

    • Directorymcp-server/ (o nome personalizzato se specificato)

      • index.ts Esporta il tuo server
      • server.ts Definizione principale del server
      • stdio.ts Punto di ingresso per trasporto STDIO, utile per server MCP locali semplici
      • http.ts Punto di ingresso per trasporto HTTP Streamable, utile per hosting del server MCP
      • Directorytools/

        • divide.ts Strumento di esempio
      • Directoryresources/

        • sample-guidance.ts Risorsa di esempio
      • Dockerfile Punto di ingresso per hosting del server MCP (escluso se infra è impostato a None)
  • project.json Aggiornato con target serve del server MCP

Infrastruttura

infra = agentcore

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

infra = none

Se hai selezionato None per infra, non vengono generati costrutti CDK o moduli Terraform — il server MCP è configurato solo per uso locale STDIO / HTTP. L’opzione auth viene ignorata in questa modalità poiché non c’è un endpoint ospitato da autenticare.

Architettura

Bedrock AgentCore Runtime

Quando viene distribuito su Bedrock AgentCore Runtime, il server MCP viene compilato in un’immagine container, caricato su Amazon ECR ed eseguito in AgentCore Runtime. 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.

None (local only)

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 server MCP

Aggiungere strumenti

Gli strumenti sono funzioni che l’assistente AI può chiamare per eseguire azioni. Puoi aggiungere nuovi strumenti nel file server.ts:

server.registerTool("toolName", {
  description: "tool description",
  inputSchema: { param1: z.string(), param2: z.number() } // Schema di input usando Zod
},
  async ({ param1, param2 }) => {
    // Implementazione dello strumento
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Aggiungere risorse

Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse statiche da file o risorse dinamiche:

const exampleContext = 'alcuni contesti da restituire';

server.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
  contents: [{ uri: uri.href, text: exampleContext }],
}));

// Risorsa dinamica
server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
  const data = await fetchSomeData();
  return {
    contents: [{ uri: uri.href, text: data }],
  };
});

Configurazione con assistenti AI

File di configurazione

La maggior parte degli assistenti AI che supportano MCP utilizza un approccio simile per la configurazione. È necessario creare o aggiornare un file di configurazione con i dettagli del server MCP:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

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

Ricaricamento a caldo (Hot Reload)

Durante lo sviluppo del server MCP, puoi configurare il flag --watch per far sì che l’assistente AI rilevi sempre le versioni più recenti di strumenti/risorse:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Se aggiungi nuovi strumenti o risorse, potrebbe essere necessario aggiornare il server MCP nell’assistente AI.

Configurazione specifica per l’assistente

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

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

Alcuni assistenti AI, come Amazon Q Developer, permettono di specificare configurazioni MCP a livello di workspace, particolarmente utili per definire i server MCP rilevanti per un progetto specifico.

Esecuzione del server MCP

Sviluppo locale

Per eseguire il tuo server MCP (e tutto ciò che è connesso ad esso, come un database locale) localmente, usa il target dev del progetto:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Se hai aggiunto più componenti al tuo progetto (server MCP, agenti, ecc.), questo li avvia tutti. Per eseguire solo questo server MCP, usa il suo target <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

Inspector

Il generatore configura un target chiamato <your-server-name>-inspect, che avvia il tuo server MCP localmente (tramite il target <your-server-name>-dev, includendo eventuali dipendenze connesse come un database locale) e lancia l’MCP Inspector preconfigurato per connettersi ad esso tramite trasporto 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

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

Consiglio

Per ispezionare il server usando il trasporto STDIO invece, usa il target <your-server-name>-inspect-stdio, che lancia l’inspector contro un’istanza STDIO del tuo server.

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 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 tsx --watch per riavviare automaticamente il server quando i file cambiano.

Streamable HTTP

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 tsx --watch per riavviare automaticamente il server quando i file cambiano.

infra = agentcore

Deploy del server MCP su Bedrock AgentCore Runtime

Infrastruttura come Codice

Se hai selezionato agentcore per infra, 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

Questo costrutto utilizza il modulo aws-cdk-lib/aws-bedrockagentcore.

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.

Passa gli output del modulo condiviso runtime_config_appconfig nel modulo del server 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 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#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"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

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

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

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.

Best Practice di Sicurezza

Quando implementi la logica di business del tuo server MCP, rivedi le best practice di sicurezza di Bedrock AgentCore Runtime.

Target bundle

Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

La configurazione di Rolldown si trova in rolldown.config.ts, con un’entry per bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.

Configurazione personalizzata

Puoi modificare la configurazione di Rolldown in rolldown.config.ts, ad esempio se hai dipendenze che richiedono percorsi file specifici e non possono essere incluse nel bundle, puoi aggiungerle alla lista dei moduli external.

Il target bundle usa http.ts come entrypoint per il server MCP HTTP Streamable da hostare su Bedrock AgentCore Runtime.

Target Docker

Il generatore configura un target <your-server-name>-docker che copia il Dockerfile dalla directory sorgente del tuo server MCP nella directory di output del bundle. Questo co-loca il Dockerfile con gli artefatti bundled, permettendo a CDK di costruire l’immagine Docker direttamente usando AgentRuntimeArtifact.fromAsset.

Viene generato anche un target docker che prepara il contesto docker per tutti i server MCP se ne sono definiti multipli.

Scansione delle immagini

L’immagine Docker creata per questo progetto viene scansionata alla ricerca di vulnerabilità come parte del processo di build utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.

Un target trivy viene aggiunto al progetto che scansiona l’immagine creata e fa fallire la build 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 di container della build dell’immagine (docker o finch), quindi non sono necessari strumenti aggiuntivi. Poiché la scansione viene rieseguita solo quando l’immagine cambia, un’immagine non modificata non viene scansionata nuovamente.

Le vulnerabilità non risolvibili vengono ignorate

La scansione viene eseguita con --ignore-unfixed, quindi le vulnerabilità senza una correzione disponibile non fanno fallire la build, poiché non possono essere risolte aggiornando gli strumenti nel Dockerfile — non vengono riportate nell’output della scansione della build. Man mano che vengono divulgate nuove vulnerabilità, il risultato delle scansioni può cambiare nel tempo, quindi rivedi periodicamente l’immagine eseguendo trivy image <your-image> senza il flag e ricostruisci contro un’immagine base più recente (o aggiungi passaggi al container per applicare le patch disponibili) una volta pubblicata una correzione.

Soppressione dei Risultati di Trivy

Potrebbero esserci casi in cui si desidera sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e si è valutato il rischio come accettabile.

Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella radice del progetto (cioè accanto al file project.json):

.trivyignore

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

Per maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.

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

Connessioni

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

TypeScript Agent to MCPCollega un TypeScript Agent a un server MCP

Python Agent to MCPCollega un Python Agent a un server MCP

MCP Server to Relational DatabaseCollega un MCP Server TypeScript a un database relazionale Aurora

MCP Server to TypeScript DynamoDBCollega un MCP Server TypeScript a una tabella DynamoDB

AgentCore Gateway to MCP ServerAggrega un server MCP dietro un AgentCore Gateway