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

Dica

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	-	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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 computeType é None)
  • pyproject.toml Atualizado com dependências MCP
  • project.json Atualizado com alvos 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 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"
      }
    }
  }
}

Cuidado

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:

• 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 do 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 é 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 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 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-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 uv run para executar seu servidor MCP com transporte HTTP, normalmente na porta 8000.

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 você, 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');
  }
}

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

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

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

CDK

Para configurar autenticação JWT, você pode passar a propriedade authorizerConfiguration para seu construto de servidor MCP. Este exemplo configura um user pool e client Cognito para proteger o servidor:

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 da seguinte forma:

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
}

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-manylinux2014) usando uv pip install

Um alvo docker específico para seu servidor MCP também é adicionado, que:

• Constrói uma imagem docker a partir do Dockerfile que executa seu servidor MCP na porta 8000, conforme contrato do protocolo MCP

Dica

A imagem docker é construída usando uma tag (exemplo my-scope-my-project-mcp-server:latest), referenciada por sua infraestrutura CDK ou Terraform, permitindo que seu Dockerfile fique colocado junto ao projeto do 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.