Get started

The fastest way in: hand the sign-up prompt to your agent. Copy it, paste it into Claude Code, Cursor, or Codex, and your agent walks you through creating your account and connecting to WarmHub — one step at a time. No forms; your agent does it with you.

Copy sign up prompt

Or download the prompt as a file.

Prefer to set it up yourself?

From signup to your first query in under five minutes. Authenticate once, then pick the surface that fits your workflow — connect and run your first query.

• 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.
• Connect via GUI chat client — Claude Desktop, claude.ai, or ChatGPT web. These connect through WarmHub’s MCP endpoint — no coding environment required.

All four options share the same backend and concepts — shapes, things, assertions, writes, and wrefs. SDK, CLI, and MCP are the primary developer surfaces; here’s how they compare:

	SDK	CLI	MCP
Best for	TypeScript apps, custom agents, programmatic access	Terminal exploration, shell scripts, quick operations	AI agents with MCP-compatible clients
Type safety	Full TypeScript types	JSON output via --json	Tool schemas
Setup	npm install + client constructor	npm install -g @warmhub/cli	Configure MCP endpoint
Write pattern	client.commit.apply(...) or OperationBuilder	wh commit submit ...	warmhub_commit_submit tool
Read pattern	client.thing.head(...)	wh thing list	warmhub_thing_head tool
Real-time	client.live.subscribe(...)	wh thing list --live	Claude Code only, via wh channel (research preview)
Get started	Connect via SDK	Connect via CLI	Connect via MCP

GUI chat clients (Claude Desktop, claude.ai, ChatGPT web) connect through the same MCP endpoint — they don’t have a separate row because they share MCP’s backend behavior; the difference is setup, not capability.

The first query section at the bottom shows how each surface reads from the public warmhub-data/us.congress.trades 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.

Authentication

WarmHub authenticates one of two ways, depending on the surface and environment:

• OAuth (interactive) — MCP clients like Claude Code and Cursor handle login on first use, and the wh CLI signs in with wh auth login. This is the default in Claude Code and Cursor.
• Personal access token (PAT) — used by the SDK and required in CI/CD, headless environments, WSL2, and any MCP client without OAuth.

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

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

The token is printed once. Copy it now and export it:

export WH_TOKEN=eyJhbGciOi...

See Personal Access Tokens for scopes and rotation. Each Connect-via section below opens with the auth it expects.

Connect via MCP

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

Auth: OAuth by default in Claude Code and Cursor — nothing to set up. On WSL2 or in headless clients, use a PAT via the mcp-remote bridge.

1. Add the MCP server

Pick your client and drop the WarmHub server into its MCP config.

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. For PAT auth in clients that don’t support OAuth, use the mcp-remote stdio bridge.

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

Auth: Pass an access token when you create the client — a PAT is the simplest option. The example below supplies it from WH_TOKEN via auth.getToken.

1. Install the SDK and create a client

The SDK is published to the public npm registry and requires Node 22.2 or later. 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 },
});

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

Auth: wh auth login (interactive) signs the CLI in directly — no PAT needed for everyday use. For CI or headless environments, use a PAT instead.

1. Install 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 or later. 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/us.congress.trades

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.

Connect via GUI chat client

Claude Desktop, claude.ai, and ChatGPT web can each connect to WarmHub’s MCP endpoint directly — no coding environment required. These clients use the same MCP backend as the Connect via MCP path above. The exact connector UI varies by client — consult your client’s documentation for the precise menu paths and field names. The steps below describe the general flow for each surface.

Claude Desktop and claude.ai

Both surfaces support adding a custom MCP connector via their settings UI.

1. Open the connectors or integrations settings in Claude Desktop or claude.ai.
2. Choose to add a custom connector.
3. Enter the WarmHub MCP URL: https://api.warmhub.ai/mcp
4. Complete the WarmHub sign-in prompt that appears — sign in with email, Google, or GitHub.
5. Once connected, WarmHub tools are available in any new conversation.

For exact field names and menu locations, refer to Anthropic’s connector documentation.

Once connected, skip down to Your first query — Via MCP for the prompt to run.

ChatGPT web

ChatGPT’s web interface supports custom MCP connectors. For exact menu paths and current availability, refer to OpenAI’s connector documentation.

The general flow:

1. Open the connector or plugin settings in the ChatGPT web interface.
2. Add a new connector and enter https://api.warmhub.ai/mcp as the endpoint URL.
3. Complete the OAuth authorization flow to connect your WarmHub account.

Once connected, skip down to Your first query — Via MCP for the prompt to run.

Your first query

We’ll use the public warmhub-data/us.congress.trades repo — it has CongressTrade 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/us.congress.trades data on WarmHub. Show me a sample of congressional stock trade disclosures.

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

This prompt works for any MCP-connected surface — Claude Code, Cursor, Claude Desktop, claude.ai, ChatGPT web, or any other MCP-compatible client.

Via SDK

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

Each CongressTrade carries the filing’s filer_name, ticker, amount_range (a disclosure tier like "$50,001 - $100,000"), and transaction_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",
  "us.congress.trades",
  { shape: "CongressTrade", 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 CongressTrade --kind thing --limit 10 --repo warmhub-data/us.congress.trades

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

wh thing view CongressTrade/20034954/bd598743649e738e-2 --repo warmhub-data/us.congress.trades

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/us.congress.trades — congressional stock trade disclosures filed under the STOCK Act, linked to legislator and security records in the companion repos below.
• warmhub-data/us.congress — current and historical members of Congress, plus committees and member assignments.
• warmhub-data/us.securities.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.
• Skills — install the WarmHub skills so your coding agent designs repos, plans ingestions, and builds apps with WarmHub context loaded.
• 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.