Server MCP TypeScript

Genera un server Model Context Protocol (MCP) in TypeScript per fornire contesto ai Modelli Linguistici di Grande Dimensioni (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 coerente per gli 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 in 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

Consiglio

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	-	The project to add an MCP server to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your MCP server. Select None for no hosting.
name	string	-	The name of your MCP server (default: mcp-server)
iacProvider	string	CDK	The preferred IaC provider

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 d’ingresso per trasporto STDIO, utile per server MCP locali semplici
      • http.ts Punto d’ingresso per trasporto HTTP streamable, utile per hostare il server MCP
      • Directorytools/

        • add.ts Strumento di esempio
      • Directoryresources/

        • sample-guidance.ts Risorsa di esempio
      • Dockerfile Punto d’ingresso per hostare il server MCP (escluso se computeType è impostato a None)
  • package.json Aggiornato con entry bin e dipendenze MCP
  • project.json Aggiornato con target serve del server MCP

Infrastruttura

Nota

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

Nota

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

Nota

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

    • Directoryagent-core

      • runtime.ts Costrutto CDK generico per il deployment su Bedrock AgentCore Runtime

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 compiere azioni. Puoi aggiungere nuovi strumenti nel file server.ts:

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

Attenzione

L’SDK MCP supporta solo Zod v3 al momento. Per consentire l’uso di Zod v4 in altri generatori, la dipendenza da Zod v3 è installata come zod-v3. Per gli schemi degli strumenti MCP, dovrai importare Zod come segue:

import { z } from 'zod-v3';

Una volta risolto questo problema con l’SDK MCP, potrai rimuovere la dipendenza aggiuntiva zod-v3 e importare direttamente da zod.

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.resource('resource-name', 'example://resource', async (uri) => ({
  contents: [{ uri: uri.href, text: exampleContext }],
}));

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

Configurazione con Assistanti 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:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• 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

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 run your-project:your-server-name-inspect

yarn

yarn nx run your-project:your-server-name-inspect

npm

npx nx run your-project:your-server-name-inspect

bun

bunx nx run your-project:your-server-name-inspect

Questo avvierà l’inspector all’indirizzo 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 run your-project:your-server-name-serve-stdio

yarn

yarn nx run your-project:your-server-name-serve-stdio

npm

npx nx run your-project:your-server-name-serve-stdio

bun

bunx nx run your-project:your-server-name-serve-stdio

Questo comando utilizza tsx --watch per riavviare automaticamente il server al cambiamento dei file.

HTTP Streamable

Se vuoi eseguire il server MCP localmente usando il trasporto HTTP streamable, puoi usare il target <your-server-name>-serve-http.

pnpm

pnpm nx run your-project:your-server-name-serve-http

yarn

yarn nx run your-project:your-server-name-serve-http

npm

npx nx run your-project:your-server-name-serve-http

bun

bunx nx run your-project:your-server-name-serve-http

Questo comando utilizza tsx --watch per riavviare automaticamente il server al cambiamento dei file.

Deploy del Server MCP su Bedrock AgentCore Runtime

Infrastruttura come Codice

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

CDK

Viene generato un costrutto CDK per il tuo progetto, 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');
  }
}

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 è 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

IAM

Per impostazione predefinita, il tuo server MCP sarà protetto tramite autenticazione IAM. Basta distribuirlo senza argomenti aggiuntivi:

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 richiamare il tuo MCP su Bedrock AgentCore Runtime utilizzando il metodo grantInvoke. 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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

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 richiamare l’agent, 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 JWT

Di seguito viene dimostrato come configurare l’autenticazione Cognito per il tuo agent.

CDK

Per configurare l’autenticazione JWT, puoi passare la proprietà authorizerConfiguration al costrutto del server MCP. Ecco un esempio che configura un User Pool e Client Cognito per proteggere il server MCP:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      authorizerConfiguration: {
        customJWTAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

Per configurare l’autenticazione JWT, puoi modificare il modulo del server MCP per configurare la variabile customJWTAuthorizer come segue:

packages/common/terraform/src/app/mcp-servers/my-project-mcp-server/my-project-mcp-server.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Sostituisci con i tuoi ID User Pool e Client o esponili come variabili
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectMcpServer"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "MCP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

Target di Bundle

Per compilare il tuo server MCP per Bedrock AgentCore Runtime, viene aggiunto un target <your-mcp-server>-bundle al tuo progetto, che:

• Bundla il server MCP in un singolo file JavaScript con esbuild, usando http.ts come entrypoint per un server MCP HTTP streamable
• Costruisce un’immagine docker dal Dockerfile che esegue questo server bundlato sulla porta 8000, come da contratto del protocollo MCP

Consiglio

L’immagine docker è costruita usando un tag (ad esempio my-scope-my-project-mcp-server:latest), da cui il costrutto CDK eredita il Dockerfile, permettendo al tuo Dockerfile di essere collocato insieme al 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à.