Servidor MCP em TypeScript

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

O que é o MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite a assistentes de IA interagirem 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

Utilização

Gerar um servidor MCP

Você pode gerar um servidor MCP em TypeScript de duas formas:

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

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

Dica

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

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	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.

Saída do Gerador

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

• Directoryyour-project/

  • Directorysrc/

    • Directorymcp-server/ (ou nome personalizado se especificado)

      • index.ts Exporta seu servidor
      • server.ts Definição principal do servidor
      • stdio.ts Ponto de entrada para transporte STDIO, útil para servidores MCP locais simples
      • http.ts Ponto de entrada para transporte HTTP Streamable, útil para hospedar seu servidor MCP
      • Directorytools/

        • add.ts Exemplo de ferramenta
      • Directoryresources/

        • sample-guidance.ts Exemplo de recurso
      • Dockerfile Ponto de entrada para hospedar seu servidor MCP (excluído quando computeType é definido como None)
  • package.json Atualizado com entrada bin e dependências MCP
  • project.json Atualizado com alvo de serviço do servidor MCP

Infraestrutura

Nota

Se você selecionou None para computeType, o gerador não fornecerá nenhum código de infraestrutura.

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

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Nota

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Nota

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

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

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.ts Construto CDK para implantar seu MCP Server
        • Dockerfile Arquivo Docker passthrough usado pelo construto CDK
  • Directorycore

    • Directoryagent-core

      • runtime.ts Construto CDK genérico para implantação no Bedrock AgentCore Runtime

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorymcp-servers

      • Directory<project-name>

        • <project-name>.tf Módulo para implantar seu MCP Server
  • Directorycore

    • Directoryagent-core

      • runtime.tf Módulo genérico para implantação no Bedrock AgentCore Runtime

Trabalhando com Seu Servidor MCP

Adicionando Ferramentas

Ferramentas são funções que o assistente de IA pode chamar para realizar ações. Você pode adicionar novas ferramentas no arquivo server.ts:

server.tool("toolName", "tool description",
  { param1: z.string(), param2: z.number() }, // Esquema de entrada usando Zod
  async ({ param1, param2 }) => {
    // Implementação da ferramenta
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Cuidado

O SDK MCP atualmente só suporta Zod v3. Para permitir o uso do Zod v4 em outros geradores, a dependência do Zod v3 é instalada como zod-v3. Para esquemas de ferramentas MCP, você precisará importar Zod da seguinte forma:

import { z } from 'zod-v3';

Uma vez que este problema com o SDK MCP for resolvido, você poderá remover a dependência adicional zod-v3 e importar diretamente de zod.

Adicionando Recursos

Recursos fornecem contexto ao assistente de IA. Você pode adicionar recursos estáticos de arquivos ou recursos dinâmicos:

const exampleContext = 'algum 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 }],
  };
});

Configurando com Assistente de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP usam uma abordagem de configuração semelhante. 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"]
    }
  }
}

Cuidado

Se você receber um erro como ENOENT npx ao conectar ao seu servidor, talvez precise especificar o caminho completo para o npx, que pode ser obtido executando which npx no seu terminal.

Recarregamento a Quente

Durante o desenvolvimento do seu servidor MCP, você pode querer configurar a flag --watch para que o assistente de IA sempre veja as versões mais recentes de ferramentas/recursos:

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

Nota

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

Consulte a documentação a seguir para configurar o MCP com assistentes de IA específicos:

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

Dica

Alguns assistentes de IA, como o Amazon Q Developer, permitem especificar uma configuração de servidor MCP no nível de workspace, o que é particularmente útil para definir os servidores MCP relevantes para um projeto específico.

Executando Seu Servidor MCP

Inspector

O gerador configura um alvo chamado <your-server-name>-inspect, que inicia o MCP Inspector com a configuração para conectar ao seu 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

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

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

Você também pode executar seu servidor com transporte STDIO diretamente usando o alvo <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 automaticamente o servidor quando arquivos mudarem.

HTTP Streamable

Se você deseja executar seu servidor MCP localmente usando transporte HTTP Streamable, pode usar o alvo <your-server-name>-serve.

pnpm

pnpm nx run your-project:your-server-name-serve

yarn

yarn nx run your-project:your-server-name-serve

npm

npx nx run your-project:your-server-name-serve

bun

bunx nx run your-project:your-server-name-serve

Este comando usa tsx --watch para reiniciar automaticamente o servidor quando arquivos mudarem.

Implantando Seu Servidor MCP no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura relevante do CDK ou Terraform será gerada para que você possa implantar seu servidor MCP no Amazon Bedrock AgentCore Runtime.

CDK

Um construto CDK é gerado para você, nomeado com base no name escolhido 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) {
    // Adicione o servidor MCP à sua stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Terraform

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

Você pode usar este módulo do Terraform em um projeto Terraform:

# Servidor MCP
module "my_project_mcp_server" {
  # Caminho relativo para o módulo gerado no projeto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Cuidado

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

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

Autenticação

IAM

Por padrão, seu servidor MCP será protegido usando autenticação IAM. Basta implantá-lo sem argumentos adicionais:

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 MCP no Bedrock AgentCore Runtime usando o método grantInvoke. Por exemplo, você pode permitir que um agent gerado com o gerador py#strands-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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# Servidor MCP
module "my_project_mcp_server" {
  # Caminho relativo para o módulo gerado no projeto common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Para conceder acesso de invocação, 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 JWT

O exemplo abaixo demonstra como configurar autenticação Cognito para seu servidor.

CDK

Para configurar autenticação JWT, você pode passar a propriedade authorizerConfiguration para seu construto de servidor MCP. Este exemplo configura um user pool e client Cognito para proteger o servidor:

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 autenticação JWT, você pode editar seu módulo do Servidor MCP para configurar a variável customJWTAuthorizer da seguinte forma:

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

  # Substitua pelos IDs do seu user pool e client ou exponha como variáveis
  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
}

Alvo de Bundle

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

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

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

Dica

Você pode ajustar a configuração do Rolldown em rolldown.config.ts. Por exemplo, se 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 alvo de bundle usa http.ts como ponto de entrada para o servidor MCP HTTP Streamable hospedado no Bedrock AgentCore Runtime.

Alvo Docker

O gerador configura um alvo <your-server-name>-docker que executa o servidor MCP HTTP Streamable empacotado na porta 8000 conforme o contrato do protocolo MCP.

Dica

A imagem docker é construída usando uma tag (por exemplo my-scope-my-project-mcp-server:latest), da qual o constructo CDK Dockerfile herda, permitindo que seu Dockerfile fique colocado junto ao projeto do servidor MCP.

Um alvo docker também é gerado para executar o build docker para todos servidores MCP se você tiver múltiplos definidos.

Observabilidade

Seu servidor MCP é configurado automaticamente com observabilidade usando a AWS Distro for Open Telemetry (ADOT), através da configuração de instrumentação automática em seu Dockerfile.

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

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