Entenda a anatomia completa de um MCP Server — do import ao registro de tools e o ciclo de vida de uma requisição.
Um MCP Server em Python com FastMCP é surpreendentemente simples. Em apenas ~10 linhas de código, você tem um servidor funcional completo, pronto para receber requisições de qualquer client MCP compatível. A estrutura segue um padrão claro: imports, criação da instância do server, funções decoradas com @mcp.tool() e o ponto de entrada. Cada parte tem um papel específico e essencial no funcionamento do servidor.
A anatomia de um MCP Server com FastMCP possui quatro componentes fundamentais: Import — traz o framework FastMCP para o seu código; Instância — cria o objeto server com um nome identificador; Tools — funções Python decoradas com @mcp.tool() que o modelo pode chamar; e Ponto de entrada — o bloco if __name__ == "__main__" que inicia o servidor. Com apenas essas quatro peças, você tem um MCP Server funcional em ~10 linhas de código.
A estrutura mínima de um MCP Server é: (1) from fastmcp import FastMCP — (2) mcp = FastMCP("meu-server") — (3) uma função decorada com @mcp.tool() — (4) mcp.run() no bloco main. Memorize essa sequência: importar → instanciar → decorar → rodar. Todo MCP Server segue esse padrão, do mais simples ao mais complexo.
Tudo começa com duas linhas de código: o import do FastMCP e a criação da instância do server. Essas duas linhas estabelecem a fundação sobre a qual todo o resto é construído. O nome que você dá ao server é importante — é assim que o client MCP identifica e exibe o server para o usuário. Escolha nomes descritivos e consistentes.
A inicialização de um MCP Server acontece em dois passos: from fastmcp import FastMCP — importa a classe principal do framework — e mcp = FastMCP("nome-do-server") — cria a instância do server com um nome identificador. O nome passado como argumento é o que aparece no client (como o Claude Desktop) para o usuário saber qual server está disponível. Esse nome deve ser único e descritivo do propósito do server.
O FastMCP é o framework oficial recomendado pela Anthropic para criar MCP Servers em Python. Ele abstrai toda a complexidade do protocolo MCP (JSON-RPC, transporte stdio/SSE, negociação de capabilities) em uma API simples baseada em decorators. Com FastMCP, o que antes exigiria centenas de linhas de código de baixo nível agora exige menos de 10 linhas. É a forma mais rápida e recomendada de criar um MCP Server.
O coração de um MCP Server são as tools — funções Python que o modelo de IA pode chamar. O FastMCP usa o decorator @mcp.tool() para transformar qualquer função Python comum em uma tool MCP acessível pelo client. Os parâmetros da função viram os parâmetros da tool, os type hints definem o schema, e a docstring vira a descrição que o modelo lê para decidir quando usar a tool.
O decorator @mcp.tool() é a ponte entre Python e o protocolo MCP. Quando você decora uma função com ele, três coisas acontecem automaticamente: (1) O nome da função vira o nome da tool; (2) Os type hints dos parâmetros são convertidos em JSON Schema para validação; (3) A docstring da função vira a descrição que o modelo usa para entender o propósito da tool. Sem precisar escrever uma única linha de configuração.
Pense no decorator @mcp.tool() como um selo de publicação: quando você coloca o selo em uma função, está dizendo "essa função está disponível para a IA usar". Sem o selo, a função é apenas código Python interno. Com o selo, ela se torna uma capability do server visível para qualquer client MCP conectado. Cada função decorada é registrada automaticamente na lista de tools do server.
Você escreve uma função Python normal com type hints e docstring — como faria em qualquer projeto Python.
Adiciona o decorator @mcp.tool() acima da função — o FastMCP detecta e registra a tool automaticamente.
O FastMCP extrai nome, parâmetros (via type hints) e descrição (via docstring) e gera o JSON Schema automaticamente.
Quando o client conecta, o server envia a lista de tools disponíveis — e o modelo sabe exatamente como chamá-las.
Um MCP Server não é um programa que executa e termina — é um processo que fica ativo, aguardando conexões e processando requisições continuamente. Entender o ciclo de vida completo do server é fundamental para debugar problemas, otimizar performance e construir servers robustos que funcionam de forma confiável em produção.
O ciclo de vida de um MCP Server segue uma sequência bem definida: o server inicia quando o client o executa; registra suas capabilities (tools, resources, prompts); aguarda conexões via stdio ou SSE; recebe requisições do client (chamadas a tools); executa a lógica da tool chamada; retorna o resultado ao client; e volta a aguardar a próxima requisição. Esse ciclo se repete até que o client encerre a conexão.
O client (ex: Claude Desktop) executa o comando configurado. O processo Python inicia e o FastMCP carrega todas as tools decoradas.
O server envia ao client a lista de todas as tools, resources e prompts disponíveis, junto com seus schemas e descrições.
O server fica em loop aguardando mensagens do client via transporte configurado (stdio para processos locais, SSE para remotos).
Quando o modelo decide usar uma tool, o client envia uma mensagem JSON-RPC com o nome da tool e os argumentos.
O FastMCP localiza a função correspondente, valida os parâmetros contra o schema e executa a função Python.
O resultado é serializado e enviado de volta ao client. O server volta ao estado de espera, pronto para a próxima requisição.
Um MCP Server pode ser tão simples quanto um único arquivo Python, ou tão organizado quanto um projeto completo com testes, documentação e módulos separados. A escolha depende da complexidade do que você está construindo. Para aprender e prototipar, um projeto mínimo é suficiente. Para produção, uma estrutura organizada faz toda a diferença na manutenibilidade.
Projeto mínimo — dois arquivos bastam: pyproject.toml (metadados e dependências) e server.py (código do server). Isso é tudo que você precisa para um MCP Server funcional. Projeto completo — para servers mais robustos, organize com: diretório src/ para código-fonte, tests/ para testes, README.md para documentação, e potencialmente múltiplos módulos para separar responsabilidades.
O arquivo pyproject.toml é o centro de configuração do seu projeto Python. Nele ficam definidas as dependências (como o FastMCP), metadados do projeto, e opcionalmente os entry points que facilitam a execução. O uv é o gerenciador de projetos recomendado — ele cuida do ambiente virtual, das dependências e da execução de forma rápida e confiável.
O pyproject.toml define: o nome do projeto, a versão do Python requerida, as dependências (incluindo fastmcp), e opcionalmente entry points com [project.scripts]. O uv gerencia tudo: cria o ambiente virtual automaticamente, instala dependências com velocidade, e permite executar o server com uv run server.py. Juntos, pyproject.toml e uv eliminam a complexidade de configuração de ambiente Python.
Use uv init nome-do-projeto para criar o pyproject.toml automaticamente, e uv add fastmcp para adicionar a dependência. O uv vai criar o ambiente virtual, resolver dependências e atualizar o pyproject.toml — tudo em um único comando. Nunca mais precisa fazer pip install manualmente ou gerenciar virtualenvs na mão.
Certifique-se de que o uv está instalado na sua máquina antes de começar. O Claude Desktop executa o server usando o comando uv run, então se o uv não estiver disponível no PATH, o server simplesmente não iniciará — e o erro pode ser silencioso. Verifique com uv --version antes de prosseguir. Se não estiver instalado, use curl -LsSf https://astral.sh/uv/install.sh | sh.
from fastmcp import FastMCP e mcp = FastMCP("nome") — o nome identifica o server no client.
@mcp.tool() transforma funções Python em tools MCP, extraindo nome, parâmetros e descrição automaticamente.
uv init e uv add fastmcp para começar.
Próximo Módulo: 3.2 — Hello World MCP