Connect AI assistants via MCP

Connect AI assistants via MCP

The MCP (Model Context Protocol) is the open standard that connects AI assistants to external systems. With Dattos' MCP server, your assistant — Claude, Cursor and others — can now operate the platform in natural language: create and run reconciliation flows, query results, generate reports, and manage records, always with the permissions of the logged-in user.

Before you begin

• Platform version: Dattos 16.4 or later. Verification is automatic: any feature that requires a newer version will warn explicitly instead of failing without explanation.

• API key: generate yours under My Profile > API Keys. The value starts with api-.

• Your instance address: https://sua-empresa.dattos.com.br/dattos.api.

What is available to the assistant

The MCP server exposes 108 tools, covering the full platform lifecycle:

• Flow building: create processes, add data sources, and assemble the flow with help from Dattos AI — or step by step, with fine-grained control.

• Execution: start and resume runs by reference date and track status.

• Query: loads, results, reconciliation (totals by status and summaries), and output samples from each step.

• Export: generate and download reports.

• Reconciliation: rules, configuration, and progress through the approval flow.

• Task Management: list, create (including recurring ones), move between stages, comment, and attach files.

• Administration: users, privacy profiles, connectors, folders, imports, and sessions.

It is not a read-only surface — the assistant performs real actions. Of the 108 tools, 55 are read-only and the rest write.

Recommended path — hosted connector (HTTP)

This is the default path. No installation or update is required: the assistant connects directly to Dattos' server.

It works in any assistant that lets you configure two things: the server URL and the HTTP headers for the call. Headers are how the server identifies your instance and authenticates you — without them, the connection is not established. Below are the instructions for the most common assistants.

The server address is:

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

The connection authenticates through two required headers:

• Authorization: Bearer api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx — your API key.

• X-Dattos-Api-Url: https://sua-empresa.dattos.com.br/dattos.api — your instance address.

And it also accepts four optional ones:

• X-Dattos-Folder-Id: 2473 — sets the default folder for operations.

• X-Dattos-Agent: claude — identifies which assistant performed the action.

• X-Dattos-Conversation-Context: conv-123 — identifies the conversation that originated the action.

• X-Dattos-Channel-User-Id: user-9 — identifies the end user when the assistant serves multiple people with the same key.

In Claude.ai (through the UI, no file)

Open Settings > Connectors > Add custom connector, enter the server URL and the headers above. There is no config file to edit — everything is done in the interface.

In Claude Code

One command does it:

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"

If you prefer to version the configuration alongside a project, Claude Code also reads a .mcp.json file in the project root, in the format below. Note the type field, which declares the transport:

{
  "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"
      }
    }
  }
}

In Cursor, VS Code, and Windsurf

Manually configure the tool's MCP file with the URL and headers:

{
  "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"
      }
    }
  }
}

In VS Code, the top-level key is servers instead of mcpServers.

After connecting, restart the assistant and try asking: "list my reconciliation processes in Dattos and run the sales one for 30/06".

Alternative — local server (stdio)

Use this option when the assistant needs to read files from your machine (for example, attach a local spreadsheet to a flow), when there is no internet access, or when your company's policy requires that the API key does not leave the machine: in the hosted path the key travels with every request (without being stored), while in the local path it stays in the operating system's vault and is reused from the CLI.

With the Dattos CLI installed and authenticated (see "CLI Dattos: installation and first steps"), add the server extras and run the installation:

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

Accepted targets: claude-code, claude-desktop, cursor, vscode, windsurf, and gemini. With no argument, the command lists the options.

The local server reuses the CLI credentials — you do not need to repeat the key in the assistant configuration. That is the main difference compared with the hosted path.

What the configuration file looks like

The dattos mcp install command writes the block below for you, preserving any other servers already in the file. If you prefer to edit it manually, this is the format:

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

Note that here there is no URL or headers: instead of calling a server over the network, the assistant runs the dattos-mcp program on your machine, and it uses the credentials you already configured in the CLI.

In VS Code, the top-level key is servers instead of mcpServers — everything else is the same.

Where the file is located, by assistant:

• 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 the command claude mcp add --transport stdio dattos -- dattos-mcp, or a .mcp.json file at the project root

• Cursor: ~/.cursor/mcp.json

• VS Code: .vscode/mcp.json, inside the project

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

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

After editing the file, close and reopen the assistant so it loads the server.

Five tools unavailable in the hosted path

For security reasons, five tools are removed when the server is accessed over HTTP. They are all still available on the local server:

• select_folder and get_current_folder — they depend on state stored on the machine. Workaround: use the X-Dattos-Folder-Id header.

• add_etl_source — would read files from the server, not yours. Workaround: use add_etl_source_content, which receives the file contents.

• batch_create_users — same reason (depends on file path).

• kill_session — ending third-party sessions is too privileged for remote exposure.

Security

• User permissions, always. The credential is the personal API key; profiles, folders, and permissions apply in full to the assistant.

• No credential custody. The gateway does not store your key: it travels with every request and is discarded with the response. Revoking the key under My Profile > API Keys cuts off the assistant's access within up to 60 seconds.

• API key only. Session tokens are not accepted in the hosted path.

• Tamper-proof audit trail. The source of the action is always stamped by the server itself as "MCP" — an assistant cannot impersonate another source, even if it tries to provide a different value. Every action performed by the assistant is recorded in the platform audit.

• Human confirmation for sensitive writes. In Task Management tools, the assistant does not write on the first call: it receives a preview of what will be done and a one-time code, and it needs you to type that code in the conversation to complete the action. The code is valid for 15 minutes, works only once, and is automatically canceled if the data changes during that period.

• Deletions require explicit confirmation. Deleting a user, profile, connector, or reconciliation rule only happens when the confirmation parameter is filled in.

• Best practices. Treat the key like a password, use a least-privilege user for automations, and rotate the key periodically.

Related articles

• CLI Dattos: installation and first steps

• CLI Dattos: commands and capabilities

• API keys: generate and revoke

• Introduction to integrations