Servidor MCP em TypeScript

Gere um servidor Model Context Protocol (MCP) em TypeScript 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 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

Uso

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	CDK	The preferred IaC provider

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 Ferramenta de exemplo
      • Directoryresources/

        • sample-guidance.ts Recurso de exemplo
      • 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á nenhuma infraestrutura como código.

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 de Zod v4 em outros geradores, a dependência do Zod v3 é instalada como zod-v3. Para esquemas de ferramentas MCP, você precisará importar o Zod da seguinte forma:

import { z } from 'zod-v3';

Uma vez que este problema do 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 Assistantes 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-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 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 construct CDK é gerado para você, nomeado com base no name escolhido durante a execução do gerador, ou <ProjectName>McpServer por padrão.

Você pode usar este construct 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 durante a execução do 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 o 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}/*"
  ]
}

Autenticação Cognito JWT

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

CDK

Para configurar autenticação JWT, você pode passar a propriedade authorizerConfiguration para seu construct de servidor MCP. Aqui está um exemplo que configura um user pool e client Cognito:

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:

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

Para construir seu servidor MCP para o Bedrock AgentCore Runtime, um alvo <your-mcp-server>-bundle é adicionado ao seu projeto, que:

• Empacota seu servidor MCP em um único arquivo JavaScript com esbuild, usando http.ts como ponto de entrada para um servidor MCP HTTP Streamable.
• Constrói uma imagem docker a partir do Dockerfile que executa este servidor empacotado na porta 8000, conforme contrato do protocolo MCP

Dica

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

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.