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:

Execute este gerador@aws/nx-plugin:py#mcp-server

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

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

Monte seu comando6

projectObrigatório

authinfra = agentcore | agentcore-ecr

iamcognito

iac

inheritcdkterraform

infra

agentcoreagentcore-ecrnone

name

preferInstallDependencies

true

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

Pré-requisito do Projeto

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

Opções

Opções do gerador6 opções

projectObrigatóriostring

O projeto ao qual adicionar um servidor MCP

authenuminfra = agentcore | agentcore-ecrPadrão: iam

O método usado para autenticar com seu servidor MCP. Aplicável apenas quando infra está definido (ignorado quando infra é none).

iamcognito

iacenumPadrão: inherit

O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

inheritcdkterraform

infraenumPadrão: agentcore

O tipo de infraestrutura para hospedar seu servidor MCP. agentcore implanta seu código como um zip em um runtime gerenciado pelo AgentCore para o ciclo de build e deploy mais rápido. agentcore-ecr constrói e hospeda uma imagem de container, para controle em nível de SO ou um pipeline de container estabelecido. Selecione none para nenhuma hospedagem.

agentcoreagentcore-ecrnone

namestring

O nome do seu servidor MCP (padrão: mcp-server)

preferInstallDependenciesbooleanPadrão: 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 Definição de imagem de contêiner (apenas quando infra é agentcore-ecr)
  • pyproject.toml Atualizado com dependências MCP
  • project.json Atualizado com targets de servir do servidor MCP

Infraestrutura

A opção infra seleciona como seu código é empacotado e hospedado no Amazon Bedrock AgentCore Runtime:

• agentcore (padrão) usa implantação direta de código: seu código compilado é empacotado como um .zip, enviado para o S3 e executado em um runtime de linguagem gerenciado pelo AgentCore. Não há imagem de contêiner para construir, nenhum repositório ECR para gerenciar e nenhuma imagem para enviar, o que resulta em um ciclo de compilação e implantação substancialmente mais rápido.
• agentcore-ecr constrói uma imagem de contêiner arm64 a partir de um Dockerfile fornecido e a hospeda no registro compartilhado core/asset-ecr, juntamente com todos os outros contêineres no workspace. Escolha esta opção quando você precisar de controle sobre a imagem do sistema operacional — por exemplo, para instalar bibliotecas nativas do sistema — ou quando você tiver um pipeline de contêiner estabelecido. Esta opção também fornece um alvo de varredura de imagem Trivy (veja Varredura de Imagem abaixo).
• none não gera nenhuma infraestrutura, então o projeto só pode ser executado localmente.

infra = agentcore | agentcore-ecr

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
    • Directoryagent-core-code (when infra is agentcore)

      • runtime.tf Packages your MCP Server’s code and delegates to agent-core
    • Directoryagent-core-container (when infra is agentcore-ecr)

      • runtime.tf Builds and publishes your MCP Server’s image and delegates to agent-core

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

AgentCore Runtime

Quando implantado no Bedrock AgentCore Runtime, o código do seu servidor é empacotado como um zip e executado no runtime gerenciado do AgentCore. 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.

Loading the diagram…

AgentCore Runtime (container)

Com infra: agentcore-ecr, o servidor MCP é construído em uma imagem de contêiner, enviado para o Amazon ECR e executado no AgentCore Runtime. Isso oferece controle em nível de sistema operacional sobre o ambiente de runtime, ao custo de um ciclo de build e deploy mais longo do que o empacotamento zip acima.

Loading the diagram…

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.

Loading the diagram…

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, e reinicia automaticamente quando os arquivos mudam.

Cada servidor MCP recebe sua própria porta, começando em 8000, para que vários servidores possam ser executados lado a lado no mesmo workspace. Leia a porta em que seu servidor escuta a partir de seu target <your-server-name>-serve em project.json.

infra = agentcore | agentcore-ecr

Implantando Seu Servidor MCP no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou agentcore ou agentcore-ecr 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, juntamente com o armazenamento de artefatos compartilhado que seu empacotamento usa. Sob o empacotamento padrão agentcore, o código do servidor é preparado no bucket de ativos compartilhado, então instancie o módulo core/asset-bucket uma vez por implantação, como os módulos Lambda e API já fazem:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

Sob agentcore-ecr, a imagem do servidor é publicada no registro de ativos compartilhado, então passe as saídas do core/asset-ecr em vez do bucket. Um registro serve todos os contêineres no workspace, então nenhum servidor MCP precisa de um repositório próprio:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

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

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

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

infra = agentcore

Um target <your-server-name>-package também é adicionado, que monta o pacote de código implantável: o pacote de dependências aarch64, sua árvore de módulos Python e um ponto de entrada main.py raiz. A infraestrutura gerada faz upload deste diretório como um .zip — via AgentRuntimeArtifact.fromCodeAsset no CDK, ou arquivado no bucket de ativos compartilhado no Terraform.

infra = agentcore-ecr

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. A verificação não é armazenada em cache, pois a imagem que ela lê reside no mecanismo de contêiner em vez de no disco — então ela sempre verifica a imagem real e falha de forma explícita em vez de relatar uma aprovação em cache para uma imagem que não está mais lá. Cada execução, portanto, leva dezenas de segundos por imagem e atualiza o banco de dados de vulnerabilidades do Trivy, então ela precisa de acesso à rede. 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