Servidor MCP de integrações

Além do Servidor MCP de configuração — que deixa uma IA ler e configurar integrações —, o CMS publica um segundo servidor MCP, o de integrações: ele expõe Entregas e Coletas que você marcar como ferramentas (tools, no vocabulário do protocolo) que um agente de IA chama para enviar dados para dentro do CMS ou buscar dados através dele.

A diferença importa: o servidor de configuração monta integrações; o de integrações usa as que já existem. Uma Entrega vira uma ferramenta “envie isto para o MES”; uma Coleta vira “consulte o estoque no ERP”. O agente não precisa conhecer a URL, a autenticação nem o formato — ele preenche os campos que a ferramenta declara, e o CMS faz o resto pelo mesmo caminho de qualquer produtor.

O endereço é por Aplicação

Cada Aplicação tem o seu endereço:

POST https://SEU-CMS/api/mcp/applications/{SIGLA}

Ele lista só as Entregas e Coletas daquela Aplicação que estão marcadas e que a credencial enxerga. O servidor de configuração (/api/mcp) continua separado — uma API Key de sistema externo nunca alcança as ferramentas de criar/configurar.

Quem pode chamar

Três credenciais, as mesmas que já enviam dados ao CMS — nenhuma nova a distribuir:

O token MCP de usuário exige ainda, no Perfil do usuário de serviço, a Ferramenta /mcp/integration-tools — na tela de Perfis ela aparece como MCP Integration Tools. Poder editar uma Entrega não é poder acioná-la para escrever num equipamento ou ERP. E o token vale enquanto o usuário vale: desativar o usuário de serviço derruba o token dele na hora, sem esperar a expiração.

Expor uma Definição

A descrição sugerida pela IA

Escrever uma boa descrição é a parte difícil: é ela que faz o agente escolher a ferramenta certa. O botão de sugestão entrega um rascunho a partir do que está gravado na Definição — por isso ele só funciona depois do primeiro salvamento, e fica desligado, com a explicação, até lá.

O modelo recebe as descrições da Aplicação e da Interface, os parâmetros (e quais são obrigatórios), se a Coleta devolve conteúdo, o modo da Entrega e se ela escreve em equipamento. Nunca recebe credencial nem dados da conexão. O texto volta no idioma da tela, com até 600 caracteres — a descrição vai em toda listagem de ferramentas, e texto longo custa a cada chamada.

A sugestão entra no campo com um Desfazer ao lado, e só vale depois que alguém revisa e salva. Depende da IA configurada e do recurso Descrição de ferramenta MCP por IA, em Configurações › IA; com um dos dois desligado, o botão diz por quê. Cada sugestão fica no Log de Auditoria.

Conectar via MCP

O popup Conectar via MCP mostra o endereço, o cabeçalho de autenticação e um exemplo de configuração para colar no cliente:

{
  "mcpServers": {
    "cms-MES": {
      "url": "https://SEU-CMS/api/mcp/applications/MES",
      "headers": { "Authorization": "Bearer <seu-token>" }
    }
  }
}

Ele abre de três lugares:

O segredo nunca aparece no popup: o exemplo traz um marcador, e quem configura cola o valor que já tem em mãos — pelo botão Copiar da própria tela, que registra quem copiou.

O que a ferramenta devolve

Os argumentos são o contrato de entrada da Definição: os Parâmetros de Entrada da Coleta, o Payload de Entrada da Entrega. Uma Entrega sem contrato de entrada recebe o corpo da mensagem pronto, num argumento único, corpo, no Content-Type da Definição.

Como os argumentos já chegam no formato da Entrega, a ferramenta não passa pelo Transformador por Aplicação produtora — nem quando é chamada com a API Key de uma produtora que tem um. Só o Transformador da própria Entrega roda.

A ferramenta fixa cms_message_status mostra a situação das mensagens que aquela credencial enviou por MCP — status, tentativas, datas.

O status vem em inglês

Nas telas, o status de uma mensagem continua em português (NAO_PROCESSADA, ERRO_ENTREGA…). Na resposta do MCP ele vira um valor estável em inglês, com uma frase curta, situacao, que o agente repassa no idioma de quem perguntou:

O agente do outro lado atende gente em qualquer idioma: um NAO_PROCESSADA cru acabava repetido tal e qual para o usuário.

Servidores MCP — /mcp-servers

Toda Aplicação com ao menos uma Entrega ou Coleta marcada como ferramenta é um servidor MCP, com endereço próprio. Esta tela, em Config. de Integração logo depois de Gatilhos, reúne esses servidores e as ferramentas de cada um. As duas telas ficam lado a lado porque respondem à mesma pergunta: quem mais dispara esta Coleta ou Entrega, além do sistema de origem — o agendador interno ou um agente de IA.

Cada Aplicação é um bloco que expande — sozinho quando só há uma, ou quando há uma busca ativa. O cabeçalho conta as ferramentas ativas, as inativas e as chamadas. Aberto, o bloco mostra o endereço MCP com botão de copiar, o Conectar via MCP e uma linha por ferramenta:

O ícone da linha abre o contrato de entrada. Nome, descrição, limite e parâmetros continuam sendo editados no cadastro da Definição — esta tela responde “o que a IA pode chamar agora”.

A tela abre em Ativas. As desligadas ficam em Inativas e Todas — é ali que se religa uma ferramenta sem abrir o formulário. Dá para filtrar por uma ou mais Aplicações, e a busca procura por ferramenta, descrição, Definição, Interface ou Aplicação.

Ligar e desligar por aqui

Ligar ou desligar nesta tela é o mesmo que marcar ou desmarcar a chave no cadastro, e a mudança entra no histórico de alterações da Definição. A confirmação diz o efeito antes: ao desligar, a ferramenta some para os agentes e as chamadas passam a ser recusadas, mas nome, descrição e parâmetros continuam gravados. Ao ligar uma Entrega, o aviso lembra que o agente poderá enviar mensagens por ela até o destino.

Ligar reaplica as mesmas validações do formulário — nome, descrição, limite, parâmetros, nome único na Aplicação. Uma Coleta sem Parâmetros de Entrada é recusada: ela nunca apareceria para a IA.

Uma ferramenta ativa pode, mesmo assim, estar invisível para o agente. A linha avisa Não aparece para a IA e diz por quê: a Definição está inativa, ou a Coleta não tem Parâmetros de Entrada.

O que conta como chamada

Cada chamada (tools/call) que chega à ferramenta conta uma vez, separada por credencial — API Key, Credencial de Entrada ou token MCP. Chamada recusada por argumento inválido ou pelo limite por minuto conta como falha, assim como a Entrega que o destino recusou.

O contador é próprio, e não uma contagem de mensagens: a mensagem some com a retenção da Interface, e uma Coleta gera várias mensagens numa chamada só. Ele começou a contar na versão que trouxe esta tela — chamadas anteriores não aparecem.

O contrato de entrada

O popup de contrato mostra o que o agente recebe ao listar as ferramentas: o comportamento (Entrega síncrona ou assíncrona, Coleta com ou sem devolução de conteúdo), e uma linha por parâmetro, com tipo, obrigatório, valor padrão, restrição (faixa ou lista de valores) e a descrição para a IA. Ver o JSON Schema enviado à IA mostra o inputSchema exato — o mesmo que o servidor entrega no tools/list, e não uma reconstrução.

Permissão

A tela tem Ferramenta própria, Servidores MCP (/mcp-servers), com dois níveis: consultar e ligar/desligar. A lista respeita as Interfaces permitidas do usuário, e ligar uma ferramenta de Interface que ele não enxerga é recusado. Numa instalação nova, o perfil CMS_Developer já vem com o nível de edição — quem constrói a integração já liga a ferramenta pelo formulário; aqui é o mesmo campo, em lote.

Onde a chamada aparece depois

• Nas telas de Mensagens, a mensagem criada por uma ferramenta MCP leva um ícone de robô violeta — na grade, no popup e na página da mensagem —, com o nome da ferramenta e da credencial ao passar o mouse.
• No botão Configurações da Definição, a aba API Keys ganha a linha Exposta como ferramenta MCP, com o nome e o endereço.

Segurança

• Marcação humana, por Definição. Nada é ferramenta sem alguém marcar; escrita física pede confirmação ao salvar.
• Validação antes de a mensagem existir. Alias desconhecido, obrigatório faltando ou valor fora da faixa configurada viram erro para o agente corrigir, sem criar mensagem.
• Limite por minuto por ferramenta e credencial.
• Escopo pela credencial. A ferramenta nunca dá mais acesso do que a credencial já tem pela API. Dá para ter uma API Key só de leitura e outra só de escrita — recomendado para escrita física.
• Segredo nunca sai, e conteúdo cifrado nunca é decifrado para o agente. A varredura de segredo roda antes de a resposta virar texto, e não só na versão estruturada dela.

Ligar e desligar o servidor

Em Configurações › IA, a chave Servidor MCP de integrações liga ou desliga o endereço inteiro, separada da chave do servidor de configuração. Vem ligada — como nada fica exposto sem marcar uma Definição, o controle real é a marcação. Com ela desligada, a tela Servidores MCP mostra uma faixa avisando que nenhuma ferramenta responde até o servidor ser religado.