Construindo Agentes de IA que Funcionam: Servidores MCP, Orquestração de Ferramentas e Execução Local

O mundo da IA tem um problema de encanamento. Temos modelos de linguagem incríveis, mas conectá-los a ferramentas reais — bancos de dados, APIs, sistemas de arquivos, outros agentes — ainda parece como colar endpoints HTTP juntos e rezar. É por isso que o Protocolo de Contexto do Modelo (MCP) é importante. É o padrão que falta para como os modelos de IA se comunicam com o mundo exterior, e está mudando a forma como construo cada projeto de agente.

Nos últimos anos, construí mais de 116 projetos de código aberto — assistentes de voz, resumidores de saúde, analisadores de documentos legais, ferramentas de segurança — e o padrão ao qual continuo retornando é o mesmo: um LLM local, um servidor MCP expondo ferramentas e um loop de agente que conecta tudo. Sem dependência de nuvem. Sem chaves de API expirando às 2 da manhã. Apenas um modelo, um protocolo e um propósito.

Neste post, vou explicar como o MCP funciona, mostrar como construir seu próprio servidor MCP em Python e compartilhar padrões que aprendi ao enviar projetos de agentes reais.

O Que É MCP e Por Que Você Deveria Se Importar?

O Protocolo de Contexto do Modelo é um padrão aberto (originalmente introduzido pela Anthropic) que define como os modelos de IA descobrem e invocam ferramentas externas. Pense nisso como USB-C para IA: uma única interface padronizada que qualquer modelo pode usar para se comunicar com qualquer ferramenta.

Antes do MCP, cada integração de IA era sob medida. Quer que seu modelo pesquise um banco de dados? Escreva um wrapper de chamada de função personalizado. Quer que ele leia PDFs? Outro wrapper. Cada ferramenta falava seu próprio dialeto, e mudar de modelo significava reescrever seu código de ligação.

O MCP corrige isso com três conceitos principais:

1. Ferramentas — Funções que o modelo pode invocar (por exemplo, search_documents, analyze_clause)
2. Recursos — Dados que o modelo pode ler (arquivos, registros de banco de dados, respostas de API)
3. Prompts — Modelos de prompt reutilizáveis que orientam o comportamento do modelo

A beleza é que os servidores MCP são agnósticos em relação ao modelo. O mesmo servidor funciona com Claude, GPT, Gemma, Llama ou qualquer modelo que suporte o uso de ferramentas. Construa uma vez, troque de modelos livremente.

Anatomia de um Servidor MCP em Python

Vamos construir um servidor MCP minimalista. Eu uso o mcp SDK Python, que torna isso surpreendentemente limpo:

from mcp.server.fastmcp import FastMCP

# Inicializa o servidor MCP
mcp = FastMCP("document-tools")

@mcp.tool()
def summarize_document(text: str, max_length: int = 200) -> str:
    """Resumir um documento para o comprimento especificado."""
    # Na prática, isso chama seu LLM local
    from ollama import chat
    response = chat(
        model="gemma3:4b",
        messages=[{
            "role": "user",
            "content": f"Resumir em {max_length} palavras:\n\n{text}"
        }]
    )
    return response.message.content

@mcp.tool()
def extract_entities(text: str) -> dict:
    """Extrair entidades nomeadas do texto."""
    from ollama import chat
    response = chat(
        model="gemma3:4b",
        messages=[{
            "role": "user",
            "content": f"Extrair entidades (pessoas, organizações, datas) como JSON:\n\n{text}"
        }]
    )
    return {"entities": response.message.content}

@mcp.resource("docs://{doc_id}")
def get_document(doc_id: str) -> str:
    """Recuperar um documento pelo ID."""
    docs = load_document_store()
    return docs.get(doc_id, "Documento não encontrado")

if __name__ == "__main__":