Quickstart

From signup to your first query in under five minutes. Pick the surface that fits your workflow — each section walks through getting a token, connecting, and running your first query. Token mint and install differ by surface (MCP uses OAuth in most clients; SDK and CLI install from the public npm registry — no token required).

• Connect via MCP — fastest path if you already use Claude Code, Cursor, or another MCP-compatible client. OAuth in most clients, no token mint required.
• Connect via SDK — TypeScript apps, custom agents, programmatic access.
• Connect via CLI — terminal-first exploration and scripts.

The first query section at the bottom shows how each surface reads from the public warmhub-data/congress-trading repo. MCP returns a natural-language summary; SDK and CLI fetch the raw records so your code or terminal can read them directly.

Prerequisites: A WarmHub account. See Getting Access if you don’t have one.

Connect via MCP

Connect any MCP-compatible client — Claude Code, Cursor, VS Code Copilot Chat, or anything else that speaks HTTP MCP.

1. Get a token

WarmHub MCP supports two auth modes:

• OAuth (default in Claude Code and Cursor) — no setup, the client handles login on first use.
• Personal access token (PAT) — required on WSL2 or in headless environments.

To create a PAT, install the wh CLI, log in, and run:

wh token create --name my-agent

The token is printed once. Copy it now if you’re using PAT auth.

2. Add the MCP server

Pick your client and drop the WarmHub server into its MCP config. The examples below use the global endpoint (/mcp); for a single-repo agent, swap in /mcp/<org>/<repo> instead — see Global vs Repo-Scoped.

Claude Code

claude mcp add --scope user --transport http warmhub https://api.warmhub.ai/mcp

That registers WarmHub user-wide. Drop --scope user to register it for the current project only. Or commit a .mcp.json in the project root for teammates:

{
  "mcpServers": {
    "warmhub": {
      "transport": "http",
      "url": "https://api.warmhub.ai/mcp"
    }
  }
}

Claude Code handles OAuth automatically on first call. For PAT auth, use the mcp-remote bridge config.

Cursor

Add to ~/.cursor/mcp.json (user-wide) or .cursor/mcp.json (project-scoped):

{
  "mcpServers": {
    "warmhub": {
      "transport": "http",
      "url": "https://api.warmhub.ai/mcp"
    }
  }
}

Restart Cursor after editing. Cursor handles OAuth on first call.

VS Code (GitHub Copilot Chat)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "warmhub": {
      "type": "http",
      "url": "https://api.warmhub.ai/mcp"
    }
  }
}

VS Code prompts for auth on first call. See VS Code’s MCP docs for the latest schema.

Other clients

Any MCP client that supports HTTP transport works. Point it at https://api.warmhub.ai/mcp (global) or https://api.warmhub.ai/mcp/<org>/<repo> (repo-scoped). For PAT auth in clients that don’t support OAuth, use the mcp-remote stdio bridge.

3. Try it

Skip down to Your first query for the prompt to try.

Connect via SDK

Build TypeScript apps and agents with @warmhub/sdk-ts.

1. Get a token

You’ll need the WarmHub CLI to mint a personal access token. Log in and create one:

wh auth login
wh token create --name my-script

Save the printed token — it’s shown only once. Export it:

export WH_TOKEN=eyJhbGciOi...

See Personal Access Tokens for scopes and rotation.

2. Install the SDK and create a client

The SDK is published to the public npm registry. No registry config or extra token required:

npm install @warmhub/sdk-ts

Create a client:

import { WarmHubClient } from "@warmhub/sdk-ts";

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WH_TOKEN },
});

3. Try it

Skip down to Your first query for the call to make.

Connect via CLI

Use the wh CLI for terminal exploration and scripting.

1. Get a token

Install the CLI and log in. The CLI saves your credentials and auto-refreshes them.

Install the CLI

The CLI is published to the public npm registry and requires Node 22+. No registry config or extra token required:

npm install -g @warmhub/cli
wh --version

Log in

wh auth login
wh auth status

wh auth login opens your browser — sign in with email, Google, or GitHub. For CI/CD or headless environments, see Getting Access for non-interactive options.

2. Set a target repo

Most wh commands operate on a specific org/repo. Set it once with wh use so you don’t need --repo on every command:

wh use warmhub-data/congress-trading

This writes a .wh file in the current directory. You can also specify a repo per-command with --repo, or set the WARMHUB_REPO environment variable. Priority: --repo flag > WARMHUB_REPO env > .wh file.

3. Try it

Skip down to Your first query for the command to run.

Your first query

We’ll use the public warmhub-data/congress-trading repo — it has StockTrade things tracking U.S. congressional stock trades disclosed under the STOCK Act. Let’s pull a sample of disclosures.

Via MCP

In your client, ask:

Look at the warmhub-data/congress-trading data on WarmHub. Show me a sample of congressional stock trade disclosures.

The agent will call warmhub_repo_describe to learn the StockTrade shape, then warmhub_thing_query to fetch StockTrade items and summarize the disclosures.

Via SDK

const trades = await client.thing.head("warmhub-data", "congress-trading", {
  shape: "StockTrade",
  kind: "thing",
  limit: 10,
});
console.log(trades.items);

Each StockTrade carries legislator_name, ticker, amount (a disclosure tier like "$50,001 - $100,000"), and tx_type (purchase/sale). See Queries for filter patterns.

Live updates

To watch new trades land in real time, wrap the same query with client.live.thingHead:

const handle = await client.live.thingHead(
  "warmhub-data",
  "congress-trading",
  { shape: "StockTrade", kind: "thing", limit: 20 },
  (snapshot) => console.log(`${snapshot.items.length} trades at HEAD`),
);
// later, to stop the stream:
handle.close();

See client.live for raw event streaming and other refreshed-query helpers.

Via CLI

wh thing list --shape StockTrade --kind thing --limit 10 --repo warmhub-data/congress-trading

Copy any StockTrade/... reference from the output and view the full record. For example:

wh thing view StockTrade/2024/20025368/1 --repo warmhub-data/congress-trading

Add --json for machine-readable output, or --live to watch for real-time changes.

Other public repos to explore

The warmhub-data org hosts several public repos:

• warmhub-data/congress-trading — congressional stock trade disclosures filed under the STOCK Act, linked to legislator and security records in the companion repos below.
• warmhub-data/congress-committees — committees and member assignments.
• warmhub-data/congress-members — current and historical members of Congress.
• warmhub-data/sec-equities — NYSE and Nasdaq listings.

Next Steps

• Core Concepts — the mental model behind orgs, repos, shapes, things, assertions, and writes.
• Data Modeling — wrefs, shapes, things, and assertions in detail.
• MCP Tool Walkthrough — full tool sequence (warmhub_capabilities → warmhub_repo_describe → reads → writes).
• MCP Server — endpoints, OAuth, and protocol details.
• SDK Overview — client options, surfaces, and error kinds.
• CLI Reference — full command reference for all wh commands.