Serveur MCP TypeScript

Générez un serveur Model Context Protocol (MCP) en TypeScript pour fournir du contexte aux Grands Modèles de Langage (LLM), avec option de déploiement sur Amazon Bedrock AgentCore.

Qu’est-ce que le MCP ?

Le Model Context Protocol (MCP) est un standard ouvert permettant aux assistants IA d’interagir avec des outils et ressources externes. Il fournit une méthode cohérente pour que les LLM puissent :

• Exécuter des outils (fonctions) réalisant des actions ou récupérant des informations
• Accéder à des ressources fournissant du contexte ou des données

Utilisation

Générer un serveur MCP

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

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#mcp-server
5. Remplissez les paramètres requis
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Astuce

Utilisez d’abord le générateur ts#project pour créer un projet auquel ajouter votre serveur MCP.

Options

Paramètre	Type	Par défaut	Description
project Requis	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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Résultat du générateur

Le générateur ajoutera les fichiers suivants à votre projet TypeScript existant :

• Répertoireyour-project/

  • Répertoiresrc/

    • Répertoiremcp-server/ (ou nom personnalisé si spécifié)

      • index.ts Exporte votre serveur
      • server.ts Définition principale du serveur
      • stdio.ts Point d’entrée pour le transport STDIO, utile pour des serveurs MCP locaux simples
      • http.ts Point d’entrée pour le transport HTTP streamable, utile pour héberger votre serveur MCP
      • Répertoiretools/

        • add.ts Exemple d’outil
      • Répertoireresources/

        • sample-guidance.ts Exemple de ressource
      • Dockerfile Point d’entrée pour héberger votre serveur MCP (exclu si computeType est défini sur None)
  • package.json Mis à jour avec l’entrée bin et les dépendances MCP
  • project.json Mis à jour avec la cible de service du serveur MCP

Infrastructure

Note

Si vous avez sélectionné None pour computeType, le générateur ne fournira aucun code d’infrastructure.

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Note

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Modules Terraform pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Note

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

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

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<project-name>

        • <project-name>.ts Construct CDK pour déployer votre serveur MCP
        • Dockerfile Fichier Docker transmis directement utilisé par le construct CDK
  • Répertoirecore

    • Répertoireagent-core

      • runtime.ts Construct CDK générique pour le déploiement sur Bedrock AgentCore Runtime

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiremcp-servers

      • Répertoire<project-name>

        • <project-name>.tf Module pour déployer votre serveur MCP
  • Répertoirecore

    • Répertoireagent-core

      • runtime.tf Module générique pour le déploiement sur Bedrock AgentCore Runtime

Utilisation de votre serveur MCP

Ajout d’outils

Les outils sont des fonctions que l’assistant IA peut appeler pour effectuer des actions. Vous pouvez ajouter de nouveaux outils dans le fichier server.ts :

server.tool("toolName", "description de l'outil",
  { param1: z.string(), param2: z.number() }, // Schéma d'entrée utilisant Zod
  async ({ param1, param2 }) => {
    // Implémentation de l'outil
    return {
      content: [{ type: "text", text: "Résultat" }]
    };
  }
);

Attention

Le SDK MCP ne prend actuellement en charge que Zod v3. Pour permettre l’utilisation de Zod v4 dans d’autres générateurs, la dépendance à Zod v3 est installée sous le nom zod-v3. Pour les schémas d’outils MCP, vous devrez importer Zod comme suit :

import { z } from 'zod-v3';

Une fois ce problème du SDK MCP résolu, vous pourrez supprimer la dépendance supplémentaire zod-v3 et importer directement depuis zod.

Ajout de ressources

Les ressources fournissent du contexte à l’assistant IA. Vous pouvez ajouter des ressources statiques depuis des fichiers ou des ressources dynamiques :

const exampleContext = 'contexte exemple à retourner';

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

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

Configuration avec des assistants IA

Fichiers de configuration

La plupart des assistants IA compatibles avec 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": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Attention

Si vous recevez une erreur comme ENOENT npx lors de la connexion à votre serveur, vous devrez peut-être spécifier le chemin complet vers npx, que vous pouvez obtenir en exécutant which npx dans votre terminal.

Rechargement à chaud

Pendant le développement de votre serveur MCP, vous pouvez activer le flag --watch pour que l’assistant IA détecte toujours les dernières versions des outils/ressources :

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

Note

Si vous ajoutez de nouveaux outils ou ressources, vous devrez peut-être rafraîchir votre serveur MCP dans l’assistant IA.

Configuration spécifique à l’assistant

Consultez la documentation suivante pour configurer MCP avec des assistants IA spécifiques :

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

Astuce

Certains assistants IA comme Amazon Q Developer permettent de spécifier une configuration MCP au niveau de l’espace de travail, ce qui est particulièrement utile pour définir les serveurs MCP pertinents pour un projet donné.

Exécution de votre serveur MCP

Inspecteur

Le générateur configure une cible nommée <your-server-name>-inspect, qui démarre l’MCP Inspector avec la configuration pour se connecter à votre serveur MCP via le transport 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

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

STDIO

La méthode la plus simple pour tester et 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.

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

Cette commande utilise tsx --watch pour redémarrer automatiquement le serveur lors des modifications de fichiers.

HTTP Streamable

Si vous souhaitez exécuter votre serveur MCP localement avec le transport HTTP Streamable, utilisez la cible <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

Cette commande utilise tsx --watch pour redémarrer automatiquement le serveur lors des modifications de fichiers.

Déploiement sur Bedrock AgentCore Runtime

Infrastructure en tant que code

Si vous avez sélectionné BedrockAgentCoreRuntime pour computeType, l’infrastructure CDK ou Terraform correspondante est générée. Vous pouvez l’utiliser pour déployer votre serveur MCP sur Amazon Bedrock AgentCore Runtime.

CDK

Un construct CDK est généré pour votre projet, nommé d’après le name 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) {
    // Ajoutez le serveur MCP à votre stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Terraform

Un module Terraform est généré pour votre projet, nommé d’après le name choisi lors de l’exécution du générateur, ou <ProjectName>-mcp-server par défaut.

Vous pouvez utiliser ce module Terraform dans un projet Terraform :

# Serveur MCP
module "my_project_mcp_server" {
  # Chemin relatif vers le module généré dans le projet common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Docker est requis pour construire et déployer votre serveur MCP. Assurez-vous qu’il est installé et lancé pour éviter des erreurs comme :

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

Authentification

IAM

Par défaut, votre serveur MCP sera sécurisé via l’authentification IAM. Déployez-le simplement sans arguments :

CDK

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Vous pouvez autoriser l’invocation de votre MCP sur Bedrock AgentCore Runtime avec la méthode grantInvoke. Par exemple, pour permettre à un agent généré avec le générateur py#strands-agent d’appeler 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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# Serveur MCP
module "my_project_mcp_server" {
  # Chemin relatif vers le module généré dans le projet common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Pour autoriser l’invocation de votre agent, ajoutez une politique IAM faisant référence à la sortie 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}/*"
  ]
}

Authentification par JWT Cognito

L’exemple suivant montre comment configurer l’authentification Cognito pour votre agent.

CDK

Pour configurer l’authentification JWT, passez la propriété authorizerConfiguration à votre construct MCP. Cet exemple configure un user pool et un client Cognito :

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

Pour configurer l’authentification JWT, modifiez votre module MCP Server en configurant la variable customJWTAuthorizer :

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

  # Remplacez par vos IDs de user pool/client ou exposez-les en variables
  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
}

Cible de bundle

Le générateur configure automatiquement une cible bundle qui utilise Rolldown pour créer un package de déploiement :

pnpm

pnpm nx run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

La configuration de Rolldown se trouve dans rolldown.config.ts, avec une entrée par bundle à générer. Rolldown gère la création de plusieurs bundles en parallèle si définis.

Astuce

Vous pouvez ajuster la configuration de Rolldown dans rolldown.config.ts, par exemple si vous avez des dépendances qui reposent sur des chemins de fichiers et ne peuvent pas être regroupées, vous pouvez les ajouter à la liste des modules external.

La cible de bundle utilise http.ts comme point d’entrée pour le serveur MCP HTTP Streamable à héberger sur Bedrock AgentCore Runtime.

Cible Docker

Le générateur configure une cible <your-server-name>-docker qui exécute le serveur MCP HTTP Streamable bundle sur le port 8000 conformément au contrat de protocole MCP.

Astuce

L’image Docker est construite avec un tag (par exemple my-scope-my-project-mcp-server:latest), dont le Dockerfile du construct CDK hérite, permettant à votre Dockerfile d’être co-localisé avec votre projet de serveur MCP.

Une cible docker est aussi générée pour construire toutes les images Docker si vous avez plusieurs serveurs MCP définis.

Observabilité

Votre serveur MCP est automatiquement configuré avec de l’observabilité grâce à 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 peuplées, vous devrez activer Transaction Search.

Pour plus de détails, consultez la documentation d’AgentCore sur l’observabilité.