Como criar servidor MCP para o sistema interno: leitura primeiro

Como criar servidor MCP para o sistema interno: leitura primeiro

Para criar um servidor MCP para o sistema interno, escolha um caso de uso estreito, use um SDK oficial, exponha poucas ferramentas somente leitura com nomes claros e autentique cada chamada com a identidade de quem pergunta, sempre com o menor escopo possível. Só depois de ver o uso real nos logs vale considerar ferramentas que alteram dados. Esse caminho é um pouco mais lento no começo e bem mais seguro depois.

Principais pontos

• MCP (Model Context Protocol) é um padrão aberto para conectar aplicações de IA a sistemas externos, e o servidor é a camada que você controla.
• Comece com ferramentas somente leitura: o pior erro possível passa a ser uma consulta indevida, e não uma alteração irreversível.
• Cada ferramenta deve ter um propósito único, nome claro e retorno enxuto, pensado para o modelo e não para uma tela.
• A autenticação deve carregar a identidade de quem pede, e o escopo deve ser o mínimo necessário para o caso de uso.
• Escrita só entra depois de piloto, logs revisados e aprovação humana desenhada para as ações de maior risco.

O que é um servidor MCP e quando faz sentido criar um

O Model Context Protocol é um padrão aberto que permite a aplicações de IA se conectarem a fontes de dados e ferramentas externas de forma uniforme. Na prática, o servidor MCP é um programa seu que fica entre o assistente de IA e o sistema interno (ERP, CRM, sistema de chamados, base de contratos). Ele declara quais ferramentas existem, o que cada uma recebe e o que devolve.

Faz sentido criar um quando o mesmo sistema precisa ser consultado por assistentes diferentes, ou quando você quer um ponto único para aplicar regras de acesso, registro e limites. Se a necessidade é pequena e de uma pessoa só, um script local pode bastar. Se várias pessoas e várias ferramentas de IA vão depender do acesso, o servidor MCP vira uma fronteira de segurança, e é isso que justifica o cuidado de desenhá-lo bem.

Um ponto importante: o servidor MCP não é só um adaptador técnico. Ele decide o que a IA pode enxergar e fazer dentro da empresa. Por isso o desenho das permissões vem antes do código.

Por que começar com ferramentas somente leitura

A razão é simples: limitar o dano. Uma ferramenta de leitura que erra devolve informação errada ou indevida, o que é ruim, mas recuperável. Uma ferramenta de escrita que erra pode cancelar um pedido, alterar um cadastro ou disparar uma cobrança, e desfazer isso custa tempo, dinheiro e confiança.

Começar por leitura traz outros benefícios práticos:

• Você descobre quais perguntas as pessoas realmente fazem antes de decidir quais ações automatizar.
• A revisão de segurança é mais curta, porque o conjunto de riscos é menor.
• Os logs de uso mostram onde a automação ajuda e onde o processo tem lacunas.
• Quem aprova o projeto (TI, jurídico, encarregado de dados) tem menos resistência a um acesso que não altera nada.

Leitura também não é isenta de risco. Dados pessoais de clientes e funcionários continuam sujeitos à LGPD, e uma ferramenta que devolve campos demais é um vazamento esperando para acontecer. Somente leitura reduz a gravidade, mas não dispensa autenticação, escopo e registro. Para o tratamento de dados no contexto de atendimento, vale ler também o guia sobre LGPD no WhatsApp com IA: consentimento, base legal e registro.

Como desenhar ferramentas de leitura que o modelo usa bem

Uma ferramenta MCP é lida por um modelo de linguagem, não por um programador. O nome, a descrição e os parâmetros são a interface. A Anthropic publica orientações sobre isso em Writing effective tools for agents, e os princípios se resumem bem ao seguinte.

Primeiro, uma ferramenta por intenção. Em vez de uma ferramenta genérica que executa qualquer consulta, crie ferramentas como consultar_status_pedido, buscar_cliente_por_documento ou listar_chamados_abertos_do_cliente. Ferramentas estreitas são mais fáceis de entender, de testar e de proteger.

Segundo, parâmetros explícitos e validados. Defina tipos, formatos e limites no servidor. Se o identificador de pedido tem um formato conhecido, rejeite o que não o respeita. Nunca aceite SQL, caminhos de arquivo ou filtros livres vindos do modelo e os repasse direto ao banco.

Terceiro, retorno enxuto. Devolva só os campos necessários para responder à pergunta, com nomes legíveis. Retornos enormes gastam contexto, confundem o modelo e ampliam a exposição de dados. Se a lista pode ser longa, pagine e limite o número de itens por chamada.

Quarto, mensagens de erro úteis. Quando algo falha, diga o que o chamador pode corrigir (formato inválido, registro não encontrado, sem permissão), sem expor detalhes internos como stack trace ou nome de tabela.

Quinto, descrições honestas. Diga na descrição o que a ferramenta faz e o que não faz. Isso reduz chamadas erradas e ajuda quem revisa o servidor depois.

Por fim, trate o conteúdo que volta do sistema como dado não confiável. Um campo de observação de cliente ou o texto de um chamado pode conter instruções escritas por terceiros, e o modelo pode tentar segui-las. O guia da OWASP sobre prevenção de prompt injection descreve esse risco e as defesas. Por isso, mesmo uma ferramenta somente leitura não deve ser combinada, no mesmo agente, com ferramentas que enviam mensagens ou escrevem em outros sistemas sem controle.

Autenticação e escopo mínimo: o que decidir antes de codar

Esta é a parte que mais separa um experimento de algo que pode ir para produção. Há quatro decisões a tomar.

Quem está pedindo? O servidor precisa saber a identidade real da pessoa ou do serviço que originou a chamada. Se todo mundo usa uma única credencial compartilhada, você perde rastreabilidade e não consegue aplicar regras por usuário. Para acesso remoto, o MCP prevê autorização baseada em OAuth; consulte a especificação vigente do protocolo para o fluxo recomendado e, se precisar de uma base conceitual, a documentação de OAuth 2.0 do Google explica o modelo de autorização.

O que essa identidade pode ver? Aplique a autorização no servidor, a cada chamada, e não apenas na tela do assistente. A folha de referência de autorização da OWASP recomenda princípios como menor privilégio, negar por padrão e verificar permissão em toda requisição. Isso vale aqui sem adaptação.

Que credencial o servidor usa para falar com o sistema interno? Crie uma conta de serviço dedicada, com permissão apenas de leitura nas tabelas ou endpoints necessários. Evite reaproveitar um usuário administrador. Guarde segredos em um cofre ou variáveis de ambiente protegidas, nunca no repositório nem na descrição das ferramentas.

O que fica registrado? Grave quem chamou, qual ferramenta, quais parâmetros, quando e com que resultado (sucesso, erro ou negado). Não registre o conteúdo sensível devolvido, só o necessário para auditoria. Conceitos de observabilidade, como traços e métricas, estão bem explicados no primer de observabilidade do OpenTelemetry.

Se o servidor for acessado por times que usam agentes de código, os mesmos princípios de permissão e isolamento aparecem em Segurança no Claude Code para empresas: permissões, sandbox e segredos.

Passo a passo para criar o primeiro servidor

Um roteiro enxuto, em ordem:

• Escolha um fluxo real e uma pergunta frequente. Exemplo: o time de atendimento precisa saber o status de um pedido sem abrir três telas.
• Liste os dados mínimos para responder essa pergunta. Cada campo fora da lista fica de fora do retorno.
• Defina a conta de serviço somente leitura e teste, fora do MCP, que ela realmente não consegue escrever.
• Escolha o SDK oficial da linguagem que sua equipe já mantém e o transporte adequado: local para testes de desenvolvimento, remoto com autenticação para uso compartilhado.
• Implemente de uma a três ferramentas estreitas, com validação de parâmetros, limite de itens e erros claros.
• Aplique a autorização por usuário dentro de cada ferramenta, antes de consultar o sistema.
• Ative o registro de chamadas desde o primeiro dia, com identificador de usuário, ferramenta e resultado.
• Teste com perguntas reais, inclusive as ruins: identificadores inexistentes, usuários sem permissão, textos com instruções maliciosas nos campos.
• Faça uma revisão de segurança curta com quem responde por TI e por dados pessoais antes de liberar a outras pessoas.
• Libere para um grupo pequeno, acompanhe os logs por um período combinado e só então decida o próximo passo.

Cenário ilustrativo: status de pedidos em um sistema de gestão

Cenário ilustrativo: uma distribuidora tem um sistema de gestão antigo e um time de atendimento que responde dúvidas de clientes pelo WhatsApp. A dor é repetida: perguntar onde está o pedido exige consultar o sistema, o transportador e a nota fiscal.

O servidor MCP do piloto expõe só duas ferramentas: consultar_status_pedido, que recebe o número do pedido e devolve situação, data prevista e transportadora, e listar_pedidos_recentes_do_cliente, que devolve no máximo um pequeno número de pedidos. Nenhuma devolve preço negociado, margem, endereço completo ou dados de pagamento.

A autenticação identifica a atendente, e o servidor só retorna pedidos da carteira que ela atende. A conta de serviço no banco só tem leitura nas visões necessárias. Cada chamada fica registrada. Depois de algumas semanas, o time revisa os logs e percebe quais perguntas aparecem mais e quais ferramentas nunca são usadas. Só então discute, com aprovação humana, se vale uma ferramenta que abre solicitação de segunda via de nota, algo de escrita e de risco maior.

Para quem pretende ligar esse tipo de consulta a atendimento no WhatsApp, o guia Como integrar IA no WhatsApp da sua empresa mostra o outro lado da integração, e o conteúdo sobre transbordo humano trata do que fazer quando a IA não deve responder sozinha.

Como medir o piloto e quando liberar ferramentas de escrita

O método que aplicamos em projetos de IA segue quatro movimentos: mapear, limitar, pilotar e transferir. Aplicado a um servidor MCP, fica assim.

Mapear: descrever o processo atual, quem consulta o quê, em qual sistema e quanto tempo isso toma hoje. Sem esse ponto de partida, não há como saber se o servidor ajudou.

Limitar: restringir dados, ferramentas e ações. É a etapa de leitura, escopo mínimo e conta de serviço dedicada descrita acima.

Pilotar: rodar um fluxo real, com logs e uma métrica de sucesso combinada antes. Pode ser tempo de resposta do time, taxa de perguntas resolvidas sem abrir o sistema ou número de correções feitas por humanos. O artigo sobre como medir um piloto de automação com IA detalha métricas e pontos de decisão.

Transferir: entregar a documentação, os acessos, o plano de monitoramento e a decisão de expandir, ajustar ou parar. Parar também é um resultado válido quando o piloto mostra que o ganho não compensa.

Sobre escrita, use um critério simples antes de liberar qualquer ferramenta que altera dados:

• A ação é reversível ou existe um jeito claro de desfazer?
• Há aprovação humana para ações de maior impacto, com registro de quem aprovou?
• A ferramenta é idempotente, ou seja, repetir a chamada não duplica o efeito?
• O escopo da credencial cobre apenas essa ação e nada além?
• Os logs do piloto de leitura mostram demanda real por essa ação?

Se alguma resposta for não, a ferramenta continua fora do servidor. Para estruturar as aprovações, o modelo de política de aprovação para agentes de IA é um bom ponto de partida.

Perguntas frequentes

Preciso saber programar para criar um servidor MCP? Sim, ao menos alguém da equipe precisa. Os SDKs oficiais reduzem o trabalho de protocolo, mas você ainda escreve as ferramentas, a validação, a autorização e a integração com o sistema interno. Se a empresa não tem time técnico, vale contratar apoio para o desenho e manter a responsabilidade pelas decisões de acesso.

Servidor MCP local ou remoto: qual escolher? Local serve para desenvolvimento e para uso individual, quando o servidor roda na máquina de quem o usa. Para uso compartilhado por uma equipe, o servidor remoto permite autenticação central, registro e controle de versões, mas exige mais cuidado com exposição de rede e autorização. Se for expor um serviço na internet, passe por uma revisão como a do checklist de segurança do OpenClaw Gateway, que trata de evidência antes da exposição.

Somente leitura já é seguro o bastante? Não por si só. Leitura reduz a gravidade dos erros, mas dados pessoais continuam protegidos pela LGPD e o conteúdo lido pode carregar instruções maliciosas. Autenticação por usuário, escopo mínimo, retorno enxuto e registro de chamadas continuam obrigatórios. Para dúvidas sobre tratamento de dados, consulte o encarregado da empresa e o material da ANPD.

Quando faz sentido adicionar ferramentas que escrevem? Quando o piloto de leitura mostrou demanda clara, os logs estão sendo revisados e existe um desenho de aprovação humana para as ações de maior risco. Comece pela ação menos crítica e reversível, com credencial própria e limites explícitos. Se não houver como desfazer o efeito, mantenha a ação com um humano.

Fontes

• Model Context Protocol: introdução
• Anthropic: Writing effective tools for agents
• OWASP: Authorization Cheat Sheet
• OWASP: LLM Prompt Injection Prevention Cheat Sheet