Servidor Python MCP

Gere um servidor Python 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 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 Python 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 - py#mcp-server
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Pré-requisito do projeto

Primeiro use o gerador py#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
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 é None)
  • pyproject.toml Atualizado com dependências MCP
  • project.json Atualizado com alvos de serviço do servidor MCP

Infraestrutura

infra = agentcore

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

infra = none

Se você selecionou None para infra, nenhum construto CDK ou módulo Terraform é gerado — o servidor MCP está 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 executar ações. O servidor MCP Python usa a biblioteca MCP Python SDK (FastMCP), que fornece uma abordagem baseada em decoradores para definir ferramentas.

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

@mcp.tool(description="Descrição da sua ferramenta")
def your_tool_name(param1: str, param2: int) -> str:
    """Implementação da ferramenta com type hints"""
    # Sua lógica da ferramenta aqui
    return f"Resultado: {param1} com {param2}"

A biblioteca FastMCP trata automaticamente:

• Validação de tipos baseada nas type hints da função
• Geração de schema JSON para o protocolo MCP
• Tratamento de erros e formatação de respostas

Adicionando Recursos

Recursos fornecem contexto ao assistente de IA. Você pode adicioná-los usando o decorador @mcp.resource:

@mcp.resource("example://static-resource", description="Exemplo de recurso estático")
def static_resource() -> str:
    """Retorna conteúdo estático"""
    return "Este é um conteúdo estático que fornece contexto para a IA"

@mcp.resource("dynamic://resource/{item_id}", description="Exemplo de recurso dinâmico")
def dynamic_resource(item_id: str) -> str:
    """Retorna conteúdo dinâmico baseado em parâmetros"""
    # Busca dados baseado no item_id
    data = fetch_data_for_item(item_id)
    return f"Conteúdo dinâmico para {item_id}: {data}"

Configurando com Assistente de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP usa 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": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "my_module.mcp_server.stdio"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/your/project/.venv"
      }
    }
  }
}

Resolução de caminhos

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

Configuração Específica do Assistente

Consulte a documentação a seguir 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 o Amazon Q Developer, permitem especificar uma configuração de 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 alvo 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 múltiplos componentes ao seu projeto (servidores MCP, agentes, etc.), isso inicia todos eles. Para executar apenas este servidor MCP, use seu alvo <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 alvo chamado <your-server-name>-inspect, que inicia seu servidor MCP localmente (via o alvo <your-server-name>-dev, incluindo quaisquer dependências conectadas, como um banco de dados local) e lança o MCP Inspector pré-configurado para conectar a ele através do 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 alvo <your-server-name>-inspect-stdio, que lança o inspector contra uma instância STDIO do seu servidor.

STDIO

A maneira mais fácil de testar e usar um servidor MCP é através do inspector ou configurando 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 uv run para executar seu servidor MCP com transporte STDIO.

HTTP Streamable

Se preferir executar seu servidor MCP localmente usando transporte HTTP Streamable, use 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 uv run uvicorn --reload para executar seu servidor MCP com transporte HTTP (normalmente na porta 8000), e reinicia automaticamente quando os arquivos são alterados.

infra = agentcore

Implantando Seu Servidor MCP no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou agentcore para infra, 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

Este construto usa o módulo aws-cdk-lib/aws-bedrockagentcore.

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.

Passe as saídas do módulo runtime_config_appconfig compartilhado 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 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#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"

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

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

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.

Alvos Bundle e Docker

Para construir seu servidor MCP para o Bedrock AgentCore Runtime, um alvo 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 alvo (aarch64-manylinux_2_28) usando uv pip install

Um alvo docker específico para seu servidor MCP também é adicionado, que copia o Dockerfile e os artefatos empacotados em um diretório de contexto docker. Isso coloca o Dockerfile junto à 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 é verificada em busca de vulnerabilidades como parte da construção 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 falha a construção se qualquer 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 ferramentas incluídas (como npm) para mantê-la assim.

A verificação usa o mesmo mecanismo de contêiner que a construção da sua 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.

Vulnerabilidades não corrigíveis são ignoradas

A verificação é executada com --ignore-unfixed, então vulnerabilidades sem uma correção disponível não falham a construção, já que não podem ser corrigidas atualizando ferramentas no seu Dockerfile — elas não são relatadas na saída de 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 <sua-imagem> 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 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.

Conexões

Use o gerador connection para integrar este projeto com outros em seu workspace. As seguintes conexões envolvem este projeto:

TypeScript Agent para MCPConecte um TypeScript Agent a um servidor MCP

Python Agent para MCPConecte um Python Agent a um servidor MCP

Python MCP Server para Python DynamoDBConecte um Python MCP Server a uma tabela DynamoDB

AgentCore Gateway para Servidor MCPAgregue um servidor MCP atrás de um AgentCore Gateway