Pular para o conteúdo
ZaiaZaiaZaia

Operar o workspace via MCP da Zaia

O MCP da Zaia é o servidor MCP first-party da Endless. Um cliente MCP (ChatGPT, Cursor, Claude ou similar, com transporte HTTP streamable) opera um workspace por conexão: monta agentes, consulta analytics, ajusta canais, conhecimento, tabelas e o restante da configuração que você já controla no Console.

Isso é o caminho inverso dos MCPs que o Agente consome no Builder. Os guias O que são MCPs?, Como Conectar um Novo MCP e Como Cadastrar um MCP Customizado continuam válidos para integrações dentro do workspace (Google Calendar, Notion, Slack, servidor MCP seu).

Antes de conectar

Seção intitulada “Antes de conectar”
  1. Entre no workspace no Console.
  2. Vá em Configurações → Integrações → Chaves de API (recurso em beta).
  3. Clique em Nova Chave de API, dê um Nome e copie a chave. Ela identifica só aquele workspace — guarde como segredo.

O MCP não cria chave de API. Use uma chave que já exista no workspace.

URL e autenticação

Seção intitulada “URL e autenticação”
Campo Valor
URL do servidor https://api.endless.zaia.app/api/v1/mcp
Autenticação Header Authorization com o UUID da chave cru ou Bearer <uuid>

O workspace vem sempre da chave. O cliente não escolhe workspace em argumentos de tool.

Exemplo para Cursor (mcp.json ou configuração equivalente):

{
  "mcpServers": {
    "zaia": {
      "url": "https://api.endless.zaia.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <sua-chave-de-api-do-workspace>"
      }
    }
  }
}

ChatGPT e Claude Desktop seguem o mesmo URL e header quando o produto expõe MCP remoto por HTTP streamable.

Primeira chamada: explain_zaia

Seção intitulada “Primeira chamada: explain_zaia”

Depois de conectar, peça ao cliente para chamar a tool explain_zaia antes de criar ou alterar recursos. Ela devolve guias por tópico, com ordem sugerida de leitura e escrita.

Tópicos disponíveis:

  • overview — modelo do workspace (padrão se você omitir o tópico)
  • agent, squad, tool, channel, kanban, knowledge, table, tag, automation
  • workflow — fluxos de trabalho (beta)
  • insights, dashboard, deploy

O fluxo típico: explain_zaia → listar o que já existe (list_agents, list_tools, …) → criar ou atualizar no rascunho quando aplicável → publicar com confirmação explícita quando o operador concordar.

Rascunho, publicação e recursos ao vivo

Seção intitulada “Rascunho, publicação e recursos ao vivo”

Parte da configuração fica em rascunho até você publicar; outra parte vale na hora.

Rascunho (clientes veem produção só depois da publicação)

  • Agentes — criar, editar, arquivar e desarquivar no draft; prompts condicionais são tasks do agente (list_tasks, create_task, update_task com name, condition e prompt).
  • Squads — montar time e vincular agentes.
  • Tools do Console (inclusive Chat Tagging com detail.type chat-tagging e tags já existentes no workspace).
  • Publicação de agente, squad e tool: deploy_version com confirm: true. list_versions mostra rascunho e produção.

Ao vivo (sem passo de publicação de versão)

  • Canais, tags, bases e itens de conhecimento, tabelas e views de kanban (criar e editar metadados da view; o MCP não move cards nem abre o board ao vivo).
  • Automações do Console — nascem inativas; você liga com update_automation (active ou inactive).

Workflows (beta)

Grafo separado dos agentes: create_workflow, update_workflow_graph, deploy_workflow com confirm: true, depois activate_workflow. Publicação de workflow não usa deploy_version.

Leitura e análise

Seção intitulada “Leitura e análise”
  • Dashboards — list_dashboard_scope e generate_dashboard montam série e métricas para o período pedido (série horária até 7 dias; período total até 180 dias, sem data futura). O layout salvo no Console não é alterado.
  • Insights — list_chats, list_insights, estimate_insights e create_insights (com confirmationToken após a estimativa). A análise roda como owner do workspace; créditos seguem a cota de Insights do Console.

Relação com a API REST

Seção intitulada “Relação com a API REST”

O MCP usa a mesma credencial de workspace que a Developer Platform API (/api/v1). A API REST permanece alpha — sujeita a mudanças. Preferir o MCP quando o operador for um assistente de IA com catálogo de tools; preferir REST quando você controla o código da integração.

Para versionamento e rollback no Console, veja Versionamento (agentes, squads, tools e MCPs do catálogo).

Próximos passos

Seção intitulada “Próximos passos”