Servidor MCP de TypeScript

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

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a 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 donde agregarás 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	CDK	The preferred IaC provider

Salida del generador

El generador agregará 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 está configurado como 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

Agregando herramientas

Las herramientas son funciones que el asistente de IA puede llamar para realizar acciones. Puedes agregar 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 se resuelva este issue del SDK MCP, podrás eliminar la dependencia adicional zod-v3 e importar directamente desde zod.

Agregando recursos

Los recursos proveen contexto al asistente de IA. Puedes agregar 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ó anteriormente).

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 los archivos cambian.

HTTP transmitible

Si deseas ejecutar tu servidor MCP localmente usando transporte HTTP transmitible, 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 los archivos cambian.

Desplegando tu servidor MCP en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se generará 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 de CDK para tu proyecto, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>McpServer por defecto.

Puedes usar este constructo de 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 pila
    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

Docker es requerido 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 usando 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, referenciando el 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 JWT con Cognito

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 grupo de usuarios y cliente 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 grupo de usuarios y cliente 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 de bundle

Para construir tu servidor MCP para Bedrock AgentCore Runtime, se agrega un objetivo <your-mcp-server>-bundle a tu proyecto, que:

• Empaceta tu servidor MCP en un único archivo JavaScript con esbuild, usando http.ts como punto de entrada para un servidor MCP HTTP transmitible.
• Construye una imagen docker desde el Dockerfile que ejecuta este servidor empacado 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.

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.