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

Pré-requisito do projeto

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	-	O projeto ao qual adicionar um servidor MCP
computeType	string	BedrockAgentCoreRuntime	O tipo de computação para hospedar seu servidor MCP. Selecione None para nenhuma hospedagem.
name	string	-	O nome do seu servidor MCP (padrão: mcp-server)
auth	string	IAM	O método usado para autenticar com seu servidor MCP. Escolha entre IAM (padrão) ou Cognito.
iacProvider	string	Inherit	O provedor de IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

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/

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

Implantação serverless

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

Projeto gerado

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

Projeto gerado

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

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.registerTool("toolName", {
  description: "tool description",
  inputSchema: { param1: z.string(), param2: z.number() } // Esquema de entrada usando Zod
},
  async ({ param1, param2 }) => {
    // Implementação da ferramenta
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

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.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
  contents: [{ uri: uri.href, text: exampleContext }],
}));

// Recurso dinâmico
server.registerResource('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"]
    }
  }
}

Resolução de caminhos

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"]
    }
  }
}

Atualizar 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

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

Configuração do workspace

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

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 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 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 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 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 seu Servidor MCP, 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');
  }
}

Construto CDK Alpha

Este construto usa o módulo @aws-cdk/aws-bedrock-agentcore-alpha.

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"
}

Docker necessário

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

O gerador fornece uma opção auth para configurar a autenticação do 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. 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 servidor MCP no Bedrock AgentCore Runtime usando o método grantInvokeAccess. 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.grantInvokeAccess(agent);
  }
}

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 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#react-website#auth, ou você pode criar seu próprio CDK UserPool e UserPoolClient.

Terraform

O módulo gerado aceita as 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"

  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 que não seja 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.

Alvo de Bundle

O gerador configura automaticamente um destino bundle que utiliza o 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 para cada 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 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.

Tags de imagem Docker

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.