Um servidor MCP não precisa virar um “miniagente”. A separação entre um servidor que expõe capacidades e um host que decide o fluxo é uma das escolhas de arquitetura mais importantes para quem está criando integrações com modelos de linguagem em 2026. Um guia publicado em 17 de novembro de 2026 pela Towards Data Science defende exatamente esse limite: ferramentas pequenas, recursos para dados de referência e prompts reutilizáveis; planejamento, estado de trabalho, autorização e confirmação de ações permanecem no aplicativo cliente.

Na prática, isso reduz o risco de um servidor assumir decisões que pertencem ao produto que o está usando. Também deixa a mesma integração compatível com hosts diferentes, facilita auditoria e evita que uma coleção de ferramentas se transforme em um fluxo rígido impossível de adaptar. Este guia mostra como aplicar esse desenho com o SDK Python do Model Context Protocol (MCP), incluindo instalação, exemplo funcional, critérios de segurança e erros recorrentes.

Resumo: o que fica no servidor e o que fica no host

  • Servidor MCP: expõe operações específicas, dados estáveis e instruções reutilizáveis.
  • Host: escolhe quais ferramentas chamar, mantém a conversa e o estado da tarefa, coleta consentimento e aplica políticas de acesso.
  • Modelo: propõe ou seleciona chamadas dentro dos limites e das permissões definidos pelo host.
  • Usuário: continua sendo a fonte de autorização para efeitos sensíveis, como enviar, apagar, comprar ou publicar.

Por que essa fronteira importa agora

O MCP é um padrão para conectar aplicações de IA a dados e funções externas. No SDK oficial para Python, um servidor pode oferecer tools, resources e prompts; o mesmo pacote também fornece cliente e transportes como stdio, Streamable HTTP e SSE. Essa flexibilidade é útil, mas cria uma tentação: colocar no servidor toda a sequência de decisões de uma tarefa.

Esse desenho parece rápido no primeiro protótipo. Depois, costuma gerar três problemas. Primeiro, o servidor passa a guardar estado de sessão e regras de produto que cada host deveria controlar. Segundo, fica mais difícil trocar de aplicativo cliente ou reutilizar a mesma capacidade em outro fluxo. Terceiro, permissões e confirmações podem ser acionadas longe da interface que o usuário realmente está vendo.

Na análise do NoticIA, a divisão é comparável a uma API bem desenhada: o servidor deve declarar o que consegue fazer, com entradas, saídas e limites claros. A decisão sobre quando, por que e com qual autorização usar essa capacidade pertence ao software que conhece a sessão e o usuário.

✅ O que essa arquitetura entrega — e o que ela não entrega

✅ Ganhos reais

  • Ferramentas mais fáceis de testar isoladamente, porque recebem parâmetros explícitos e retornam resultados definidos.
  • Reuso do mesmo servidor por diferentes hosts sem embutir uma conversa, um plano ou uma interface específicos.
  • Menor superfície para decisões implícitas de alto impacto: o host pode exigir confirmação antes de executar uma operação destrutiva.
  • Auditoria melhor: cada chamada pode ser registrada pelo host com usuário, política aplicada e resultado.
  • Manutenção mais simples, pois recursos de catálogo e operações de negócio não ficam misturados com lógica de orquestração.

⚠️ O que ela não resolve sozinha

  • Um schema tipado não substitui autorização no sistema de origem; uma ferramenta ainda precisa validar quem pode acessar ou alterar cada dado.
  • Uma descrição clara de ferramenta não impede o modelo de propor uma ação inadequada; o host precisa aplicar política e confirmação.
  • O MCP não transforma automaticamente uma operação externa em segura, idempotente ou reversível.

Requisitos para acompanhar o exemplo

ComponenteMínimoRecomendadoIdeal
Python3.113.12 ou superiorAmbiente isolado por projeto
Gerenciadorpipuvuv com lockfile versionado
SDKpacote mcpmcp[cli]versão fixada após testes
SistemaWindows, macOS ou Linuxterminal com GitCI para testes e lint
Tempo30 minutos1 a 2 horasmais tempo para autenticação e observabilidade
O SDK Python oficial requer Python 3.11 ou superior.

Como escolher entre tool, resource e prompt

A escolha não é estética. Ela informa ao host e ao modelo o tipo de interação esperado.

  • Tool: uma operação parametrizada, como localizar um pedido, criar um rascunho ou calcular frete. Deve ter entrada pequena e resultado previsível.
  • Resource: informação identificada por URI, como uma ficha de produto, política pública ou documento de referência. É apropriado para leitura e contexto estável.
  • Prompt: modelo reutilizável de instrução. Ele pode padronizar a forma de pedir uma análise, mas não deve executar autorização ou decisões ocultas.

Se a operação exige aprovar uma compra, escolher o próximo passo de uma investigação ou reter o estado de uma conversa, ela não deve ser escondida em uma ferramenta. O host deve coordenar essas etapas e chamar ferramentas atômicas quando necessário.

Passo 1: criar um ambiente e instalar o SDK

Com uv, a instalação pode ser declarada no projeto. O extra cli adiciona o comando mcp, usado para desenvolvimento, execução e instalação. Quem utiliza pip pode chegar ao mesmo resultado.

# Com uv: adiciona o SDK e as ferramentas de linha de comando
uv add "mcp[cli]"

# Alternativa com pip, dentro de um ambiente virtual
python -m pip install "mcp[cli]"

O motivo para usar um ambiente isolado não é apenas organização: ele torna reproduzível a combinação de Python e dependências que foi testada. Para confirmar a instalação, execute uv run mcp --help ou mcp --help, conforme o fluxo escolhido.

Passo 2: expor capacidades pequenas e tipadas

O exemplo abaixo mantém o catálogo no servidor. Ele não decide o que o usuário quer comprar, não adiciona itens a um carrinho e não memoriza a conversa. Essas decisões ficam com o host.

from mcp.server import MCPServer

mcp = MCPServer("catalogo")

CATALOGO = {
    "teclado": {"nome": "Teclado mecânico", "estoque": 12},
    "mouse": {"nome": "Mouse sem fio", "estoque": 0},
}

@mcp.tool()
def buscar_produto(sku: str) -> dict:
    """Retorna dados públicos de um SKU existente no catálogo."""
    produto = CATALOGO.get(sku)
    if produto is None:
        return {"encontrado": False, "sku": sku}
    return {"encontrado": True, "sku": sku, **produto}

@mcp.resource("catalogo://politica-devolucao")
def politica_devolucao() -> str:
    """Exibe a política de devolução que o host pode mostrar ao usuário."""
    return "Devoluções podem ser solicitadas conforme os termos publicados."

As anotações de tipo ajudam o SDK a descrever os parâmetros. A docstring também tem função operacional: ela precisa informar com precisão o que a ferramenta faz, o que não faz e o formato esperado. Evite nomes amplos como executar ou processar; uma ferramenta bem nomeada reduz ambiguidade para humanos e modelos.

Passo 3: testar antes de conectar um host de produção

Salve o arquivo como server.py e abra-o no Inspector do MCP:

uv run mcp dev server.py

Teste pelo menos estes casos: um SKU existente, um SKU inexistente, caracteres inesperados, parâmetros vazios e uma chamada repetida. A verificação intermediária é simples: buscar_produto("teclado") deve devolver os campos definidos; buscar_produto("inexistente") não deve provocar exceção nem vazar dados internos.

Passo 4: deixe a orquestração explícita no host

Imagine que o usuário peça: “compre o teclado”. O servidor de catálogo pode responder sobre produto e estoque. O host deve então decidir se apresenta preço, coleta endereço, confirma valor final e somente depois chama um serviço de pedido com credenciais e trilha de auditoria adequadas. Essa sequência não deve ser uma única ferramenta chamada comprar que aceita texto livre.

Uma regra útil é separar operações de leitura das operações que alteram estado. Uma ferramenta de leitura pode ser chamada sem efeitos externos; uma ferramenta de escrita deve ter escopo estreito, validar contexto no serviço de origem e permitir que o host peça confirmação ao usuário. Para ações irreversíveis, inclua um identificador de idempotência ou um mecanismo equivalente no backend, em vez de confiar que o modelo não repetirá uma chamada.

Comparação de desenhos possíveis

DesenhoVantagemRiscoQuando usar
Tool ampla que executa todo o fluxoProtótipo rápidoAutorização e estado ficam opacosApenas demonstrações sem efeito externo
Tools pequenas + host orquestradorReuso, testes e controleHost exige mais implementaçãoAplicações reais com usuários
Servidor com workflow próprioBom para automação interna muito delimitadaAcoplamento e baixa portabilidadeJobs sem conversa e com política fixa
O desenho recomendado para hosts conversacionais privilegia ferramentas atômicas e políticas no cliente.

Segurança: onde os projetos costumam errar

O SDK oficial mantém uma política de segurança e recomenda reportar vulnerabilidades pelo canal privado do repositório. Isso é importante, mas a segurança principal de um servidor depende do sistema que ele conecta. Não exponha segredos em recursos, não coloque tokens em descrições de ferramentas e não trate o texto vindo do modelo como autorização.

  • Valide autorização novamente no serviço que guarda o dado, mesmo que o host já tenha autenticado o usuário.
  • Use escopos mínimos por ferramenta; “acesso total ao banco” não é um parâmetro conveniente, é uma falha de desenho.
  • Registre tentativas e resultados sem registrar conteúdo sensível desnecessário.
  • Separe ambientes de desenvolvimento, homologação e produção; uma URL de teste não deve apontar para dados reais.
  • Defina limites de taxa, paginação e tamanho de resposta para impedir consultas caras ou vazamento em massa.

Quatro usos práticos

  • Suporte interno: o servidor oferece consulta de status de pedido; o host decide quando mostrar dados pessoais e quando transferir para um atendente.
  • Catálogo técnico: resources expõem documentação por URI; tools localizam versões e compatibilidades sem transformar o servidor em um chatbot.
  • Operações de infraestrutura: tools consultam saúde e logs resumidos; o host exige revisão humana antes de acionar um rollback.
  • Pesquisa corporativa: o servidor pesquisa índices autorizados; o host preserva contexto da investigação, permissões e citações apresentadas ao usuário.

Troubleshooting: cinco falhas frequentes

  • ❌ O host não descobre a ferramenta. Causa: decorador ausente, import errado ou servidor não iniciado. Solução: abra no Inspector e confirme se o nome aparece antes de depurar o host.
  • ❌ A ferramenta recebe argumentos inválidos. Causa: schema ambíguo ou tipos frouxos. Solução: use parâmetros tipados, nomes específicos e retorne erro estruturado para dados inválidos.
  • ❌ Uma ação foi repetida. Causa: retries sem idempotência. Solução: implemente chave de idempotência no sistema de destino e mostre o resultado da operação existente.
  • ❌ Um usuário acessou dado fora do próprio escopo. Causa: confiança exclusiva na autorização do host. Solução: valide identidade e escopo no backend que detém o dado.
  • ❌ O servidor ficou preso a um único aplicativo. Causa: lógica de conversa e estado foram gravados no servidor. Solução: mova plano, histórico e política de UX para o host; mantenha o contrato MCP pequeno.

Perguntas frequentes

Um servidor MCP precisa ter agente próprio?

Não. Um servidor pode ser somente uma camada de capacidades tipadas. Um agente ou host externo pode compor essas capacidades conforme o contexto.

Quando uma operação deve ser tool?

Quando ela é uma função parametrizada que o host pode chamar e cujo efeito pode ser explicado com clareza. Dados de referência identificados por URI tendem a se encaixar melhor como resources.

Posso executar ações de escrita por MCP?

Sim, desde que a operação seja estreita, autorizada pelo backend e acompanhada de política de confirmação no host quando o impacto exigir. O protocolo não elimina esses controles.

stdio ou HTTP?

O SDK oficial suporta stdio, Streamable HTTP e SSE. Stdio é comum para integração local; Streamable HTTP é apropriado quando o servidor precisa ser acessado como serviço. A escolha deve seguir o ambiente, a autenticação e a exposição de rede.

O SDK Python é livre para uso comercial?

O repositório oficial declara licença MIT. Ainda assim, verifique as licenças e condições dos serviços, bibliotecas e dados que o seu servidor integrar.

O que essa prática muda para equipes brasileiras

A expansão do MCP torna simples conectar um assistente a sistemas internos, mas a parte difícil continua sendo a engenharia de produto: definir limites, permissões, logs e responsabilidade por decisões. Equipes que começarem com ferramentas pequenas e contratos claros terão mais facilidade para trocar de host, testar integrações e atender requisitos de segurança. Em vez de criar um “super-servidor” que tenta decidir tudo, vale construir uma base que torne cada ação verificável e reversível quando possível.



Descubra mais sobre noticiAI

Assine para receber nossas notícias mais recentes por e-mail.

Deixe seu comentário