Connection Guide — Choose Your Protocol

HatiData exposes three distinct connection protocols, each designed for a different class of workload. This guide helps you pick the right one.

Three Ways to Connect

1. SQL Proxy (Postgres Wire Protocol)

The SQL proxy listens on port 5439 and speaks the PostgreSQL v3 wire protocol. Any Postgres-compatible client — psql, DBeaver, Metabase, Grafana, Tableau, psycopg2, pg, JDBC, ODBC — can connect without modification.

• Best for: BI tools, direct SQL queries, data exploration, batch analytics
• Protocol: PostgreSQL wire protocol (binary)
• Port: 5439
• Auth: Username + API key as password

psql -h proxy.hatidata.com -p 5439 -U admin -d hatidata
# Password: hd_live_your_api_key

See Postgres Drivers & BI Tools for driver-specific setup.

2. MCP Server (JSON-RPC over HTTP)

The MCP server runs alongside the SQL proxy and exposes 24 tools over HTTP using the JSON-RPC 2.0 protocol. AI agents use this to access memory, chain-of-thought logging, semantic triggers, branch isolation, and governed SQL queries.

• Best for: AI agents, memory read/write, CoT logging, trigger management, branch operations
• Protocol: JSON-RPC 2.0 over HTTP(S)
• Endpoint: POST /mcp
• Auth: Authorization: ApiKey <key> header

curl -X POST https://api.hatidata.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey hd_agent_xxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

See Proxy MCP Server (HTTP) for full protocol details and client examples.

3. Control Plane API (REST)

The Control Plane is a standard REST API for management operations — user administration, organization setup, billing, API key lifecycle, policy management, and more.

• Best for: Account management, billing, user/org admin, API key creation, policy configuration
• Protocol: REST (JSON over HTTP)
• Base URL: https://api.hatidata.com/v1/
• Auth: Authorization: Bearer <jwt> header

# List organizations
curl https://api.hatidata.com/v1/orgs \
  -H 'Authorization: Bearer eyJhbGci...'

# Create an API key
curl -X POST https://api.hatidata.com/v1/orgs/{org_id}/api-keys \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{"name": "analytics-agent", "prefix": "hd_agent"}'

See Control Plane API Reference for all 100+ endpoints.

When to Use What

Use Case	Protocol	Endpoint
Run SQL queries from code	SQL Proxy	postgres://...@host:5439/hatidata
Connect BI tools (Metabase, Grafana, Tableau)	SQL Proxy	postgres://...@host:5439/hatidata
AI agent memory (store/search)	MCP Server	POST /mcp
Chain-of-thought logging	MCP Server	POST /mcp
Semantic trigger management	MCP Server	POST /mcp
Branch isolation for agents	MCP Server	POST /mcp
Run governed SQL from an agent	MCP Server	POST /mcp (via query tool)
Manage users and organizations	Control Plane	GET/POST /v1/orgs/...
Create and rotate API keys	Control Plane	POST /v1/.../api-keys
Configure policies	Control Plane	POST /v1/.../policies
Manage billing and subscriptions	Control Plane	POST /v1/billing/...
View dashboards and analytics	Dashboard	https://app.hatidata.com

tip

Agents running SQL queries can use either the SQL Proxy (via a Postgres driver) or the MCP Server's query tool. The MCP query tool is preferred for agents because it returns JSON, integrates with HatiData's agent identity model, and logs to the chain-of-thought ledger automatically.

Authentication per Protocol

Protocol	Auth Method	Header / Field	Key Format
SQL Proxy	Password field	Postgres password in connection string	hd_live_* or hd_agent_*
MCP Server	API key header	Authorization: ApiKey <key>	hd_live_* or hd_agent_*
Control Plane	JWT bearer token	Authorization: Bearer <jwt>	JWT from login or OAuth
Control Plane	API key (alternate)	Authorization: ApiKey <key>	hd_live_*

Key Prefixes

Prefix	Intended Use	Available On
hd_live_*	Programmatic access from backend services	SQL Proxy, MCP Server, Control Plane
hd_agent_*	AI agent access with per-agent scoping	SQL Proxy, MCP Server
hd_test_*	Development and testing	SQL Proxy, MCP Server

Agent keys (hd_agent_*) carry an agent identity that ties all operations — policy evaluation, quota metering, audit logging, memory isolation — to that specific agent. Always use agent keys when connecting AI agents.

Key Format

All API keys must be exactly 40 characters with the following structure:

hd_live_  + 32 alphanumeric characters = 40 total
hd_test_  + 32 alphanumeric characters = 40 total
hd_agent_ + 31 alphanumeric characters = 40 total

The random portion must contain only ASCII letters (a-z, A-Z) and digits (0-9). No underscores, hyphens, or special characters after the prefix.

Invalid Key Format

Keys that are shorter, longer, or contain non-alphanumeric characters after the prefix will be rejected with Authentication failed: Invalid API key format. This is a common issue when manually creating keys — always use the Control Plane API or dashboard to generate keys.

Agent Self-Registration

When an agent connects to HatiData Cloud, it automatically self-registers:

1. Agent presents org-level API key
2. HatiData creates a registered_agents record
3. Agent receives a stable fingerprint (hd_agt_xxx)
4. Trust level starts at provisional
5. Auto-promotes to verified after 10 successful executions

The fingerprint is returned in the connection metadata and persists across sessions.

Registration Paths

Path	Use Case
Auto on connect	Primary — zero friction
spawn_agent()	Multi-agent orchestration
register_agent MCP tool	Claude, Cursor, AutoGen
hati agent declare CLI	CI/CD, pre-deployment

For the full registration model, trust levels, and org-level policies, see Agent Registry.

TLS

All three protocols require TLS in production and preprod environments. Local development allows plain connections.

Environment	SQL Proxy	MCP Server	Control Plane
Local dev	sslmode=disable	http://localhost:5440/mcp	http://localhost:8080/v1/
Preprod	sslmode=require	https://preprod-api.hatidata.com/mcp	https://preprod-api.hatidata.com/v1/
Production	sslmode=require	https://api.hatidata.com/mcp	https://api.hatidata.com/v1/

warning

Never disable TLS in production. The SQL proxy rejects sslmode=disable connections in cloud environments, and the MCP/Control Plane endpoints are only accessible over HTTPS.

Quick Reference: Connection Strings

# SQL Proxy — Production
postgres://admin:hd_live_xxx@proxy.hatidata.com:5439/hatidata?sslmode=require

# SQL Proxy — Local dev
postgres://admin:hd_live_xxx@localhost:5439/hatidata?sslmode=disable

# MCP Server — Production
POST https://api.hatidata.com/mcp
Authorization: ApiKey hd_agent_xxx

# MCP Server — Local dev
POST http://localhost:5440/mcp
Authorization: ApiKey hd_agent_xxx

# Control Plane — Production
GET https://api.hatidata.com/v1/orgs
Authorization: Bearer <jwt>

Next Steps

• Proxy MCP Server (HTTP) — Full MCP protocol reference with client examples
• MCP Setup — Configure Claude Desktop, Cursor, and other MCP clients
• Postgres Drivers & BI Tools — Connect DBeaver, Metabase, Grafana, and more
• Control Plane API — Complete REST API reference
• MCP Tools Reference — All 24 MCP tools with schemas