MCP Server

HatiData includes a built-in MCP (Model Context Protocol) server that lets Claude Desktop, Claude Code, Cursor, and other MCP-compatible agents query your data warehouse directly.

What is MCP

The Model Context Protocol is an open standard for connecting AI models to external data sources and tools. An MCP server exposes tools that agents can call during their reasoning process. HatiData's MCP server provides four tools:

Tool	Description
query	Execute SQL against the warehouse and return results as JSON
list_tables	List all available tables in the database
describe_table	Get the schema (columns, types) for a specific table
get_context	RAG context retrieval via full-text search

These tools give any MCP-compatible agent the ability to explore your data warehouse schema, run analytical queries, and retrieve contextual information -- all through the HatiData proxy's full security pipeline (policy checks, audit, metering, column masking).

Installation

The MCP server is included with the hatidata-agent Python package:

pip install hatidata-agent[mcp]

This installs the hatidata-mcp-server command-line tool.

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "hatidata": {
      "command": "hatidata-mcp-server",
      "args": [
        "--host", "localhost",
        "--port", "5439",
        "--agent-id", "claude-desktop",
        "--database", "hatidata"
      ]
    }
  }
}

Claude Code

Add to your Claude Code MCP settings:

.claude/mcp.json

{
  "mcpServers": {
    "hatidata": {
      "command": "hatidata-mcp-server",
      "args": [
        "--host", "localhost",
        "--port", "5439",
        "--agent-id", "claude-code",
        "--database", "hatidata"
      ]
    }
  }
}

Cursor

Add to your Cursor MCP configuration:

.cursor/mcp.json

{
  "mcpServers": {
    "hatidata": {
      "command": "hatidata-mcp-server",
      "args": [
        "--host", "localhost",
        "--port", "5439",
        "--agent-id", "cursor-agent",
        "--database", "hatidata"
      ]
    }
  }
}

CLI Options

hatidata-mcp-server [OPTIONS]

Options:
  --host       Proxy hostname           [default: localhost]
  --port       Proxy port               [default: 5439]
  --agent-id   Agent identifier          [default: mcp-agent]
  --database   Database name             [default: hatidata]
  --user       Username                  [default: agent]
  --password   Password or API key       [default: ""]

For cloud deployments, point to your cloud proxy and provide an API key:

{
  "mcpServers": {
    "hatidata": {
      "command": "hatidata-mcp-server",
      "args": [
        "--host", "your-org.proxy.hatidata.com",
        "--port", "5439",
        "--agent-id", "claude-desktop",
        "--database", "hatidata",
        "--password", "hd_live_your_api_key"
      ]
    }
  }
}

API Keys in Configuration

Avoid hardcoding API keys in configuration files. Use environment variables or a secret manager where possible. The --password flag accepts environment variable references in some shells.

Tool Details

query

Execute a SQL query and return results as JSON.

Input:

{
  "sql": "SELECT customer_id, SUM(total) as revenue FROM orders GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
}

Output:

[
  {"customer_id": 42, "revenue": 125000.00},
  {"customer_id": 17, "revenue": 98500.00}
]

The query tool supports both standard SQL and legacy warehouse SQL syntax. Functions like NVL, IFF, DATEDIFF, and DATEADD are automatically transpiled to DuckDB-compatible equivalents. Agents can write in whichever SQL dialect they are most familiar with.

The query passes through HatiData's full 13-step pipeline: policy evaluation, cost estimation, quota checks, row-level security, transpilation, DuckDB execution, AI healing on failure, column masking, and audit logging.

list_tables

List all tables in the database.

Input: (none)

Output:

["customers", "orders", "products", "events"]

Returns only tables the authenticated agent has permission to see, based on ABAC policy evaluation.

describe_table

Get column names, types, and nullability for a table.

Input:

{
  "table_name": "orders"
}

Output:

[
  {"column_name": "id", "data_type": "INTEGER", "is_nullable": "NO"},
  {"column_name": "customer_id", "data_type": "INTEGER", "is_nullable": "NO"},
  {"column_name": "total", "data_type": "DECIMAL(10,2)", "is_nullable": "YES"},
  {"column_name": "created_at", "data_type": "TIMESTAMP", "is_nullable": "YES"}
]

This tool queries information_schema.columns under the hood, with results filtered by the agent's access policies.

get_context

Retrieve relevant rows using full-text search (for RAG workflows).

Input:

{
  "table": "knowledge_base",
  "search_query": "enterprise pricing",
  "top_k": 5
}

Output:

[
  {"id": 12, "title": "Enterprise Plan", "content": "Custom pricing for..."},
  {"id": 45, "title": "Pricing FAQ", "content": "Our enterprise tier..."}
]

The get_context tool is designed for retrieval-augmented generation workflows where an agent needs to pull relevant context from a table before generating a response. The top_k parameter controls how many results to return (default: 5).

Transport Protocol

The MCP server uses the stdio transport -- it reads JSON-RPC messages from stdin and writes responses to stdout. This is the standard transport for MCP servers and is supported by all MCP-compatible clients.

The communication flow:

1. The MCP client (Claude Desktop, Cursor, etc.) spawns the hatidata-mcp-server process
2. The client sends JSON-RPC requests via stdin
3. The server connects to HatiData's proxy over the PostgreSQL wire protocol
4. Query results are returned as JSON-RPC responses via stdout
5. The process stays alive for the duration of the session

Using from Python

You can also programmatically create an MCP server instance:

from hatidata_agent.mcp_server import create_server, create_tools
from hatidata_agent import HatiDataAgent

agent = HatiDataAgent(
    host="localhost",
    port=5439,
    agent_id="my-mcp-server",
)

# Get tool definitions for custom integration
tools = create_tools(agent)

# Or start the full MCP server programmatically
server = create_server(agent)
server.run()  # Blocks, listening on stdio

This is useful when you want to embed HatiData's MCP capabilities inside a larger application or custom agent runtime.

Ready-Made Config Files

Pre-built MCP configuration files for Claude Desktop, Claude Code, and Cursor are available in the public repo:

• GitHub: integrations/mcp

These configuration files include sensible defaults and comments explaining each option.

Security Considerations

Every tool call through the MCP server goes through HatiData's full security pipeline:

• Authentication -- The --password flag provides the API key used for all connections
• Authorization -- ABAC policies evaluate each query against the agent's role and capabilities
• Audit -- Every query is logged with the agent ID, framework (mcp), and full query text
• Row-level security -- Automatic WHERE clause injection based on agent identity
• Column masking -- Sensitive columns are redacted based on the agent's role
• Metering -- Query costs are tracked against the agent's credit quota

Next Steps

• Agent Integrations -- LangChain, CrewAI, and more
• Python SDK -- Direct agent-aware queries from Python
• SQL Compatibility -- What SQL syntax the MCP tools understand