Query Hong Kong Data with AI Agents via the Renavon REST API

Jason DeRise recently argued that data companies face a stark choice: embed into AI workflows or get bypassed. His thesis is simple — as AI agents become the primary interface for analysis, data that isn't accessible to those agents might as well not exist.

We agree. The shift isn't from dashboards to chat. It's from data-as-files to data-as-context. When an analyst asks Claude to "compare Group 1 race winners by trainer over the last two seasons," the value isn't in downloading a CSV and writing pandas code. It's in the agent querying the data directly, reasoning over it, and producing an answer in seconds.

Renavon exposes every dataset through a single authenticated REST endpoint: POST /api/v1/query. Any AI assistant that can make HTTP calls — and they all can — can query your subscription with one line of configuration.

Three integration paths¶

There's no one right answer; pick the one that matches how you work.

Path 1 — Just ask the assistant to call the API (simplest)¶

Modern Claude (Desktop, Code, or via the API), Cursor, and ChatGPT can call HTTP endpoints directly inside a conversation. Paste the curl example below into your first message and the agent will use it as a template for the rest of the conversation:

curl -X POST https://renavon.com/api/v1/query \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*) FROM hkjc_races"}'

Then ask away in plain English. The agent writes the SQL, fires the request, and reasons over the JSON response. No installation, no MCP server, no config file. This covers most use cases.

Path 2 — Custom MCP server (for Claude Desktop / Cursor with native MCP)¶

If you want a first-class integration in Claude Desktop or Cursor — schema discovery, autocomplete, persistent tool registration — wrap the REST endpoint in a tiny MCP server. The whole thing fits in ~30 lines of Python:

# renavon_mcp.py — save anywhere
import os
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("renavon")
API_KEY = os.environ["RENAVON_API_KEY"]

@mcp.tool()
def query(sql: str) -> dict:
    """Run a read-only SQL query against Renavon Hong Kong datasets.
    Returns columns, rows, and row_count."""
    r = httpx.post(
        "https://renavon.com/api/v1/query",
        headers={"X-API-KEY": API_KEY, "Content-Type": "application/json"},
        json={"query": sql},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    mcp.run()

Add it to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "renavon": {
      "command": "uv",
      "args": ["run", "--with", "mcp", "--with", "httpx", "/path/to/renavon_mcp.py"],
      "env": {
        "RENAVON_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The query tool now appears in the tool picker, with the agent able to call it autonomously.

Path 3 — Autonomous agents (Manus, Devin, ChatGPT Code Interpreter)¶

For agents that already run Python: hand them the API key and the curl example above. They handle authentication, query construction, and result parsing themselves. No MCP, no setup. This works with any agent that can install requests (or equivalent).

What you can ask¶

After connecting via any of the three paths above, your AI agent can answer questions like:

Horse Racing - "Show me all Group 1 race winners trained by John Size in the last 2 seasons" - "Which horses have the best win rate at Sha Tin over 1200m?" - "Compare the average finishing positions of horses sired by Golden Slipper winners"

Company Registry - "How many new companies were registered in Hong Kong last month?" - "Compare company registration trends by industry sector over the past 3 years"

The agent inspects the available tables (via SELECT name FROM system.tables), writes appropriate SQL, executes it, and presents the results — all within the conversation.

What about direct ClickHouse access?¶

Earlier versions of Renavon exposed ClickHouse credentials directly so customers could connect tools like mcp-server-clickhouse, DBeaver, or DataGrip. That's no longer the case — every query now goes through POST /api/v1/query, authenticated by your API key. This change brings:

• Per-user access enforcement at the SQL layer (you can only query the datasets your subscription covers).
• Resource caps on every query (memory, execution time) so a runaway query can't degrade the cluster.
• Rate limits sized for typical analytic workloads (600 queries/hour by default).
• A single API contract for AI agents, scripts, and dashboards, instead of per-tool credential management.

For analytic workloads — which is what almost all our customers do — this is strictly better. The REST endpoint accepts arbitrary read-only SQL, returns JSON columns and rows, and is faster to set up than any MCP/JDBC dance.

Get started¶

Head to the Connect page for your API key, or browse available datasets if you don't have a subscription yet.