MCP — Conecte assistentes de IA aos dados do DATTA

Qualquer cliente compatível com MCP (Model Context Protocol) passa a consultar os dados do DATTA diretamente, com a mesma autenticação e as mesmas permissões que valem na interface. Seu time já usa assistentes de IA, IDEs como o Cursor ou automações no n8n, mas os dados que importam estão na plataforma — e a alternativa costuma ser exportar planilha e colar conteúdo em prompt. O servidor MCP do DATTA fecha essa distância e mantém a operação visível no console: quem conectou, o que executou e quanto tempo levou.

A tela Sistema > MCP

Toda a operação fica em Sistema›MCP (página screens/config-mcp.html, servida dentro do console), que reúne:

• as ferramentas registradas, cada uma com nome, esquema de parâmetros e a permissão exigida — é a lista exata do que um cliente externo pode fazer;
• o catálogo de capacidades, com quantas operações a plataforma publica hoje, qual mecanismo de busca por significado foi usado para indexá-las e um botão para reconstruir o catálogo sem esperar a atualização automática;
• as sessões de clientes ativas naquele momento;
• as invocações recentes, com usuário, ferramenta, duração e resultado — é o primeiro lugar a olhar quando algo parece lento ou falha;
• os endereços de conexão prontos para copiar e colar nos clientes.

Validar depois de instalar

Antes de distribuir os endereços ao time, confirme três coisas, em ordem:

1. O servidor responde. A verificação de saúde do serviço MCP deve estar íntegra.
2. As ferramentas estão registradas. A lista de ferramentas na tela Sistema›MCP deve trazer as 8 ferramentas publicadas.
3. O canal responde de verdade. Um teste de fumaça pelo canal JSON-RPC, pedindo a listagem de ferramentas, deve devolver a mesma lista. O formato das mensagens e o canal usado estão na referência de API.

Passo a passo: conectar um assistente de IA

1. Abra Sistema›MCP e copie o endereço de conexão do servidor (o canal de eventos, no caminho /mcp/sse) e um token de acesso válido.
2. No seu computador, edite o arquivo de configuração de servidores MCP do cliente que você usa (cada cliente documenta onde ele fica — normalmente um JSON no perfil do usuário) e declare o DATTA como servidor:

{
  "mcpServers": {
    "datta": {
      "url": "<endereco-de-conexao-copiado-do-console>",
      "headers": {
        "Authorization": "Bearer <seu-token-de-acesso>"
      }
    }
  }
}

1. Reinicie o cliente. As 8 ferramentas do DATTA ficam disponíveis na conversa — pergunte, por exemplo, "quantos processos entraram este mês?" e veja o assistente consultar a plataforma de verdade.

Outros clientes

• n8n — no nó MCP Client, informe o mesmo endereço de conexão e o cabeçalho Authorization: Bearer <token>. Use List Tools para confirmar a conexão.
• Cursor — em Settings › MCP Servers, adicione o mesmo endereço.

Permissões: cada ferramenta tem a sua

Nenhuma ferramenta é executada sem autorização: cada uma exige uma permissão própria, no formato MCP_TOOL_<NOME>, verificada contra o perfil do usuário dono do token. A lista de ferramentas mostra a permissão exigida ao lado de cada uma.

Se um cliente recebe permission denied, a permissão daquela ferramenta não está no perfil do usuário: ajuste em Sistema›Usuários → editar o perfil → conferir se MCP_TOOL_<NOME> está listada, e adicione se faltar. Veja o guia de perfis e permissões.

Limites de uso

Para proteger a plataforma valem limites padrão:

Um cliente que recebe rate limited atingiu um desses tetos. Os valores podem ser elevados temporariamente pela equipe de operações quando um caso de uso legítimo exigir mais.

Rotação do token de serviço

As integrações internas da plataforma usam um token de serviço próprio, guardado como segredo sob o nome MCP_SERVICE_ACCOUNT_TOKEN. A rotação é feita pela equipe de operações, sem indisponibilidade para os usuários:

1. Gerar um novo token aleatório.
2. Atualizar o segredo MCP_SERVICE_ACCOUNT_TOKEN no cofre da plataforma.
3. Reiniciar os módulos que o leem — o Copilot/chat e o próprio servidor MCP — para que releiam o segredo.

Monitoramento

As invocações recentes na tela Sistema›MCP respondem as perguntas do dia a dia — qual ferramenta é mais usada, quanto tempo leva, quem chamou e o que falhou — sem sair do console. As mesmas medições são coletadas automaticamente e alimentam o painel de observabilidade da plataforma:

# Volume por ferramenta
sum by (tool) (rate(datta_mcp_invocations_total[5m]))

# Taxa de erro por ferramenta
sum by (tool) (rate(datta_mcp_invocations_total{outcome="error"}[5m]))
  / sum by (tool) (rate(datta_mcp_invocations_total[5m]))

# Latência p95 por ferramenta
histogram_quantile(0.95,
  sum by (tool, le) (rate(datta_mcp_invocation_latency_ms_bucket[5m])))

# Limites de uso acionados
sum by (tool) (rate(datta_mcp_rate_limited_total[1h]))

Solução de problemas

Veja também

• Perfis e permissões
• Referência de API — canal JSON-RPC, canal de eventos e os recursos de listagem usados pela tela.