Servidor MCP de TypeScript

Genera un servidor TypeScript Model Context Protocol (MCP) para proporcionar contexto a Modelos de Lenguaje Grande (LLMs), y opcionalmente despliégalo en Amazon Bedrock AgentCore.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA interactuar con herramientas y recursos externos. Proporciona una forma consistente para que los LLMs puedan:

• Ejecutar herramientas (funciones) que realizan acciones o recuperan información
• Acceder a recursos que proporcionan contexto o datos

Uso

Generar un Servidor MCP

Puedes generar un servidor MCP de TypeScript de dos maneras:

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#mcp-server
5. Complete los parámetros requeridos
6. Haga clic en Generate

Requisito Previo del Proyecto

Primero usa el generador ts#project para crear un proyecto al que agregar tu servidor MCP.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar un servidor MCP
name	string	-	El nombre de tu servidor MCP (predeterminado: mcp-server)
auth	iam | cognito	iam	El método utilizado para autenticar con tu servidor MCP. Solo aplicable cuando infra está configurado (se ignora cuando infra es none).
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
infra	agentcore | none	agentcore	El tipo de infraestructura para alojar tu servidor MCP. Selecciona none para no tener alojamiento.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

El generador agregará los siguientes archivos a tu proyecto TypeScript existente:

• Directorioyour-project/

  • Directoriosrc/

    • Directoriomcp-server/ (o nombre personalizado si se especifica)

      • index.ts Exports your server
      • server.ts Main server definition
      • stdio.ts Entry point for STDIO transport, useful for simple local MCP servers
      • http.ts Entry point for Streamable HTTP transport, useful for hosting your MCP server
      • Directoriotools/

        • divide.ts Sample tool
      • Directorioresources/

        • sample-guidance.ts Sample resource
      • Dockerfile Entry point for hosting your MCP server (excluded when infra is set to None)
  • project.json Updated with MCP server serve target

Infraestructura

infra = agentcore

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu MCP Server, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<mcp-server-name>

        • <mcp-server-name>.ts CDK construct for deploying your MCP Server

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriomcp-servers

      • Directorio<mcp-server-name>

        • <mcp-server-name>.tf Module for deploying your MCP Server
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

infra = none

Si seleccionaste none para infra, no se generan construcciones CDK ni módulos Terraform — el servidor MCP está configurado solo para uso local STDIO / HTTP. La opción auth se ignora en este modo ya que no hay un endpoint alojado para autenticar.

Arquitectura

Bedrock AgentCore Runtime

Cuando se despliega en Bedrock AgentCore Runtime, el servidor MCP se construye en una imagen de contenedor, se envía a Amazon ECR y se ejecuta en AgentCore Runtime. Los asistentes de IA invocan el endpoint del plano de datos de AgentCore Runtime, que reenvía las llamadas tools/* y resources/* a tu servidor a través del transporte HTTP transmisible.

None (local only)

Con infra: none, no se genera infraestructura de AWS. El servidor MCP está configurado solo para transportes STDIO y HTTP locales, y es consumido por asistentes de IA que se ejecutan en la misma máquina.

Trabajar con tu Servidor MCP

Agregar Herramientas

Las herramientas son funciones que el asistente de IA puede llamar para realizar acciones. Cada herramienta vive en su propio archivo bajo tools/ que exporta una función register<Name>Tool, que luego llamas desde server.ts. Por ejemplo, agrega tools/my-tool.ts:

tools/my-tool.ts

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export const registerMyTool = (server: McpServer) => {
  server.registerTool("toolName", {
    description: "tool description",
    inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
  },
    async ({ param1, param2 }) => {
      // Tool implementation
      return {
        content: [{ type: "text", text: "Result" }]
      };
    }
  );
};

Luego regístrala dentro de createServer en server.ts:

server.ts

import { registerMyTool } from './tools/my-tool.js';

export const createServer = async () => {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });

  registerMyTool(server);

  return server;
};

Agregar Recursos

Los recursos proporcionan contexto al asistente de IA. Al igual que las herramientas, cada recurso vive en su propio archivo bajo resources/ que exporta una función register<Name>Resource llamada desde server.ts. Puedes agregar recursos estáticos desde archivos o recursos dinámicos:

resources/my-resource.ts

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export const registerMyResource = (server: McpServer) => {
  const exampleContext = 'some context to return';

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

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

Configurar con Asistentes de IA

Archivos de Configuración

La mayoría de los asistentes de IA que soportan MCP utilizan un enfoque de configuración similar. Necesitarás crear o actualizar un archivo de configuración con los detalles de tu servidor MCP:

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

Resolución de Rutas

Si recibes un error como ENOENT npx al conectarte a tu servidor, es posible que necesites especificar la ruta completa a npx, la cual puedes obtener ejecutando which npx en tu terminal.

Recarga en Caliente

Mientras desarrollas tu servidor MCP, es posible que desees configurar la bandera --watch para que el asistente de IA siempre vea las últimas versiones de herramientas/recursos:

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

Actualización de Herramientas

Si agregas nuevas herramientas o recursos, es posible que necesites actualizar tu servidor MCP en el asistente de IA.

Configuración Específica del Asistente

Por favor, consulta la siguiente documentación para configurar MCP con Asistentes de IA específicos:

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

Configuración del Espacio de Trabajo

Algunos Asistentes de IA, como Kiro, te permiten especificar la configuración del servidor MCP a nivel de espacio de trabajo, lo cual es particularmente útil para definir los servidores MCP relevantes para un proyecto en particular.

Ejecutar tu Servidor MCP

Desarrollo Local

Para ejecutar tu servidor MCP (y todo lo conectado a él, como una base de datos local) localmente, usa el target dev del proyecto:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Si has agregado múltiples componentes a tu proyecto (servidores MCP, agentes, etc.), esto los inicia todos. Para ejecutar solo este servidor MCP, apunta a su 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

El generador configura un target llamado <your-server-name>-inspect, que inicia tu servidor MCP localmente (a través del target <your-server-name>-dev, incluyendo cualquier dependencia conectada como una base de datos local) y lanza el MCP Inspector preconfigurado para conectarse a él a través del transporte Streamable HTTP.

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

Esto iniciará el inspector en http://localhost:6274. Comienza haciendo clic en el botón “Connect”.

Consejo

Para inspeccionar el servidor usando el transporte STDIO en su lugar, usa el target <your-server-name>-inspect-stdio, que lanza el inspector contra una instancia STDIO de tu servidor.

STDIO

La forma más fácil de probar y usar un servidor MCP es usando el inspector o configurándolo con un asistente de IA (como se indicó anteriormente).

Sin embargo, puedes ejecutar tu servidor con transporte STDIO directamente usando el 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

Este comando usa tsx --watch para reiniciar automáticamente el servidor cuando los archivos cambian.

Streamable HTTP

Si deseas ejecutar tu servidor MCP localmente usando transporte Streamable HTTP, puedes usar el 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

Este comando usa tsx --watch para reiniciar automáticamente el servidor cuando los archivos cambian.

infra = agentcore

Desplegar tu Servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste agentcore para infra, se genera la infraestructura relevante de CDK o Terraform que puedes usar para desplegar tu servidor MCP en Amazon Bedrock AgentCore Runtime.

CDK

Se genera un constructo CDK para tu servidor MCP, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>McpServer por defecto.

Puedes usar este constructo CDK en una aplicación 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');
  }
}

Constructo CDK

Este constructo usa el módulo aws-cdk-lib/aws-bedrockagentcore.

Terraform

Se genera un módulo Terraform para ti, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>-mcp-server por defecto.

Pasa las salidas del módulo compartido runtime_config_appconfig al módulo del servidor 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 Requerido

Docker es necesario para construir y desplegar tu servidor MCP. Asegúrate de haber instalado e iniciado Docker para evitar errores como:

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

Autenticación

El generador proporciona una opción auth para configurar la autenticación de tu servidor MCP. Puedes elegir entre autenticación IAM (predeterminada) o Cognito al generar tu servidor MCP.

IAM

Por defecto, tu servidor MCP estará asegurado usando autenticación IAM, simplemente despliégalo sin ningún argumento:

CDK

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

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

Puedes otorgar acceso para invocar tu servidor MCP en Bedrock AgentCore Runtime usando el método grantInvokeAccess. Por ejemplo, es posible que desees que un agente generado con el generador py#agent llame a tu servidor 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

# MCP Server
module "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
}

Para otorgar acceso para invocar tu servidor MCP, necesitarás agregar una política como la siguiente, haciendo referencia a la salida 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}/*"
  ]
}

Autenticación con Cognito

Cuando seleccionas autenticación Cognito, el generador configura el servidor MCP para usar Cognito para la autenticación.

CDK

El constructo generado acepta una prop identity que configura la autenticación con 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,
    });
  }
}

El constructo UserIdentity puede ser generado usando el generador ts#website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

Terraform

El módulo generado acepta las variables user_pool_id y user_pool_client_ids para la autenticación con 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]
}

Proveedores OIDC Personalizados

Si requieres autenticación JWT personalizada con un proveedor OIDC que no sea Cognito, puedes modificar el constructo CDK generado o el módulo Terraform para tu servidor MCP directamente. Ten en cuenta que el generador de conexiones solo admitirá autenticación IAM o Cognito.

Mejores Prácticas de Seguridad

Al implementar la lógica de negocio de tu servidor MCP, revisa las mejores prácticas de seguridad de Bedrock AgentCore Runtime.

Target Bundle

El generador configura automáticamente un target bundle que utiliza Rolldown para crear un paquete de despliegue:

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 configuración de Rolldown se encuentra en rolldown.config.ts, con una entrada por cada bundle a generar. Rolldown gestiona la creación de múltiples bundles en paralelo si están definidos.

Configuración Personalizada

Puedes ajustar la configuración de Rolldown en rolldown.config.ts, por ejemplo, si tienes dependencias que dependen de rutas de archivos y no pueden ser empaquetadas, puedes agregarlas a la lista de módulos external.

El target bundle usa http.ts como punto de entrada para el servidor MCP Streamable HTTP para alojar en Bedrock AgentCore Runtime.

Target Docker

El generador configura un target <your-server-name>-docker que copia el Dockerfile desde el directorio fuente de tu servidor MCP al directorio de salida del bundle. Esto coloca el Dockerfile junto con los artefactos empaquetados, permitiendo que CDK construya la imagen Docker directamente usando AgentRuntimeArtifact.fromAsset.

También se genera un target docker que prepara el contexto docker para todos los servidores MCP si tienes múltiples definidos.

Escaneo de Imágenes

La imagen Docker construida para este proyecto puede ser escaneada en busca de vulnerabilidades usando Trivy, ejecutándose desde la imagen Trivy alojada en ECR.

Se agrega un target trivy a tu proyecto que escanea la imagen construida y termina con código distinto de cero si se encuentra alguna vulnerabilidad de severidad HIGH o CRITICAL. El Dockerfile generado usa una imagen base sin vulnerabilidades corregibles conocidas de estas severidades al momento de la generación, y actualiza las herramientas incluidas (como npm) para mantenerlo así.

El escaneo usa el mismo motor de contenedores que tu construcción de imagen (docker o finch), por lo que no se requieren herramientas adicionales. Dado que el escaneo solo se vuelve a ejecutar cuando la imagen cambia, una imagen sin cambios no se vuelve a escanear. El script raíz trivy proporcionado escanea cada imagen en el workspace:

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Ejecuta Trivy en CI

El escaneo intencionalmente no está conectado a build ya que esto puede introducir fricción innecesaria al iterar durante el desarrollo, ya que la base de datos de vulnerabilidades de Trivy se actualiza continuamente con nuevos CVEs.

En su lugar, recomendamos ejecutar el comando anterior como un paso dedicado en tu pipeline de CI antes del despliegue a entornos de producción.

Las vulnerabilidades no corregibles son ignoradas

El escaneo se ejecuta con --ignore-unfixed, por lo que las vulnerabilidades sin una corrección disponible no fallan la construcción, ya que no pueden ser accionadas actualizando las herramientas en tu Dockerfile — no se reportan en la salida del escaneo de la construcción. A medida que se divulgan nuevas vulnerabilidades, el resultado de los escaneos puede cambiar con el tiempo, así que revisa la imagen periódicamente ejecutando trivy image <your-image> sin la bandera, y reconstruye contra una imagen base más nueva (o agrega pasos de contenedor para aplicar parches disponibles) una vez que se publique una corrección.

Suprimiendo Hallazgos de Trivy

Puede haber instancias en las que desees suprimir una vulnerabilidad específica, por ejemplo cuando aún no hay una corrección disponible y has evaluado el riesgo como aceptable.

Agrega el ID de vulnerabilidad (uno por línea) al archivo .trivyignore en la raíz de tu proyecto (es decir, junto a tu project.json):

.trivyignore

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

Para más detalles sobre el filtrado de hallazgos, consulta la documentación de filtrado de Trivy.

Observabilidad

Tu servidor MCP está configurado automáticamente con observabilidad utilizando AWS Distro for Open Telemetry (ADOT), mediante la configuración de auto-instrumentación en tu Dockerfile.

Puedes encontrar trazas en la consola de AWS CloudWatch, seleccionando “GenAI Observability” en el menú. Ten en cuenta que para que las trazas se completen necesitarás habilitar Transaction Search.

Para más detalles, consulta la documentación de AgentCore sobre observabilidad.

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

Python Agent to MCPConnect a Python Agent to an MCP server

MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway