TypeScript MCP Server

Gere um servidor TypeScript Model Context Protocol (MCP) para fornecer contexto a Large Language Models (LLMs), e opcionalmente implante-o no Amazon Bedrock AgentCore.

O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA interajam com ferramentas e recursos externos. Ele fornece uma maneira consistente para LLMs:

• Executar ferramentas (funções) que realizam ações ou recuperam informações
• Acessar recursos que fornecem contexto ou dados

Uso

Gerar um MCP Server

Você pode gerar um servidor MCP TypeScript de duas maneiras:

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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 o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#mcp-server
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Pré-requisito do Projeto

Primeiro use o gerador ts#project para criar um projeto ao qual adicionar seu servidor MCP.

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O projeto ao qual adicionar um servidor MCP
name	string	-	O nome do seu servidor MCP (padrão: mcp-server)
auth	iam | cognito	iam	O método usado para autenticar com seu servidor MCP. Aplicável apenas quando infra está definido (ignorado quando infra é none).
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.
infra	agentcore | none	agentcore	O tipo de infraestrutura para hospedar seu servidor MCP. Selecione none para nenhuma hospedagem.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam computar o grafo de projetos do Nx); instale uma vez no final.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto TypeScript existente:

• Directoryyour-project/

  • Directorysrc/

    • Directorymcp-server/ (or custom name if specified)

      • 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
      • Directorytools/

        • divide.ts Sample tool
      • Directoryresources/

        • 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

Infraestrutura

infra = agentcore

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

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

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

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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

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

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

      • …
  • project.json Project build targets and configuration

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

Para implantar seu MCP Server, os seguintes arquivos são gerados:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<mcp-server-name>

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

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<mcp-server-name>

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

    • Directoryagent-core

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

infra = none

Se você selecionou none para infra, nenhum construto CDK ou módulo Terraform é gerado — o servidor MCP é configurado apenas para uso local STDIO / HTTP. A opção auth é ignorada neste modo, pois não há endpoint hospedado para autenticar.

Arquitetura

Bedrock AgentCore Runtime

Quando implantado no Bedrock AgentCore Runtime, o servidor MCP é construído em uma imagem de contêiner, enviado para o Amazon ECR e executado no AgentCore Runtime. Assistentes de IA invocam o endpoint do plano de dados do AgentCore Runtime, que encaminha chamadas tools/* e resources/* para o seu servidor através do transporte HTTP streamable.

None (local only)

Com infra: none, nenhuma infraestrutura AWS é gerada. O servidor MCP é configurado apenas para transportes STDIO e HTTP locais, e é consumido por assistentes de IA executando na mesma máquina.

Trabalhando com Seu MCP Server

Adicionando Ferramentas

Ferramentas são funções que o assistente de IA pode chamar para realizar ações. Cada ferramenta fica em seu próprio arquivo em tools/ que exporta uma função register<Name>Tool, que você então chama de server.ts. Por exemplo, adicione 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" }]
      };
    }
  );
};

Em seguida, registre-a dentro de createServer em 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;
};

Adicionando Recursos

Recursos fornecem contexto ao assistente de IA. Como ferramentas, cada recurso fica em seu próprio arquivo em resources/ que exporta uma função register<Name>Resource chamada de server.ts. Você pode adicionar recursos estáticos de arquivos ou 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 }],
    };
  });
};

Configurando com Assistentes de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP usa uma abordagem de configuração similar. Você precisará criar ou atualizar um arquivo de configuração com os detalhes do seu servidor MCP:

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

Resolução de Caminho

Se você receber um erro como ENOENT npx ao conectar ao seu servidor, pode ser necessário especificar o caminho completo para npx, que você pode obter executando which npx no seu terminal.

Hot Reload

Ao desenvolver seu servidor MCP, você pode desejar configurar a flag --watch para que o assistente de IA sempre veja as versões mais recentes das ferramentas/recursos:

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

Atualizando Ferramentas

Se você adicionar novas ferramentas ou recursos, pode ser necessário atualizar seu servidor MCP no assistente de IA.

Configuração Específica do Assistente

Por favor, consulte a seguinte documentação para configurar MCP com Assistentes de IA específicos:

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

Configuração do Workspace

Alguns Assistentes de IA, como Kiro, permitem que você especifique a configuração do servidor MCP no nível do workspace, o que é particularmente útil para definir os servidores MCP relevantes para um projeto específico.

Executando Seu MCP Server

Desenvolvimento Local

Para executar seu servidor MCP (e tudo conectado a ele, como um banco de dados local) localmente, use o target dev do projeto:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Se você adicionou vários componentes ao seu projeto (servidores MCP, agentes, etc.), isso inicia todos eles. Para executar apenas este servidor MCP, direcione seu 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

O gerador configura um target chamado <your-server-name>-inspect, que inicia seu servidor MCP localmente (via target <your-server-name>-dev, incluindo quaisquer dependências conectadas, como um banco de dados local) e lança o MCP Inspector pré-configurado para se conectar a ele via 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

Isso iniciará o inspector em http://localhost:6274. Comece clicando no botão “Connect”.

Dica

Para inspecionar o servidor usando transporte STDIO, use o target <your-server-name>-inspect-stdio, que lança o inspector contra uma instância STDIO do seu servidor.

STDIO

A maneira mais fácil de testar e usar um servidor MCP é usando o inspector ou configurando-o com um assistente de IA (como acima).

No entanto, você pode executar seu servidor com transporte STDIO diretamente usando o 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 automaticamente o servidor quando os arquivos mudam.

Streamable HTTP

Se você quiser executar seu servidor MCP localmente usando transporte Streamable HTTP, você pode usar o 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 automaticamente o servidor quando os arquivos mudam.

infra = agentcore

Implantando Seu MCP Server no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou agentcore para infra, a infraestrutura CDK ou Terraform relevante é gerada, que você pode usar para implantar seu servidor MCP no Amazon Bedrock AgentCore Runtime.

CDK

Um construto CDK é gerado para seu Servidor MCP, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>McpServer por padrão.

Você pode usar este construto CDK em uma aplicação 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');
  }
}

Construto CDK

Este construto usa o módulo aws-cdk-lib/aws-bedrockagentcore.

Terraform

Um módulo Terraform é gerado para você, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>-mcp-server por padrão.

Passe as saídas do módulo compartilhado runtime_config_appconfig para o módulo do 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 Necessário

Docker é necessário para construir e implantar seu servidor MCP. Certifique-se de ter instalado e iniciado o Docker para evitar erros como:

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

Autenticação

O gerador fornece uma opção auth para configurar a autenticação para seu servidor MCP. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu servidor MCP.

IAM

Por padrão, seu servidor MCP será protegido usando autenticação IAM, simplesmente implante-o sem nenhum argumento:

CDK

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

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

Você pode conceder acesso para invocar seu servidor MCP no Bedrock AgentCore Runtime usando o método grantInvokeAccess. Por exemplo, você pode desejar que um agente gerado com o gerador py#agent chame seu 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 conceder acesso para invocar seu servidor MCP, você precisará adicionar uma política como a seguinte, referenciando a saída 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}/*"
  ]
}

Autenticação Cognito

Quando você seleciona autenticação Cognito, o gerador configura o servidor MCP para usar Cognito para autenticação.

CDK

O construto gerado aceita uma propriedade identity que configura a autenticação 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,
    });
  }
}

O construto UserIdentity pode ser gerado usando o gerador ts#website#auth, ou você pode criar seu próprio UserPool e UserPoolClient CDK.

Terraform

O módulo gerado aceita variáveis user_pool_id e user_pool_client_ids para autenticação 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]
}

Provedores OIDC Personalizados

Se você precisar de autenticação JWT personalizada com um provedor OIDC não-Cognito, você pode modificar o construto CDK gerado ou o módulo Terraform para seu servidor MCP diretamente. Observe que o gerador de conexão suportará apenas autenticação IAM ou Cognito.

Melhores Práticas de Segurança

Ao implementar a lógica de negócios do seu servidor MCP, revise as melhores práticas de segurança do Bedrock AgentCore Runtime.

Bundle Target

O gerador configura automaticamente um target bundle que usa Rolldown para criar um pacote de implantação:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada por pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

Configuração Personalizada

Você pode ajustar a configuração do Rolldown em rolldown.config.ts, por exemplo, se você tiver dependências que dependem de caminhos de arquivo e não podem ser empacotadas, você pode adicioná-las à lista de módulos external.

O bundle target usa http.ts como ponto de entrada para o servidor MCP Streamable HTTP hospedar no Bedrock AgentCore Runtime.

Docker Target

O gerador configura um target <your-server-name>-docker que copia o Dockerfile do diretório de origem do seu servidor MCP para o diretório de saída do bundle. Isso coloca o Dockerfile junto com os artefatos empacotados, permitindo que o CDK construa a imagem Docker diretamente usando AgentRuntimeArtifact.fromAsset.

Um target docker também é gerado, que prepara o contexto docker para todos os servidores MCP se você tiver vários definidos.

Image Scanning

A imagem Docker construída para este projeto pode ser verificada em busca de vulnerabilidades usando Trivy, executando a partir da imagem Trivy hospedada no ECR.

Um target trivy é adicionado ao seu projeto que verifica a imagem construída e sai com código diferente de zero se alguma vulnerabilidade de severidade HIGH ou CRITICAL for encontrada. O Dockerfile gerado usa uma imagem base sem vulnerabilidades corrigíveis conhecidas dessas severidades no momento da geração, e atualiza as ferramentas incluídas (como npm) para mantê-lo assim.

A verificação usa o mesmo mecanismo de contêiner que sua construção de imagem (docker ou finch), portanto nenhuma ferramenta adicional é necessária. Como a verificação só é executada novamente quando a imagem muda, uma imagem inalterada não é verificada novamente. O script raiz trivy fornecido verifica todas as imagens no workspace:

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Execute o Trivy no CI

A verificação intencionalmente não está conectada ao build, pois isso pode introduzir atrito desnecessário ao iterar durante o desenvolvimento, já que o banco de dados de vulnerabilidades do Trivy é continuamente atualizado com novos CVEs.

Em vez disso, recomendamos executar o comando acima como uma etapa dedicada em seu pipeline de CI antes da implantação em ambientes de produção.

Vulnerabilidades não corrigíveis são ignoradas

A verificação é executada com --ignore-unfixed, portanto vulnerabilidades sem uma correção disponível não falham a construção, pois não podem ser resolvidas atualizando ferramentas em seu Dockerfile — elas não são relatadas na saída da verificação da construção. À medida que novas vulnerabilidades são divulgadas, o resultado das verificações pode mudar ao longo do tempo, então revise a imagem periodicamente executando trivy image <your-image> sem a flag, e reconstrua contra uma imagem base mais recente (ou adicione etapas de contêiner para aplicar patches disponíveis) assim que uma correção for publicada.

Suprimindo Descobertas do Trivy

Pode haver casos em que você deseja suprimir uma vulnerabilidade específica, por exemplo, quando nenhuma correção está disponível ainda e você avaliou o risco como aceitável.

Adicione o ID da vulnerabilidade (um por linha) ao arquivo .trivyignore na raiz do seu projeto (ou seja, ao lado do seu project.json):

.trivyignore

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

Para mais detalhes sobre filtragem de descobertas, consulte a documentação de filtragem do Trivy.

Observabilidade

Seu servidor MCP é configurado automaticamente com observabilidade usando o AWS Distro for Open Telemetry (ADOT), configurando a instrumentação automática no seu Dockerfile.

Você pode encontrar traces no Console AWS do CloudWatch, selecionando “GenAI Observability” no menu. Observe que para que os traces sejam preenchidos, você precisará habilitar o Transaction Search.

Para mais detalhes, consulte a documentação do AgentCore sobre observabilidade.

Conexões

Use o gerador connection para integrar este projeto com outros em seu workspace. As seguintes conexões envolvem este projeto:

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