Descubra como o FastMCP usa decorators Python e schemas JSON para registrar tools e validar parâmetros automaticamente.
Decorators são um dos recursos mais elegantes do Python. Usando a sintaxe @, você pode modificar o comportamento de uma função sem alterar seu código. O FastMCP aproveita esse recurso para transformar funções Python comuns em tools MCP — sem precisar de arquivos de configuração, registros manuais ou código boilerplate. Basta colocar o decorator e a mágica acontece.
Um decorator em Python é uma função que recebe outra função como argumento e retorna uma versão modificada dela. A sintaxe @decorator é apenas um atalho para funcao = decorator(funcao). No caso do FastMCP, o decorator @mcp.tool() faz três coisas: (1) registra a função na lista de tools do server; (2) extrai metadados (nome, parâmetros, descrição) usando introspecção Python; e (3) mantém a função original intacta — ela continua funcionando normalmente como qualquer função Python.
Pense em um decorator como um selo que marca a função como "disponível para a IA". Assim como um produto na prateleira de uma loja precisa de uma etiqueta de preço para ser vendido, uma função Python precisa do decorator @mcp.tool() para ser visível como tool MCP. Sem o selo, a função existe mas ninguém fora do código sabe que ela está lá. Com o selo, ela aparece no catálogo de tools que o modelo pode usar.
O decorator @mcp.tool() é o componente mais importante do FastMCP. Ele faz o trabalho pesado de conectar seu código Python ao protocolo MCP, extraindo automaticamente tudo que o client precisa saber sobre a tool: nome, descrição e schema de parâmetros. Vamos entender exatamente o que ele extrai e como.
O decorator @mcp.tool() extrai automaticamente três informações essenciais da função: Nome — obtido diretamente do nome da função Python (ex: def buscar_clima vira a tool buscar_clima); Descrição — extraída do docstring da função, que o modelo lê para entender quando e como usar a tool; e Parâmetros — extraídos dos type hints, convertidos automaticamente em JSON Schema para validação. Tudo isso acontece sem nenhuma configuração manual.
A abordagem de "convenção sobre configuração" do FastMCP é inspirada em frameworks como Ruby on Rails e FastAPI. Estudos de produtividade de desenvolvedores mostram que eliminar código boilerplate pode aumentar a velocidade de desenvolvimento em até 40%. No caso do FastMCP, a mesma tool que exigiria ~30 linhas de configuração manual (nome, schema JSON, handler) é definida em apenas 3-5 linhas de Python idiomático com o decorator.
Os type hints do Python são a base do sistema de schemas do FastMCP. Cada tipo Python é convertido automaticamente em um tipo JSON Schema equivalente, que o modelo de IA usa para saber exatamente que parâmetros enviar ao chamar a tool. Quanto mais precisos os type hints, mais preciso o modelo será ao usar a tool.
O FastMCP converte type hints Python em JSON Schema automaticamente:
O modelo usa esse schema para validar os parâmetros antes de enviar — garantindo que a tool sempre recebe dados no formato correto.
Sempre use type hints o mais específicos possível. Em vez de list, use list[str]. Em vez de dict, use dict[str, int]. Quanto mais informação o schema tiver, mais corretamente o modelo vai preencher os parâmetros. Um parâmetro marcado como Optional[str] = None indica ao modelo que ele pode omitir esse campo quando não for relevante.
O que a tool retorna é tão importante quanto o que ela recebe. O FastMCP suporta diversos tipos de retorno e cuida da serialização automaticamente. Strings são retornadas diretamente, dicionários e listas são convertidos em JSON, e tipos complexos são tratados de forma transparente. Entender os tipos de retorno ajuda você a construir tools que comunicam resultados de forma clara para o modelo.
Tools MCP podem retornar diferentes tipos de dados: str — o mais comum, retorna texto simples que o modelo pode usar diretamente; dict — para dados estruturados, serializado automaticamente em JSON; list — para coleções de itens, também serializado em JSON. O FastMCP converte qualquer um desses tipos no formato de resposta MCP correto. Para a maioria dos casos, retornar uma str com a informação formatada é a opção mais simples e eficaz.
A função Python retorna um valor (str, dict, list ou outro tipo suportado).
O FastMCP detecta o tipo do retorno e o converte para o formato de conteúdo MCP (TextContent para strings, JSON para dicts/lists).
O resultado é encapsulado em uma resposta JSON-RPC e enviado de volta ao client, que o repassa ao modelo.
As docstrings das suas funções não são apenas boa prática de programação — no contexto do MCP, elas são a interface entre o modelo de IA e a tool. O modelo lê a descrição para decidir quando usar a tool e como preenchê-la. Uma descrição ruim significa que o modelo vai usar a tool no momento errado ou com parâmetros incorretos. Uma descrição boa significa que a tool será usada perfeitamente.
A docstring da função vira o campo description da tool no protocolo MCP. O modelo de IA lê essa descrição para tomar três decisões: (1) Quando usar — "essa tool é relevante para o que o usuário pediu?"; (2) Como usar — "que parâmetros devo passar?"; e (3) O que esperar — "que tipo de resultado essa tool retorna?". Quanto mais clara, específica e informativa a descrição, melhor o modelo usa a tool. Descrições vagas geram uso impreciso.
Escreva docstrings como se estivesse explicando a tool para um colega que nunca viu seu código. Seja específico sobre o que a tool faz, mencione quando ela deve ser usada, e descreva o que cada parâmetro significa. Por exemplo: em vez de "Busca dados", escreva "Busca a previsão do tempo atual para uma cidade brasileira. Retorna temperatura, umidade e condição climática."
Construir tools MCP que funcionam é fácil. Construir tools que funcionam bem exige atenção a boas práticas. Nomes claros, type hints completos, docstrings descritivas, uso inteligente de defaults e Optional — tudo isso impacta diretamente na qualidade da experiência do usuário final com a IA. Aqui estão as práticas que separam tools amadoras de profissionais.
As boas práticas para tools MCP incluem: Nomes claros — use verbos descritivos como buscar_clima, criar_tarefa, enviar_email; Type hints completos — marque todos os parâmetros e o retorno com tipos precisos; Docstrings descritivas — explique o que a tool faz, quando usar, e o que cada parâmetro significa; Defaults inteligentes — use valores padrão quando um parâmetro tem um valor mais comum; e Optional — use Optional[tipo] para campos que não são obrigatórios, permitindo que o modelo os omita quando não forem relevantes.
Nunca confie que o modelo vai enviar parâmetros corretos — sempre valide as entradas dentro da função. Embora o JSON Schema ajude, o modelo pode enviar valores inesperados (strings vazias, números fora do range, etc.). Use validações simples no início da função e retorne mensagens de erro claras quando os dados forem inválidos. Uma tool que falha com uma mensagem útil é muito melhor que uma que crasheia silenciosamente.
@mcp.tool() extrai automaticamente: nome (da função), descrição (da docstring) e parâmetros (dos type hints).
Próximo Módulo: 3.4 — Server de Calculadora