Ferramentas - Morada.ai

Visão geral

O servidor MCP morada-platform expõe 14 ferramentas organizadas por domínio. A primeira chamada de qualquer fluxo deve ser list_workspaces para descobrir o workspaceId usado pelas demais.

Domínio	Ferramentas	Escopo
Workspaces	`list_workspaces`	—
Conversas	`list_conversations`, `get_conversation`, `list_conversation_messages`	`conversations:view`
Deals	`list_deals`, `get_deal`	`deals:view`
Agentes	`list_agents`, `get_agent`	`instances:view`
Integrações	`list_integrations`, `get_integration`	`integrations:view`
Analytics	`get_analytics`	`dashboard:view`
Talk Analytics	`get_talk_analytics`	`talk-dashboard:view`
Mensagens	`send_active_message`	`talk:edit`
Templates	`list_message_templates`, `create_message_template`	`message-templates:view` / `message-templates:edit`

Workspaces

`list_workspaces`

Lista todos os workspaces (partners) aos quais o usuário autenticado tem acesso. Primeiro passo de qualquer fluxo — o id retornado aqui é usado como workspaceId em todas as outras tools. Retorno: array de workspaces com id, name e role.

Conversas

`list_conversations`

Lista conversas de um workspace com filtros opcionais por status, intervalo de datas, agente, tags ou busca por pessoa. Resultado paginado. Parâmetros principais: workspaceId, status, dateFrom, dateTo, agentId, tags, search, limit, offset.

`get_conversation`

Retorna os detalhes completos de uma conversa específica: pessoa, agente atribuído, tags, status e timestamps. Parâmetros: workspaceId, conversationId.

`list_conversation_messages`

Lista as mensagens de uma conversa com sanitização automática (imagens são marcadas, mensagens longas são truncadas em 2000 caracteres). Cada mensagem traz um campo category que separa pedido do cliente, resposta da IA, resposta de atendente humano, template e ações internas. Parâmetros: workspaceId, conversationId, dateFrom, dateTo, actor, limit, offset.

Deals

`list_deals`

Lista deals de um workspace com filtros por status (open, won, lost, closed), data de criação e busca por nome ou telefone da pessoa. Parâmetros: workspaceId, status, dateFrom, dateTo, search, limit, offset.

`get_deal`

Retorna o contexto completo de um deal: pessoa, produtos, logs de etapas, rastreio de origem e usuário responsável. Parâmetros: workspaceId, dealId.

Agentes (Mia)

`list_agents`

Lista todos os agentes (bots/instâncias) de um workspace. Retorna id, name, type e partnerId. Parâmetros: workspaceId.

`get_agent`

Retorna a configuração de um agente: tipo, instruções e demais propriedades. Use o parâmetro fields para pedir o valor completo de chaves específicas. Parâmetros: workspaceId, agentId, fields (opcional).

Integrações

`list_integrations`

Lista todas as integrações (partner connections) configuradas em um workspace. Retorna id, connectorCode, active e metadados do conector. Parâmetros: workspaceId.

`get_integration`

Retorna detalhes de uma integração específica: conector, status ativo e propriedades de configuração. Parâmetros: workspaceId, integrationId.

Analytics

`get_analytics`

Retorna KPIs do dashboard para um workspace em um intervalo de datas: volume de conversas, métricas de funil, tempos de resposta e indicadores de atividade de agentes. Parâmetros: workspaceId, from (ISO), to (ISO), timezone (opcional, ex.: America/Sao_Paulo).

`get_talk_analytics`

Retorna as métricas do dashboard do Talk (atendimento humano), uma seção por chamada: kpis (atendimentos criados, tempo até atribuição, tempo até 1ª resposta, tempo médio de atendimento e CSAT, com comparativo do período anterior), tickets-by-day, status-distribution, tickets-by-attendant, times-by-day, csat, attendants, presence-status-history e presence-current. Aceita filtro por fila e por atendentes. A seção queues lista o catálogo de filas do workspace (id, name, status) para resolver nomes em ids; os ids de atendente vêm do campo id da seção attendants. Parâmetros: workspaceId, section, from (ISO, inclusivo), to (ISO, exclusivo), queueIds (opcional, máx. 20), attendantUserIds (opcional, máx. 50).

Mensagens

`send_active_message`

Envia uma mensagem ativa (outbound) no WhatsApp usando um template aprovado pela Meta, via um agente com canal WhatsApp ativo. Cria ou retoma uma conversa com o destinatário.

Operação de escrita que envia uma mensagem real. O assistente deve confirmar telefone, template e variáveis antes de executar.

Parâmetros: workspaceId, agentId, templateName, phoneNumber, recipientName (opcional), email (opcional), replacements (opcional). Retorno: success e conversationId.

Templates de mensagem

`list_message_templates`

Lista os templates do WhatsApp disponíveis para um agente, consultando a Meta Graph API. Retorna nome, status (APPROVED, PENDING, etc.), idioma, categoria e componentes. Parâmetros: workspaceId, agentId, name (filtro opcional).

`create_message_template`

Cria um novo template de mensagem na conta do WhatsApp Business via Meta Graph API.

Operação de escrita. O template entra em revisão da Meta antes de poder ser usado.

Parâmetros: workspaceId, agentId, payload de template no formato esperado pela Meta.

Fluxos recomendados

Investigar uma conversa

list_workspaces
  → list_conversations (com filtros)
    → get_conversation (id específico)
      → list_conversation_messages

Mapear agentes

list_workspaces
  → list_agents
    → get_agent (informações básicas)

Disparar uma mensagem ativa

list_workspaces
  → list_agents (escolher agente com Meta)
    → list_message_templates (escolher template APPROVED)
      → send_active_message
        → get_conversation (acompanhar)

Relatório de período

list_workspaces
  → get_analytics (from / to)
    → list_deals (status=won, dateFrom, dateTo) para drill-down

Boas práticas

Sempre liste antes de agir

Use as ferramentas list_* para descobrir IDs antes de chamar get_*. Isso evita tentativa-e-erro e mantém consistência entre chamadas.

Confirme operações de escrita

Para send_active_message e create_message_template, sempre apresente ao usuário o que será enviado antes de executar.

Reutilize workspaceId

Uma vez descoberto, reutilize o mesmo workspaceId em chamadas subsequentes para evitar trocas de contexto.

Filtre cedo para reduzir tokens

Em listas grandes (conversas, deals), use os filtros de data, status e busca para reduzir o payload retornado.

​Visão geral

​Workspaces

​list_workspaces

​Conversas

​list_conversations

​get_conversation

​list_conversation_messages

​Deals

​list_deals

​get_deal

​Agentes (Mia)

​list_agents

​get_agent

​Integrações

​list_integrations

​get_integration

​Analytics

​get_analytics

​get_talk_analytics

​Mensagens

​send_active_message

​Templates de mensagem

​list_message_templates

​create_message_template

​Fluxos recomendados

​Investigar uma conversa

​Mapear agentes

​Disparar uma mensagem ativa

​Relatório de período

​Boas práticas

Visão geral

Workspaces

`list_workspaces`

Conversas

`list_conversations`

`get_conversation`

`list_conversation_messages`

Deals

`list_deals`

`get_deal`

Agentes (Mia)

`list_agents`

`get_agent`

Integrações

`list_integrations`

`get_integration`

Analytics

`get_analytics`

`get_talk_analytics`

Mensagens

`send_active_message`

Templates de mensagem

`list_message_templates`

`create_message_template`

Fluxos recomendados

Investigar uma conversa

Mapear agentes

Disparar uma mensagem ativa

Relatório de período

Boas práticas