Conectar assistentes de inteligência artificial via MCP

Conectar assistentes de inteligência artificial via MCP

O MCP (Model Context Protocol) é o padrão aberto que conecta assistentes de inteligência artificial a sistemas externos. Com o servidor MCP da Dattos, o seu assistente — Claude, Cursor e outros — passa a operar a plataforma em linguagem natural: cria e executa fluxos de conciliação, consulta resultados, gera relatórios e administra cadastros, sempre com as permissões do usuário conectado.

Antes de começar

• Versão da plataforma: Dattos 16.4 ou superior. A verificação é automática: um recurso que exija versão mais nova avisa explicitamente em vez de falhar sem explicação.

• Chave de API: gere a sua em Meu Perfil > Chaves de API. O valor começa com api-.

• Endereço da sua instância: https://sua-empresa.dattos.com.br/dattos.api.

O que fica disponível para o assistente

O servidor MCP expõe 108 ferramentas, cobrindo o ciclo completo da plataforma:

• Construção de fluxos: criar processos, adicionar fontes de dados e montar o fluxo com o apoio do Dattos AI — ou etapa por etapa, com controle fino.

• Execução: disparar e retomar execuções por data de referência e acompanhar o status.

• Consulta: carregamentos, resultados, conciliação (totais por status e resumos) e amostras de saída de cada etapa.

• Exportação: gerar e baixar relatórios.

• Conciliação: regras, configuração e avanço no fluxo de aprovação.

• Gestão de Tarefas: listar, criar (inclusive com recorrência), mover de estágio, comentar e anexar.

• Administração: usuários, perfis de privacidade, conectores, pastas, importações e sessões.

Não é uma superfície somente leitura — o assistente executa ações reais. Das 108 ferramentas, 55 são de leitura e as demais escrevem.

Caminho recomendado — conector hospedado (HTTP)

Este é o caminho padrão. Não exige instalação nem atualização: o assistente se conecta direto ao servidor da Dattos.

Funciona em qualquer assistente que permita configurar duas coisas: a URL do servidor e os cabeçalhos HTTP da chamada. Os cabeçalhos são como o servidor identifica a sua instância e autentica você — sem eles, a conexão não se estabelece. Abaixo estão as instruções para os assistentes mais comuns.

O endereço do servidor é:

https://mcp.dattos.com.br/mcp

A conexão se autentica por dois cabeçalhos obrigatórios:

• Authorization: Bearer api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — a sua chave de API.

• X-Dattos-Api-Url: https://sua-empresa.dattos.com.br/dattos.api — o endereço da sua instância.

E aceita mais quatro, opcionais:

• X-Dattos-Folder-Id: 2473 — define a pasta padrão das operações.

• X-Dattos-Agent: claude — identifica qual assistente executou a ação.

• X-Dattos-Conversation-Context: conv-123 — identifica a conversa que originou a ação.

• X-Dattos-Channel-User-Id: user-9 — identifica o usuário final, quando o assistente atende várias pessoas com a mesma chave.

No Claude.ai (pela tela, sem arquivo)

Abra Configurações > Conectores > Adicionar conector personalizado, informe a URL do servidor e os cabeçalhos acima. Não há arquivo de configuração a editar — tudo é feito na interface.

No Claude Code

Um comando resolve:

claude mcp add --transport http dattos https://mcp.dattos.com.br/mcp --header "Authorization: Bearer api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" --header "X-Dattos-Api-Url: https://sua-empresa.dattos.com.br/dattos.api" --header "X-Dattos-Agent: claude-code"

Se preferir versionar a configuração junto com um projeto, o Claude Code também lê um arquivo .mcp.json na raiz do projeto, no formato abaixo. Note o campo type, que declara o transporte:

{
  "mcpServers": {
    "dattos": {
      "type": "http",
      "url": "https://mcp.dattos.com.br/mcp",
      "headers": {
        "Authorization": "Bearer api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "X-Dattos-Api-Url": "https://sua-empresa.dattos.com.br/dattos.api",
        "X-Dattos-Agent": "claude-code"
      }
    }
  }
}

No Cursor, VS Code e Windsurf

Configure manualmente o arquivo MCP da ferramenta com a URL e os cabeçalhos:

{
  "mcpServers": {
    "dattos": {
      "url": "https://mcp.dattos.com.br/mcp",
      "headers": {
        "Authorization": "Bearer api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "X-Dattos-Api-Url": "https://sua-empresa.dattos.com.br/dattos.api",
        "X-Dattos-Folder-Id": "2473",
        "X-Dattos-Agent": "cursor"
      }
    }
  }
}

No VS Code, a chave inicial é servers em vez de mcpServers.

Depois de conectar, reinicie o assistente e experimente pedir: "liste meus processos de conciliação na Dattos e execute o de vendas para 30/06".

Alternativa — servidor local (stdio)

Use esta opção quando o assistente precisar ler arquivos da sua máquina (por exemplo, anexar uma planilha local a um fluxo), quando não houver saída para a internet, ou quando a política da sua empresa exigir que a chave de API não saia da máquina: no caminho hospedado a chave viaja em cada requisição (sem ser armazenada), enquanto no local ela fica no cofre do sistema operacional e é reaproveitada da CLI.

Com a CLI Dattos instalada e autenticada (veja "CLI Dattos: instalação e primeiros passos"), inclua os complementos do servidor e rode a instalação:

pip install "dattos[mcp,security]"
dattos mcp install claude-code

Alvos aceitos: claude-code, claude-desktop, cursor, vscode, windsurf e gemini. Sem argumento, o comando lista as opções.

O servidor local reaproveita as credenciais da CLI — não é preciso repetir a chave na configuração do assistente. É a principal diferença em relação ao caminho hospedado.

Como fica o arquivo de configuração

O comando dattos mcp install escreve o bloco abaixo por você, preservando os outros servidores que já estiverem no arquivo. Se preferir editar à mão, é este o formato:

{
  "mcpServers": {
    "dattos": {
      "command": "dattos-mcp",
      "args": []
    }
  }
}

Repare que aqui não há URL nem cabeçalhos: em vez de chamar um servidor pela rede, o assistente executa o programa dattos-mcp na sua máquina, e ele usa as credenciais que você já configurou na CLI.

No VS Code, a chave inicial é servers em vez de mcpServers — o resto é igual.

Onde fica o arquivo, por assistente:

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json

• Claude Code: use o comando claude mcp add --transport stdio dattos -- dattos-mcp, ou um .mcp.json na raiz do projeto

• Cursor: ~/.cursor/mcp.json

• VS Code: .vscode/mcp.json, dentro do projeto

• Windsurf: ~/.codeium/windsurf/mcp_config.json

• Gemini CLI: ~/.gemini/settings.json

Depois de editar o arquivo, feche e abra o assistente para ele carregar o servidor.

Cinco ferramentas indisponíveis no caminho hospedado

Por decisão de segurança, cinco ferramentas são removidas quando o servidor é acessado por HTTP. Todas continuam disponíveis no servidor local:

• select_folder e get_current_folder — dependem de estado gravado na máquina. Contorno: use o cabeçalho X-Dattos-Folder-Id.

• add_etl_source — leria arquivos do servidor, não os seus. Contorno: use add_etl_source_content, que recebe o conteúdo do arquivo.

• batch_create_users — mesmo motivo (depende de caminho de arquivo).

• kill_session — encerrar sessões de terceiros é privilegiado demais para exposição remota.

Segurança

• Permissões do usuário, sempre. A credencial é a chave de API pessoal; perfis, pastas e permissões valem integralmente para o assistente.

• Sem custódia de credenciais. O gateway não guarda a sua chave: ela viaja em cada requisição e é descartada com a resposta. Revogar a chave em Meu Perfil > Chaves de API corta o acesso do assistente em até 60 segundos.

• Somente chave de API. Token de sessão não é aceito no caminho hospedado.

• Trilha de auditoria à prova de falsificação. A origem da ação é sempre estampada pelo próprio servidor como "MCP" — um assistente não consegue se passar por outra origem, mesmo que tente informar outro valor. Toda ação executada pelo assistente fica registrada na auditoria da plataforma.

• Confirmação humana nas escritas sensíveis. Nas ferramentas de Gestão de Tarefas, o assistente não escreve na primeira chamada: ele recebe uma prévia do que será feito e um código de uso único, e precisa que você digite esse código na conversa para concluir. O código vale 15 minutos, funciona uma única vez e é cancelado automaticamente se o dado mudar nesse intervalo.

• Exclusões exigem confirmação explícita. Excluir usuário, perfil, conector ou regra de conciliação só acontece com o parâmetro de confirmação preenchido.

• Boas práticas. Trate a chave como senha, use um usuário de permissões mínimas para automações e regenere a chave periodicamente.

Artigos relacionados

• CLI Dattos: instalação e primeiros passos

• CLI Dattos: comandos e capacidades

• Chaves de API: gerar e revogar

• Introdução às integrações