Servidor MCP — /mcp-tokens

O CMS publica um servidor MCP (Model Context Protocol): um endereço que um assistente de IA — Claude Desktop, Claude Code, ou qualquer cliente que fale o protocolo — usa para ler e configurar integrações, conversando com o sistema em vez de conversar sobre ele.

Na prática, o que era “abra a tela de Aplicações, crie uma Interface, depois uma Entrega, escolha o tipo, preencha os campos obrigatórios daquele tipo” passa a ser uma frase: “crie uma entrega HTTP POST para o MES na aplicação SAP, validando o retorno”. A IA descobre o que existe, monta o plano, confere e aplica.

O que o token é, e o que não é

A decisão central: um token MCP não tem permissões próprias. Ele aponta para um usuário de serviço, e é o Perfil desse usuário que decide tudo — quais ferramentas a IA enxerga, quais Aplicações e Interfaces ela alcança, o que ela pode alterar.

O mesmo token pode ainda chamar as ferramentas do Servidor MCP de integrações — enviar por uma Entrega, executar uma Coleta —, mas só se o Perfil tiver também a Ferramenta /mcp/integration-tools. Configurar uma Entrega e acioná-la são permissões separadas.

Criar um token

{
  "mcpServers": {
    "cms": {
      "type": "http",
      "url": "https://seu-cms/api/mcp",
      "headers": { "Authorization": "Bearer cms_mcp_..." }
    }
  }
}

O valor começa com cms_mcp_ de propósito: quem encontrar a string num arquivo de configuração sabe de onde ela é, e uma varredura por cms_mcp_ acha token vazado em repositório.

O que a IA consegue fazer

As ferramentas são filtradas pelo Perfil do usuário de serviço antes de serem oferecidas — a IA não enxerga uma ferramenta que levaria 403 ao chamar. Por isso o mesmo servidor se comporta de formas diferentes conforme o token.

Ler

cms_describe_types é a peça que evita a maior parte dos erros: sem ela o modelo chuta valor de enum e nome de campo; com ela, consulta o contrato antes de montar qualquer coisa.

Diagnosticar

cms_search_messages devolve metadados — id, status, datas, tentativas. O corpo só sai se o token tiver a permissão de conteúdo ligada, e payload criptografado nunca sai, com ou sem essa permissão: decifrar exige a Ferramenta própria, com justificativa e reautenticação, e está fora do alcance do MCP.

cms_screen_link não devolve dado: devolve para onde olhar. É o caminho barato de responder “essa mensagem passou?” — a contagem sai de uma consulta só, o conteúdo não entra na resposta, e a lista de telas alcançáveis é fechada. Cada tela é conferida contra a permissão do token antes de o endereço sair. O caminho vem relativo: quem sabe o endereço público da instalação é quem a hospeda, não a API.

Para janelas relativas a agora, cms_screen_link aceita periodo (hoje, ontem, 1h, 24h, 7d…) no lugar de dataInicio/dataFim: o endereço leva o atalho, e a tela resolve as datas a cada consulta.

Testar antes de gravar

cms_test_read recusa, explicando, o que teria efeito colateral: Coleta com comando pós-coleta, ação pós-leitura de arquivo, RFC que pode escrever, e os tipos orientados a evento — que não têm o que ler sob demanda.

Criar e alterar

cms_create_* e cms_update_* cobrem Aplicação, Interface, Entrega, Coleta, Erro de Negócio e Conexão Externa. Criar uma Aplicação cuja sigla já existe não duplica: devolve a existente, marcada como já existente.

Para uma integração inteira de uma vez, o caminho é outro:

Documentação e roteiro embutidos

Além das ferramentas, o servidor publica resources — conteúdo que o cliente lê uma vez e mantém no contexto:

• cms://catalog/types — o mesmo catálogo de cms_describe_types
• cms://docs/como-criar-integracao — o que é Aplicação, Interface, Definição e Erro de Negócio, e em que ordem criar
• cms://docs/direcao-e-tipos — por que quem inicia a conversa decide entre ENTREGA e COLETA

E um prompt pronto, configurar_integracao, que o cliente oferece como comando: você descreve o objetivo em uma frase e ele conduz o roteiro até a validação e a pré-visualização.

Por que é seguro deixar uma IA aqui

• Segredo não sai. Cada resposta é montada campo a campo, por lista de permitidos — senha, token e chave privada não estão nessa lista. Por cima disso, uma varredura final percorre a resposta inteira, inclusive mensagens de erro, e corta o que casar com padrão de segredo. Se essa rede precisar agir, o incidente é registrado.
• Conteúdo cifrado não sai, em nenhuma hipótese, nem com a permissão de conteúdo ligada.
• Nada é criado ligado. Entregas e Coletas nascem desativadas.
• Nada se expõe sozinho. As chaves que abrem uma saída de dado — Expor como ferramenta MCP, Devolver o conteúdo coletado para a IA e Devolver o resultado da coleta na resposta da API — só são ligadas por uma pessoa, na tela. As ferramentas de criar e alterar, e o cms_apply_integration, recusam ligá-las; desligar continua permitido.
• Tudo passa pelo Perfil. As mesmas checagens de Ferramenta e de Interfaces permitidas que valem na tela valem aqui, no mesmo código.
• Tudo fica na auditoria, com o login do usuário de serviço.

Revogar

Na lista, Revogar desliga o token na hora sem apagá-lo — o histórico de uso continua legível. Excluir remove o registro, e qualquer cliente que estivesse usando aquele valor perde o acesso imediatamente. Um token com data de expiração passada para de autenticar sozinho.

O token também vale só enquanto o usuário de serviço vale: desativar o usuário derruba todos os tokens dele na hora, sem esperar a expiração — como acontece com a sessão de tela de um usuário desativado.

A coluna Último uso é a forma rápida de achar token esquecido: o que nunca foi usado, ou não é usado há meses, provavelmente não deveria continuar existindo.

Desligar o servidor inteiro

Para fechar a porta de uma vez, sem mexer em token nenhum, desligue o recurso Servidor MCP em Configurações → IA: a partir daí nenhum token é aceito.

A recusa acontece depois da validação do token, de propósito — quem chamasse sem credencial descobriria que o servidor existe e está desligado, e a resposta única para token ausente/inválido/expirado/revogado perderia a graça.

Permissão da tela

A Ferramenta é /mcp-tokens. Quem a tem consegue criar e revogar tokens — ou seja, consegue conceder a uma IA o acesso de qualquer usuário de serviço disponível. Trate-a com o mesmo cuidado de Perfis de Acesso, e não a inclua em perfis operacionais.