Ferramentas próprias (MCP)

5 min de leituraAtualizado em 29 out. 2026

Os agentes de IA da Atalia usam ferramentas para consultar e agir em outros sistemas durante a conversa: ver um pedido, achar um horário livre, gerar uma cobrança. A Atalia já traz várias prontas (agenda, catálogo, base de conhecimento). Para ligar o seu sistema, você publica um servidor MCP (Model Context Protocol) e cadastra na Atalia. Cada função do servidor vira uma ferramenta que o agente pode chamar.

Exemplos do que dá para fazer:

O cliente pergunta	A ferramenta	O que o agente faz
"Meu pedido já saiu?"	`consultar_pedido` no seu ERP	Responde com o status e a previsão de entrega
"Tem horário amanhã de manhã?"	`horarios_livres` na sua agenda	Manda a lista de horários para o cliente escolher
"Quero pagar"	`gerar_cobranca` no seu gateway	Envia o Pix nativo do WhatsApp e marca a conversa
"Quero a segunda via"	`segunda_via_boleto` no seu financeiro	Envia o PDF e o botão "Baixar boleto"

As ferramentas funcionam nos agentes de IA do painel. Na integração via API a Atalia não responde ninguém, então não há agente para chamá-las.

1. O que o servidor precisa responder

A Atalia é cliente MCP por HTTP (Streamable HTTP, JSON-RPC 2.0, protocolo 2024-11-05). O servidor fica num único endereço https:// e responde a quatro métodos:

Método	O que devolver
`initialize`	`protocolVersion`, `capabilities` e `serverInfo`
`notifications/initialized`	Nada: é uma notificação (sem `id`). Responda `202` ou `204`.
`tools/list`	`{ "tools": [ { "name", "description", "inputSchema" } ] }`
`tools/call`	`{ "content": [ { "type": "text", "text": "..." } ] }`, com `isError` e `structuredContent` opcionais

A resposta pode vir como application/json ou text/event-stream: a Atalia entende os dois.
Se o servidor devolver o header Mcp-Session-Id, ele é reenviado nas chamadas seguintes.
Servidor sem estado (stateless) funciona bem: cada chamada traz tudo o que precisa.

Exemplo mínimo

Um servidor com uma ferramenta, num Cloudflare Worker. O mesmo vale para Node, Python, PHP: é só JSON por HTTP.

const TOOLS = [
  {
    name: 'consultar_pedido',
    description: 'Consulta o status e a previsão de entrega de um pedido pelo número. Use quando o cliente perguntar sobre um pedido.',
    inputSchema: {
      type: 'object',
      properties: { numero: { type: 'string', description: 'Número do pedido, ex.: 1042' } },
      required: ['numero'],
    },
  },
];

export default {
  async fetch(request, env) {
    if (request.headers.get('Authorization') !== `Bearer ${env.MCP_TOKEN}`) return new Response('Unauthorized', { status: 401 });
    const { id, method, params } = await request.json();
    if (id === undefined) return new Response(null, { status: 202 }); // notificação

    const reply = (result) => Response.json({ jsonrpc: '2.0', id, result });
    if (method === 'initialize') {
      return reply({ protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'minha-loja', version: '1.0.0' } });
    }
    if (method === 'tools/list') return reply({ tools: TOOLS });
    if (method === 'tools/call' && params.name === 'consultar_pedido') {
      const pedido = await buscarPedido(params.arguments.numero); // o seu sistema
      const payload = pedido
        ? { success: true, data: { numero: pedido.numero, status: pedido.status, previsao: pedido.previsao } }
        : { success: false, message: 'Pedido não encontrado' };
      return reply({ content: [{ type: 'text', text: JSON.stringify(payload) }] });
    }
    return Response.json({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Método não encontrado' } });
  },
};

2. Cadastrar na Atalia

Em Automações › MCP Servers, clique em Novo MCP customizado.
Informe o endereço do servidor e a autenticação: Bearer, chave de API, OAuth ou nenhuma. Se precisar, acrescente cabeçalhos extras.
Clique em Testar conexão: a Atalia chama initialize e tools/list e mostra as ferramentas encontradas. Salve.
No agente de IA (Automações › Agentes de IA), ative as ferramentas que ele pode usar. Em cada parâmetro dá para usar Valor fixo, para o agente não precisar preencher.
Mudou as ferramentas no servidor? Abra o MCP e clique em Sincronizar ferramentas.

3. Descrever bem as ferramentas

A IA escolhe a ferramenta e preenche os parâmetros lendo o name, a description e o inputSchema. Uma boa descrição vale mais que instrução no prompt.

Nome curto e claro, em snake_case: consultar_pedido, horarios_livres.
Descrição que diz quando usar, não só o que faz: "Use quando o cliente perguntar sobre um pedido."
Cada parâmetro com description e exemplo de formato ("data no formato AAAA-MM-DD").
Poucos parâmetros. O que a ferramenta consegue descobrir sozinha (o telefone do cliente, a empresa), não peça à IA.
O inputSchema é convertido para o formato estrito dos modelos (additionalProperties: false): não dependa de campos extras fora do schema.

4. O resultado da ferramenta

O que você devolve em content[].text é o que a IA lê para responder. Pode ser texto ou JSON. Se você mandar structuredContent (MCP 2025-06-18), ele vale no lugar do texto.

Falha de transporte (o servidor caiu, deu exceção): isError: true.
Falha de negócio (pedido não existe, gateway recusou): devolva "success": false com uma message. A Atalia reporta a ferramenta como falha, e a IA explica ao cliente.

{ "success": false, "message": "Pedido não encontrado" }

Devolva o que a IA precisa para responder bem: status em português, datas legíveis, valores já formatados. Evite despejar o registro inteiro do banco.

Além do texto: a chave `atalia`

O resultado também pode pedir que a Atalia faça algo, sem a IA precisar escrever:

Chave	O que faz	Página
`atalia.send`	Envia ao cliente um elemento nativo: Pix, botões, lista, carrossel, mídia, link, localização, contato	Enviar elementos nativos
`atalia.final`	Encerra a vez da IA quando o envio já respondeu o cliente	Enviar elementos nativos
`atalia.status`, `atalia.tags`	Muda o status e as tags da conversa	Mudar a conversa e registrar conversões
`event`	Registra um evento de conversão (compra, lead qualificado)	Mudar a conversa e registrar conversões

Tudo é opcional e aditivo: resultado sem essas chaves continua funcionando como antes.

Onde as ferramentas valem

Onde	Ferramentas	Elementos nativos e mudanças na conversa
Agente de IA numa conversa	Sim	Sim
Sub-agente	Sim	Sim, enviados em nome do sub-agente
Copilot (sugestão para o atendente)	Sim	Não, de propósito: o texto do Copilot passa pela aprovação de uma pessoa, e enviar sozinho furaria essa revisão

1. O que o servidor precisa responder​

Exemplo mínimo​

2. Cadastrar na Atalia​

3. Descrever bem as ferramentas​

4. O resultado da ferramenta​

Além do texto: a chave atalia​

Onde as ferramentas valem​