Esqueça a complexidade de protocolos manuais: aprenda a expor ferramentas e dados internos para agentes de IA em menos de 30 linhas de código.
Com a consolidação do Model Context Protocol (MCP) como o padrão aberto da indústria para conectar modelos de inteligência artificial a ferramentas, bancos de dados e APIs corporativas, a forma como integramos IA no dia a dia da engenharia mudou drasticamente.
Antes do MCP, conectar um agente de IA a um sistema interno exigia integrações proprietárias para cada ferramenta. Se você quisesse usar o Claude Desktop, o Cursor e um squad autônomo na mesma base de dados, precisava escrever três integrações diferentes com formatos incompatíveis de function calling.
O MCP resolveu essa fragmentação criando uma interface aberta universal. Porém, quando muitos desenvolvedores olham a especificação pela primeira vez, acham que criar um servidor customizado exige implementar dezenas de linhas de protocolo JSON-RPC e controle complexo de transporte. A realidade é muito mais simples: com o FastMCP do SDK oficial em Python, você constrói e roda seu próprio servidor de ferramentas em poucos minutos.
O que é o FastMCP na Prática?
Se você já construiu APIs em Python com FastAPI ou Flask, vai se sentir em casa com o FastMCP. Ele funciona sob os mesmos princípios elegantes de desenvolvimento moderno:
- Desenvolvimento Orientado a Decorators: Você escreve uma função Python padrão e adiciona o decorador
@mcp.tool(). - Tipagem Estática Nativa: O FastMCP utiliza os type hints nativos do Python para gerar automaticamente os schemas JSON que os modelos precisam para entender os parâmetros.
- Documentação como Contexto do Modelo: O docstring da sua função vira automaticamente a descrição da ferramenta que o LLM lê para saber quando e como deve usá-la.
- Transporte Transparente: O servidor gerencia nativamente o transporte via STDIO (entrada e saída padrão do terminal) para rodar localmente no seu computador ou via HTTP/SSE para a nuvem.
Implementação Prática: Construindo seu Servidor em Python
Veja como é direto criar um servidor MCP com ferramentas úteis para consultar dados internos de pedidos e verificar status de serviços:
# server.py
from mcp.server.fastmcp import FastMCP
from typing import Dict, Any
# 1. Inicializa o servidor FastMCP com um nome descritivo
mcp = FastMCP("FerramentasCorporativas")
# 2. Define uma ferramenta para consultar status de pedidos
@mcp.tool()
def consultar_pedido(pedido_id: str) -> Dict[str, Any]:
"""
Consulta as informações e o status atual de entrega de um pedido corporativo.
Args:
pedido_id: O identificador único do pedido (ex: PED-10293).
"""
# Em produção, aqui você executaria uma query no banco ou chamada a uma API interna
return {
"pedido_id": pedido_id,
"status": "DESPACHADO",
"previsao_entrega": "48 horas",
"transportadora": "Log Express"
}
# 3. Define uma ferramenta para checar saúde de infraestrutura
@mcp.tool()
def verificar_saude_servico(servico_nome: str) -> str:
"""
Verifica a disponibilidade e a latência de um microsserviço interno.
Args:
servico_nome: Nome do microsserviço (ex: checkout, pagamentos, catalogo).
"""
servicos_disponiveis = ["checkout", "pagamentos", "catalogo"]
if servico_nome.lower() in servicos_disponiveis:
return f"Serviço '{servico_nome}' operando normalmente (Latência média: 42ms)."
return f"Alerta: Serviço '{servico_nome}' não encontrado ou indisponível."
# 4. Ponto de entrada do servidor
if __name__ == "__main__":
mcp.run()
Como Conectar seu Servidor ao Claude Desktop ou Cursor
Para que o Claude Desktop ou ferramentas de IA na IDE passem a enxergar suas novas ferramentas locais, basta adicionar o servidor no arquivo de configuração (ex: claude_desktop_config.json):
{
"mcpServers": {
"meu-servidor-corporativo": {
"command": "python",
"args": ["/caminho/absoluto/para/server.py"]
}
}
}
Ao reiniciar o aplicativo, o ícone de ferramentas aparecerá ativo. Quando você perguntar no chat: "Verifique o status do pedido PED-10293 e me diga a previsão de entrega", o modelo chamará automaticamente a sua função Python, processará o retorno estruturado e responderá com precisão cirúrgica sem alucinar.
Três Regras de Ouro ao Construir Ferramentas MCP
- Escreva Docstrings Precisos e Ricos em Contexto: O modelo decide se vai chamar sua ferramenta com base exclusivamente na descrição da função. Explique com clareza o que ela faz e dê exemplos de formatos esperados nos parâmetros.
- Mantenha as Ferramentas Atômicas: Crie ferramentas com responsabilidade única e bem delimitada. Ferramentas que tentam fazer muitas ações diferentes confundem a seleção de parâmetros do modelo.
- Trate Erros com Mensagens Acionáveis: Nunca deixe sua ferramenta levantar uma exceção não tratada que quebre o processo. Capture erros e retorne mensagens semânticas claras (ex: "Pedido não encontrado no banco de dados") para que o modelo entenda a falha e responda adequadamente ao usuário.
Conclusão
A engenharia de IA moderna não é sobre tentar colocar todo o conhecimento do mundo dentro de prompts gigantescos; é sobre equipar os modelos com ferramentas seguras, padronizadas e fáceis de plugar.
Com o FastMCP em Python, você elimina a barreira técnica de entrada e transforma qualquer script ou API interna da sua empresa em uma capacidade nativa que qualquer agente ou assistente de IA moderno consegue utilizar em minutos.