# MCP Reference

Source: https://www.hotdata.dev/docs/mcp
Site index: https://www.hotdata.dev/llms.txt

# Hotdata MCP

Model Context Protocol server – expose workspace tools to AI agents.

**Spec:** [Model Context Protocol](https://modelcontextprotocol.io/)

## Endpoints

- **GET** `https://mcp.hotdata.dev/mcp/sse` – open the event stream and receive this session's message endpoint.
- **POST** `https://mcp.hotdata.dev/mcp/message?session=<session_id>` – send JSON-RPC requests on that session.

The server speaks MCP's [HTTP+SSE transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports) at protocol version `2024-11-05`. The POST endpoint is not callable on its own: the session id is issued by the SSE stream, and a POST without one is refused with `400 Missing session (query param or X-MCP-Session header)`.

## Authentication

Opening the stream requires both headers:

```
Authorization: Bearer <user_api_key>
X-Workspace-Id: <workspace_public_id>
```

The API key is the same one `api.hotdata.dev` accepts. The workspace is pinned to the session when the stream opens, and every tool call on that session is scoped to it.

Each POST carries the same `Authorization: Bearer` header — the key must belong to the user that opened the session — plus the session id. `X-Workspace-Id` is not read on POST: the session's workspace always wins, so a request cannot re-target a session it did not open.

If a client sends an `Origin` header it must be an allowed origin (`https://mcp.hotdata.dev`, or a localhost origin for local development); anything else is refused with `403 Origin not allowed`. Clients that send no `Origin`, such as CLI tools and server-side agents, are unaffected.

## Session handshake

1. **Open the stream** with the two auth headers, and keep it open for the life of the session.

   ```bash
   curl -N https://mcp.hotdata.dev/mcp/sse \
     -H "Authorization: Bearer $HOTDATA_API_KEY" \
     -H "X-Workspace-Id: $HOTDATA_WORKSPACE_ID"
   ```

2. **Read the `endpoint` event.** The first event on the stream is the message URL — raw text, not JSON — with the session id already in the query string:

   ```
   event: endpoint
   data: https://mcp.hotdata.dev/mcp/message?session=7Xwn...
   ```

3. **POST JSON-RPC to that URL.** Keep the `session` query param, or send the id as an `X-MCP-Session` header instead:

   ```bash
   curl "https://mcp.hotdata.dev/mcp/message?session=$SESSION_ID" \
     -H "Authorization: Bearer $HOTDATA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example","version":"0.1.0"}}}'
   ```

4. **Read the response on the stream.** The POST answers `200` with an empty body — it is an acknowledgement, not the result. Every JSON-RPC response arrives on the SSE stream as a `message` event:

   ```
   event: message
   data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"hotdata-mcp","version":"1.0.0"}}}
   ```

Normal MCP ordering follows: `initialize`, then the `notifications/initialized` notification (which produces no response), then `tools/list` and `tools/call`. The stream emits `: keepalive` comments while idle. A session lives one hour; a POST against an expired or unknown id returns `404 Session not found or expired`, and the client should open a new stream to get a fresh one.

## Available tools

The server exposes the tools below to AI agents. Each tool is described with its parameters as reported by the server's `tools/list`.

**Query execution is not usable over MCP today.** The server does not scope a call to a database, so `run_query` cannot run, and the tools that read a result back from a `result_id` — `get_query_status`, `list_query_results`, `get_query_result_schema`, `get_query_result_sample`, and `export_query_results` — have no result to read. `get_table_row_count` and `get_table_size` are unavailable for the same reason. None of these tools are deprecated: they are registered on the server and take the parameters documented below.

## Query execution

Run SQL and check query status.

---

### run_query

Execute a SQL query and get results. Returns `result_id`, `columns`, `rows`, and `execution_time_ms`. Reuse the returned `result_id` with the query-result tools to inspect, sample, or export the same result set without re-running.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `sql` | string | Yes | SQL to execute (Postgres-compatible). |
| `connection_id` | string | No | Connection public ID to run the query against. Optional when the workspace has a single connection. |

---

### get_query_status

Get the status of a query result by id (e.g. `pending`, `ready`, `failed`).

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `result_id` | string | Yes | Query result id from `run_query`. |

## Query results

Inspect and export result sets by `result_id` (from `run_query`).

---

### list_query_results

List recent query result ids in the workspace. Use returned ids with `get_query_result_schema`, `get_query_result_sample`, or `export_query_results`.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. Default `10`. |
| `offset` | integer | No | Offset for pagination. Default `0`. |

---

### get_query_result_schema

Get column names and types for a result set by id.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `result_id` | string | Yes | Query result id from `run_query`. |

---

### get_query_result_sample

Get the first N rows of a result set by id. Use `limit`/`offset` for pagination.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `result_id` | string | Yes | Query result id from `run_query`. |
| `limit` | integer | No | Maximum number of rows to return. Default `10`. |
| `offset` | integer | No | Row offset for pagination. Default `0`. |

---

### export_query_results

Export a result set by id to CSV or JSON.

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `result_id` | string | Yes | Query result id from `run_query`. |
| `format` | string | No | `csv` or `json`. Default `csv`. |

## Data sources & tables

List and inspect connections and their tables.

---

### list_data_sources

List data sources (connections) in the current workspace. Returns names; use `connection_id` from context when calling `list_tables`.

---

### list_tables

List tables for a connection. `connection_id` is the connection's `public_id` (e.g. from `list_data_sources`).

**Parameters:**
- `connection_id` (string, required) — Connection public ID.

---

### describe_table

Get table description: column metadata (name, type, nullable, default). `schema` is usually `public`.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.
- `schema` (string, required) — Schema name.
- `table` (string, required) — Table name.

---

### get_tables_summary

List tables for a connection; optionally include row count and size for each (up to `table_limit`).

**Parameters:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `connection_id` | string | Yes | Connection public ID. |
| `include_row_count` | boolean | No | Include row count per table. Default `false`. |
| `include_size` | boolean | No | Include size per table. Default `false`. |
| `table_limit` | integer | No | Maximum number of tables to summarize. Default `20`. |

---

### get_table_row_count

Get row count for a table. `approximate=true` uses an estimate when available (faster).

**Parameters:**
- `connection_id` (string, required) — Connection public ID.
- `schema` (string, required) — Schema name.
- `table` (string, required) — Table name.
- `approximate` (boolean, optional) — Use an estimate when available. Default `true`.

---

### get_table_size

Get table size (bytes/GB). Dialect-dependent (e.g. Postgres).

**Parameters:**
- `connection_id` (string, required) — Connection public ID.
- `schema` (string, required) — Schema name.
- `table` (string, required) — Table name.

---

### get_column_stats

Get column statistics for a table: cardinality, nulls, min, max, and sample values. Use to guide filtering and joins.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.
- `schema` (string, required) — Schema name.
- `table` (string, required) — Table name.

## Connections

Inspect and manage existing connections.

---

### get_connection

Get connection details by id: name, source_type, table_count, discovery_status.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.

---

### delete_connection

Delete a connection by id.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.

---

### run_discovery

Re-run schema discovery for a connection by id. Use after the source schema changes.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.

---

### purge_connection_cache

Purge cached schema and table data for a connection by id. Use to force a fresh read after upstream changes.

**Parameters:**
- `connection_id` (string, required) — Connection public ID.

## Metrics & queries

Inspect query metrics, latency, storage, and saved queries.

---

### explain_workspace_metrics

Explain current workspace metrics (connection count, total queries, p50/p99 latency). Includes trend if available.

---

### get_query_latency_trend

Get query latency trend for the last 24 hours. Returns p99 min/max/latest.

---

### get_query_storage

Get visibility into query result storage: object count and total bytes for the workspace.

---

### get_query_count

Get total query count for the workspace.

---

### list_query_errors

List recent query errors in the workspace (time, SQL preview, status_code).

**Parameters:**
- `limit` (integer, optional) — Maximum number of errors to return. Default `10`.

---

### list_recent_queries

List recent queries in the workspace (time, SQL preview, latency_ms, execution_time_ms).

**Parameters:**
- `limit` (integer, optional) — Maximum number of queries to return. Default `10`.

---

### get_slow_queries

List slowest queries in the workspace by latency.

**Parameters:**
- `limit` (integer, optional) — Maximum number of queries to return. Default `5`.

---

### list_saved_queries

List saved (pinned) queries in the workspace.

**Parameters:**
- `limit` (integer, optional) — Maximum number of saved queries to return. Default `10`.