Servidor MCP Python

Gere um servidor Python 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 Servidor MCP

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#mcp-server

yarn

yarn nx g @aws/nx-plugin:py#mcp-server

npm

npx nx g @aws/nx-plugin:py#mcp-server

bun

bunx nx g @aws/nx-plugin:py#mcp-server

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

pnpm

pnpm nx g @aws/nx-plugin:py#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:py#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:py#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:py#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 - py#mcp-server
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Pré-requisito do Projeto

Primeiro use o gerador py#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 calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

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

• Directoryyour-project/

  • Directoryyour_module/

    • Directorymcp_server/ (ou nome personalizado se especificado)

      • __init__.py Inicialização do pacote Python
      • server.py Definição principal do servidor com ferramentas e recursos de exemplo
      • stdio.py Ponto de entrada para transporte STDIO, útil para servidores MCP locais simples
      • http.py Ponto de entrada para transporte HTTP Streamable, útil para hospedar seu servidor MCP
      • Dockerfile Ponto de entrada para hospedar seu servidor MCP (excluído quando infra é definido como None)
  • pyproject.toml Atualizado com dependências MCP
  • project.json Atualizado com targets de servir do servidor MCP

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 Servidor MCP

Adicionando Ferramentas

Ferramentas são funções que o assistente de IA pode chamar para realizar ações. O servidor MCP Python usa a biblioteca MCP Python SDK (FastMCP), que fornece uma abordagem simples baseada em decoradores para definir ferramentas.

Você pode adicionar novas ferramentas no arquivo server.py:

@mcp.tool(description="Your tool description")
def your_tool_name(param1: str, param2: int) -> str:
    """Tool implementation with type hints"""
    # Your tool logic here
    return f"Result: {param1} with {param2}"

A biblioteca FastMCP lida automaticamente com:

• Validação de tipo baseada nas dicas de tipo da sua função
• Geração de esquema JSON para o protocolo MCP
• Tratamento de erros e formatação de resposta

Adicionando Recursos

Recursos fornecem contexto ao assistente de IA. Você pode adicionar recursos usando o decorador @mcp.resource:

@mcp.resource("example://static-resource", description="Static resource example")
def static_resource() -> str:
    """Return static content"""
    return "This is static content that provides context to the AI"

@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
def dynamic_resource(item_id: str) -> str:
    """Return dynamic content based on parameters"""
    # Fetch data based on item_id
    data = fetch_data_for_item(item_id)
    return f"Dynamic content for {item_id}: {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": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "my_module.mcp_server.stdio"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/your/project/.venv"
      }
    }
  }
}

Resolução de Caminho

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

Configuração Específica do Assistente

Por favor, consulte a seguinte documentação para configurar o 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 Servidor MCP

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 inicia o MCP Inspector pré-configurado para se conectar a ele via transporte HTTP Streamable.

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 inicia 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 uv run para executar seu servidor MCP com transporte STDIO.

Streamable HTTP

Se você quiser executar seu servidor MCP localmente usando transporte HTTP Streamable, 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 uv run uvicorn --reload para executar seu servidor MCP com transporte HTTP (normalmente na porta 8000), e reinicia automaticamente quando os arquivos mudam.

infra = agentcore

Implantando Seu Servidor MCP 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.

Targets Bundle e Docker

Para construir seu servidor MCP para o Bedrock AgentCore Runtime, um target bundle é adicionado ao seu projeto, que:

• Exporta suas dependências Python para um arquivo requirements.txt usando uv export
• Instala dependências para a plataforma de destino (aarch64-manylinux_2_28) usando uv pip install

Um target docker específico para seu servidor MCP também é adicionado, que copia o Dockerfile e artefatos empacotados em um diretório de contexto docker. Isso coloca o Dockerfile junto com a saída construída, permitindo que o CDK construa a imagem Docker diretamente usando AgentRuntimeArtifact.fromAsset.

Verificação de Imagem

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

Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway