Servidor MCP de TypeScript

Genera un servidor TypeScript del Model Context Protocol (MCP) para proporcionar contexto a Modelos de Lenguaje Grande (LLMs), con opción de desplegarlo 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 proveen contexto o datos

Uso

Generar un servidor MCP

Puedes generar un servidor MCP en TypeScript de dos formas:

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

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

Consejo

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	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.

Salida del Generador

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

• Directoryyour-project/

  • Directorysrc/

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

      • index.ts Exporta tu servidor
      • server.ts Definición principal del servidor
      • stdio.ts Punto de entrada para transporte STDIO, útil para servidores MCP locales simples
      • http.ts Punto de entrada para transporte HTTP transmitible, útil para alojar tu servidor MCP
      • Directorytools/

        • add.ts Herramienta de ejemplo
      • Directoryresources/

        • sample-guidance.ts Recurso de ejemplo
      • Dockerfile Punto de entrada para alojar tu servidor MCP (excluido cuando computeType se establece en None)
  • package.json Actualizado con entrada bin y dependencias MCP
  • project.json Actualizado con objetivo serve del servidor MCP

Infraestructura

Nota

Si seleccionaste None para computeType, el generador no proveerá infraestructura como código.

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Nota

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

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Nota

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

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

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.ts Constructo CDK para implementar tu MCP Server
        • Dockerfile Archivo Docker passthrough utilizado por el constructo CDK
  • Directorycore

    • Directoryagent-core

      • runtime.ts Constructo CDK genérico para implementar en Bedrock AgentCore Runtime

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.tf Módulo para implementar tu MCP Server
  • Directorycore

    • Directoryagent-core

      • runtime.tf Módulo genérico para implementar en Bedrock AgentCore Runtime

Trabajando con tu Servidor MCP

Añadiendo Herramientas

Las herramientas son funciones que el asistente de IA puede llamar para realizar acciones. Puedes añadir nuevas herramientas en el archivo server.ts:

server.tool("toolName", "tool description",
  { param1: z.string(), param2: z.number() }, // Esquema de entrada usando Zod
  async ({ param1, param2 }) => {
    // Implementación de la herramienta
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Precaución

El SDK de MCP solo soporta Zod v3 actualmente. Para permitir el uso de Zod v4 en otros generadores, la dependencia de Zod v3 se instala como zod-v3. Para esquemas de herramientas MCP, necesitarás importar Zod de la siguiente manera:

import { z } from 'zod-v3';

Una vez que este issue del SDK MCP se resuelva, podrás eliminar la dependencia adicional zod-v3 e importar directamente desde zod.

Añadiendo Recursos

Los recursos proveen contexto al asistente de IA. Puedes añadir recursos estáticos desde archivos o recursos dinámicos:

const exampleContext = 'algun contexto para retornar';

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

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

Configuración con Asistentes de IA

Archivos de configuración

La mayoría de los asistentes de IA que admiten MCP utilizan un enfoque de configuración similar. Deberá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"]
    }
  }
}

Precaución

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

Recarga en caliente

Durante el desarrollo de tu servidor MCP, puedes configurar el flag --watch para que el asistente de IA siempre vea las versiones más recientes de las herramientas/recursos:

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

Nota

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

Configuración específica del asistente

Consulta la siguiente documentación para configurar MCP con asistentes de IA específicos:

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

Consejo

Algunos asistentes de IA, como Amazon Q Developer, permiten especificar configuraciones de servidor MCP a nivel de espacio de trabajo, lo cual es especialmente útil para definir los servidores MCP relevantes para un proyecto particular.

Ejecutando tu Servidor MCP

Inspector

El generador configura un objetivo llamado <your-server-name>-inspect, que inicia el MCP Inspector con la configuración para conectarse a tu servidor MCP usando transporte 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

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

STDIO

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

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

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

HTTP Transmisible

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

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

Despliegue en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se generará la infraestructura correspondiente 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 proyecto, 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) {
    // Agrega el servidor MCP a tu stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Terraform

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

Puedes usar este módulo de Terraform en un proyecto Terraform:

# Servidor MCP
module "my_project_mcp_server" {
  # Ruta relativa al módulo generado en el proyecto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Precaución

Se requiere Docker para construir y desplegar tu servidor MCP. Asegúrate de tener Docker instalado y en ejecución para evitar errores como:

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

Autenticación

IAM

Por defecto, tu servidor MCP estará protegido con autenticación IAM. Simplemente despliégalo sin argumentos adicionales:

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 MCP en Bedrock AgentCore Runtime usando el método grantInvoke. Por ejemplo, quizás quieras que un agente generado con el generador py#strands-agent pueda llamar 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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# Servidor MCP
module "my_project_mcp_server" {
  # Ruta relativa al módulo generado en el proyecto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

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

Autenticación Cognito JWT

El siguiente ejemplo demuestra cómo configurar autenticación Cognito para tu agente.

CDK

Para configurar autenticación JWT, puedes pasar la propiedad authorizerConfiguration a tu constructo de servidor MCP. Este ejemplo configura un User Pool y Client de Cognito para proteger el servidor 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

Para configurar autenticación JWT, puedes editar tu módulo de Servidor MCP para configurar la variable customJWTAuthorizer de la siguiente manera:

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

  # Reemplaza con tus IDs de user pool y client o expón como 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
}

Objetivo Bundle

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

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

Consejo

Puedes ajustar la configuración de Rolldown en rolldown.config.ts, por ejemplo si tienes dependencias que requieren rutas de archivo específicas y no pueden incluirse en el bundle, puedes agregarlas a la lista de módulos external.

El objetivo bundle usa http.ts como punto de entrada para el servidor MCP HTTP transmisible que se aloja en Bedrock AgentCore Runtime.

Objetivo Docker

El generador configura un objetivo <your-server-name>-docker que ejecuta el servidor MCP HTTP transmisible empaquetado en el puerto 8000 según el contrato de protocolo MCP.

Consejo

La imagen docker se construye usando un tag (por ejemplo my-scope-my-project-mcp-server:latest), del cual hereda el Dockerfile del constructo CDK, permitiendo que tu Dockerfile esté ubicado junto a tu proyecto de servidor MCP.

También se genera un objetivo docker que ejecuta la construcción docker para todos los servidores MCP si tienes múltiples definidos.

Observabilidad

Tu servidor MCP se configura automáticamente con observabilidad utilizando la 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 rellenen, deberás habilitar Transaction Search.

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