MCP Tool Walkthrough

New to MCP?

Start with the Quickstart to set up your client first. This page assumes you already have an MCP-connected agent pointed at WarmHub.

Try it against live data

The walkthrough below uses a generic game-world example for clarity. To run it against real data, point your authenticated MCP client at the public warmhub-data/us.congress.trades repo and walk the same warmhub_capabilities → warmhub_repo_describe → read-tools sequence against the CongressTrade shape. Other public repos in the warmhub-data org work too — let warmhub_repo_describe tell you which shapes each one exposes.

The walkthrough interleaves reads and writes: run steps 1-3 and 5 against warmhub-data/* (the discovery + read steps — substitute your target repo’s shapes from warmhub_repo_describe’s output for the placeholder Location/Observation payloads), and skip step 4 (the write step) on public datasets — it needs permission on the target repo. To run writes, pass a repo you own as the orgName/repoName arguments.

The WarmHub MCP server requires a token even for public-repo reads, so make sure your client is signed in first.

Once connected, an agent can interact with WarmHub using the tools below. Here is the recommended sequence for bootstrapping.

1. Discover the catalog with warmhub_capabilities

Call warmhub_capabilities first to see which tools are callable on the current endpoint, grouped by category, plus a short workflow cookbook and the wref syntax reference:

{
  "name": "warmhub_capabilities"
}

The payload is static (no arguments).

Use this as your catalog index, then follow up with warmhub_repo_describe for per-repo specifics.

2. Orient to the repo with warmhub_repo_describe

Call warmhub_repo_describe to get a complete picture of the repository:

{
  "name": "warmhub_repo_describe",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo"
  }
}

This returns:

• Shapes defined in the repo, including field types, optional shape-level descriptions, and per-field inline descriptions extracted from typed field objects (fields with descriptions appear as { "type": "number", "description": "Horizontal position" })
• Summary counts — shapeCount, subscriptionCount, totalCount, plus breakdowns by kind and by shape
• Sample wrefs — example references the agent can use immediately
• Write examples — ready-to-use warmhub_commit_submit operations tailored to the repo’s actual shapes

The write examples are generated from the repo’s current shape definitions, so the agent gets correct field names and types without guessing.

3. Read current state with warmhub_thing_head

Get a snapshot of all active things:

{
  "name": "warmhub_thing_head",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo"
  }
}

Filter by shape or kind for targeted results:

{
  "name": "warmhub_thing_head",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo",
    "shape": "Location",
    "limit": 10
  }
}

4. Write data with warmhub_commit_submit

Create or update things and assertions with versioned write operations. The committer wref below must already resolve to an existing thing — create the agent identity in a prior write, or omit committer to attribute the write to the authenticated user.

{
  "name": "warmhub_commit_submit",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo",
    "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "committer": "Agent/claude",
    "message": "Add initial game locations",
    "operations": [
      {
        "operation": "add",
        "kind": "thing",
        "name": "Location/cave",
        "data": { "x": 3, "y": 7, "label": "Dark Cave" }
      },
      {
        "operation": "add",
        "kind": "assertion",
        "name": "Observation/cave-safe",
        "about": "Location/cave",
        "data": { "safe": true, "confidence": 0.8 }
      }
    ]
  }
}

submissionId is required — supply a UUID (e.g. crypto.randomUUID() in JavaScript, uuid.uuid4() in Python, or any standard UUID v4 generator) that identifies this logical submission. The tool validates this field before attempting the write; omitting it or supplying a non-UUID value will fail before any operations are applied.

Retries must reuse the same submissionId. Minting a new UUID on a retry changes the request identity and will not be treated as a retry of the original submission. If a call fails with an ambiguous append error, its structuredContent.error.data carries an eventRequestId alongside lookupTool: "warmhub_commit_receipt_get". Call that tool with the eventRequestId to check whether the write landed before deciding whether to retry — warmhub_commit_receipt_get takes eventRequestId, not submissionId, and rejects unknown arguments.

A single MCP write request can carry multiple operations across add (shapes, things, assertions, collections), revise (shapes, things, assertions, collections), retract (any entity kind), and rename (any entity kind). The response payload may include per-operation results — inspect each operation’s outcome individually, as partial failures are a normal success payload that callers must handle. See the MCP Tools Reference for the exact response shape and Writes for the cross-surface contract.

5. Query with warmhub_thing_query

For targeted retrieval by shape, kind, or about-reference:

{
  "name": "warmhub_thing_query",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo",
    "shape": "Observation",
    "about": "Location/cave"
  }
}

This returns all active Observation assertions about Location/cave.

Key Concepts for Agents

Discover, then describe. Start with warmhub_capabilities to learn what tools are callable on the current endpoint, then call warmhub_repo_describe for schema definitions, sample data references, wref syntax rules, and write contract examples tailored to the repo.

warmhub_commit_submit requires a submissionId. Supply a UUID identifying the logical submission, and reuse it when retrying rather than minting a new one. If a write fails and you cannot tell whether it landed, look up the receipt before retrying — the error tells you which value to look it up by. Partial failures are a normal success payload, so inspect each operation’s outcome individually. See Step 4 above and the MCP Server page for the failure taxonomy and payload shapes.

Wrefs address everything. Things are referenced by Shape/name (local) or wh:org/repo/Shape/name (canonical). Assertions use about to reference their subject.

Prefer warmhub_thing_query for targeted reads. Use warmhub_thing_head for broad orientation and warmhub_thing_query when you know what shape or subject you need.

Full Tool Reference

WarmHub exposes MCP tools covering organizations, repositories, shapes, things, assertions, commits, subscriptions, actions, and meta (capability discovery). See the MCP Tools Reference for the complete list with argument schemas and descriptions.

Next Steps

• Core Concepts — review the data model behind things, assertions, and writes
• MCP Server — detailed MCP server configuration and protocol details
• MCP Tools Reference — full reference for all MCP tools
• Agent Context (wh prime) — CLI-side bootstrapping for agents with shell access