DocumentationArchitectureBlogAboutSpeak to an engineer
Hotdata
Reference›MCP Reference

MCP Reference

Hotdata MCP

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

Spec: Model Context Protocol

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 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.

    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:

    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:

ParamTypeRequiredDescription
sqlstringYesSQL to execute (Postgres-compatible).
connection_idstringNoConnection 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:

ParamTypeRequiredDescription
result_idstringYesQuery 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:

ParamTypeRequiredDescription
limitintegerNoMaximum number of results to return. Default 10.
offsetintegerNoOffset for pagination. Default 0.

get_query_result_schema

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

Parameters:

ParamTypeRequiredDescription
result_idstringYesQuery 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:

ParamTypeRequiredDescription
result_idstringYesQuery result id from run_query.
limitintegerNoMaximum number of rows to return. Default 10.
offsetintegerNoRow offset for pagination. Default 0.

export_query_results

Export a result set by id to CSV or JSON.

Parameters:

ParamTypeRequiredDescription
result_idstringYesQuery result id from run_query.
formatstringNocsv 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:

ParamTypeRequiredDescription
connection_idstringYesConnection public ID.
include_row_countbooleanNoInclude row count per table. Default false.
include_sizebooleanNoInclude size per table. Default false.
table_limitintegerNoMaximum 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.