# How the DAT MCP Server Integrates with Claude Desktop: Architecture and Setup Guide

> Learn how the DAT MCP server integrates with Claude Desktop via HTTP/SSE endpoints and the Model Context Protocol. Execute SQL queries and data analysis using natural language.

- Repository: [Junjie.M/dat](https://github.com/junjiem/dat)
- Tags: architecture
- Published: 2026-03-05

---

**The DAT MCP server exposes data-agent tools via HTTP/SSE endpoints that Claude Desktop discovers and invokes through the Model Context Protocol, allowing Claude to execute SQL queries and data analysis through natural language requests.**

The DAT (Data-as-a-Tool) framework from the `junjiem/dat` repository provides a Model Context Protocol (MCP) server that enables Claude Desktop to interact directly with data agents. This integration allows Claude to perform complex data analysis by invoking specialized tools hosted on the DAT server through standardized MCP requests.

## Architecture Overview

The integration relies on four core components working together through the Model Context Protocol specification.

**[`McpToolsService.java`](https://github.com/junjiem/dat/blob/main/McpToolsService.java)** ([`dat-servers/dat-server-mcp/src/main/java/ai/dat/server/mcp/service/tools/McpToolsService.java`](https://github.com/junjiem/dat/blob/main/dat-servers/dat-server-mcp/src/main/java/ai/dat/server/mcp/service/tools/McpToolsService.java)) defines the exposed tools using Spring Boot annotations. This service publishes methods like `dat_agents` and `dat_ask_data` as discoverable MCP tools that follow the protocol specification for dynamic invocation.

**[`ProjectService.java`](https://github.com/junjiem/dat/blob/main/ProjectService.java)** ([`dat-servers/dat-server-mcp/src/main/java/ai/dat/server/mcp/service/ProjectService.java`](https://github.com/junjiem/dat/blob/main/dat-servers/dat-server-mcp/src/main/java/ai/dat/server/mcp/service/ProjectService.java)) manages the DAT project state including agents, schemas, and data connections. When Claude invokes a tool, this service routes the request to the appropriate Ask-Data agent and executes the underlying business logic.

**Claude Desktop** acts as the MCP client. The application loads the MCP server URL through its **MCP Tools** configuration panel, discovers available tools via the MCP specification, and translates user questions into structured MCP requests sent to the DAT server.

**[`McpServerCommand.java`](https://github.com/junjiem/dat/blob/main/McpServerCommand.java)** ([`dat-cli/src/main/java/ai/dat/cli/commands/server/McpServerCommand.java`](https://github.com/junjiem/dat/blob/main/dat-cli/src/main/java/ai/dat/cli/commands/server/McpServerCommand.java)) provides the CLI entry point. Running `dat server mcp` initializes the server and outputs the endpoint URL required for Claude Desktop configuration.

## Starting the DAT MCP Server

Before Claude Desktop can connect, you must start the MCP server and identify the endpoint URL.

Use the following command to launch the server with HTTP transport:

```bash
./dat server mcp \
  --transport http \
  --port 8080

```

The console outputs the critical connection details that Claude Desktop requires:

```

🧩 MCP Server type: http
📖 MCP Server url: http://127.0.0.1:8080/mcp
🚀 Starting DAT MCP Server...

```

The `--transport` parameter accepts `stdio` for local pipe communication or `http` for network-based SSE connections. The HTTP transport is required for Claude Desktop integration.

## Configuring Claude Desktop for MCP Integration

Once the server is running, configure Claude Desktop to discover the DAT tools.

1. Open Claude Desktop settings and navigate to the **MCP Tools** section.
2. Paste the server URL (e.g., `http://127.0.0.1:8080/mcp`) into the tool configuration panel.
3. Claude automatically fetches the tool manifest from `McpToolsService` and lists available functions including `dat_agents` and `dat_ask_data`.

Claude Desktop now treats these DAT tools as native capabilities. When users ask data-related questions, Claude determines which tool to invoke and constructs the appropriate MCP request.

## Tool Invocation Flow and Data Processing

When a user submits a query like "How many COVID-19 vaccine doses were administered in 2022?", Claude Desktop generates an MCP request targeting the `dat_ask_data` tool.

The request payload follows this structure:

```json
{
  "name": "dat_ask_data",
  "parameters": {
    "conversationId": "a1b2c3",
    "agentName": "default",
    "question": "How many COVID-19 vaccine doses were administered in 2022?"
  }
}

```

This HTTP POST request hits the `/mcp` endpoint and triggers `McpToolsService.ask()` (lines 48-95 in the source). The method performs three critical operations:

- **Generates a UUID** for `conversationId` if the parameter is missing, ensuring conversation tracking.
- **Retrieves the active project** via `ProjectService.getProject()` to access configured data sources and agent definitions.
- **Executes the Ask-Data agent** through `ProjectService.ask()`, which generates SQL and streams formatted results back to Claude.

The response includes the generated SQL query and analysis results, which Claude Desktop incorporates directly into the chat interface.

## Key Configuration Files

Understanding these source files helps troubleshoot integration issues:

- **[`McpToolsService.java`](https://github.com/junjiem/dat/blob/main/McpToolsService.java)**: Defines `@Tool` annotated methods that expose DAT functionality through the MCP protocol.
- **[`ProjectService.java`](https://github.com/junjiem/dat/blob/main/ProjectService.java)**: Contains the core execution logic for routing questions to specific agents and managing database connections.
- **[`McpServerCommand.java`](https://github.com/junjiem/dat/blob/main/McpServerCommand.java)**: Handles CLI argument parsing and server initialization, printing the transport type and endpoint URL on startup.
- **[`application-mcp.yml`](https://github.com/junjiem/dat/blob/main/application-mcp.yml)** ([`dat-servers/dat-server-mcp/src/main/resources/application-mcp.yml`](https://github.com/junjiem/dat/blob/main/dat-servers/dat-server-mcp/src/main/resources/application-mcp.yml)): Stores default configuration including port assignments and transport settings.

## Summary

- The **DAT MCP server** (`junjiem/dat`) exposes data analysis tools through HTTP/SSE endpoints following the Model Context Protocol specification.
- **Claude Desktop** integrates by connecting to the server URL and dynamically discovering tools defined in [`McpToolsService.java`](https://github.com/junjiem/dat/blob/main/McpToolsService.java).
- The **`dat server mcp`** CLI command starts the server and displays the endpoint required for configuration.
- Tool requests flow from Claude through `McpToolsService` to `ProjectService`, which executes Ask-Data agents and returns SQL-generated results.
- The integration supports both `stdio` and `http` transports, though Claude Desktop requires the HTTP transport for network-based tool invocation.

## Frequently Asked Questions

### What transport protocol should I use for Claude Desktop integration?

Use the **HTTP transport** (`--transport http`) when integrating with Claude Desktop. While the DAT MCP server supports `stdio` for local pipe communication, Claude Desktop requires HTTP or Server-Sent Events (SSE) to connect to remote or local network endpoints. Configure the port using `--port 8080` or modify [`application-mcp.yml`](https://github.com/junjiem/dat/blob/main/application-mcp.yml).

### Which tools does the DAT MCP server expose to Claude Desktop?

The server exposes **`dat_agents`** and **`dat_ask_data`** through [`McpToolsService.java`](https://github.com/junjiem/dat/blob/main/McpToolsService.java). The `dat_agents` tool returns configured agent definitions, while `dat_ask_data` processes natural language questions, generates SQL queries, and returns data analysis results. These tools are discovered automatically when Claude Desktop connects to the MCP endpoint.

### How does the DAT server handle missing conversation IDs?

According to the implementation in `McpToolsService.ask()` (lines 48-95), the server automatically **generates a UUID** for the `conversationId` parameter if it is not provided in the MCP request. This ensures every query maintains proper context tracking through the `ProjectService` execution pipeline.

### Can I customize the MCP server port and endpoint?

Yes. Modify **[`application-mcp.yml`](https://github.com/junjiem/dat/blob/main/application-mcp.yml)** in `dat-servers/dat-server-mcp/src/main/resources/` to change default port assignments, or override settings via CLI flags like `--port 8080`. The endpoint path remains `/mcp` as defined by the Spring Boot controller mapping in [`McpToolsService.java`](https://github.com/junjiem/dat/blob/main/McpToolsService.java).