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.

This walkthrough assumes a signed-in client because it includes builder-tier steps such as warmhub_repo_describe and warmhub_thing_create. Several read tools — including warmhub_capabilities, warmhub_thing_head, warmhub_thing_get, warmhub_thing_query, warmhub_shape_list, and warmhub_shape_get — are available anonymously on public repos, so a token is not required for those calls alone.

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, totalCount, plus breakdowns by kind and by shape. subscriptionCount and example subscription names are included only with effective repo:configure access; otherwise they are omitted, not reported as zero or an empty list.
• Sample wrefs — example references the agent can use immediately
• Write examples — ready-to-use operations tailored to the repo’s actual shapes; drop each example’s operation field and pass it as an item to the matching write tool, such as warmhub_thing_create for an add

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_thing_create

Create things and assertions with warmhub_thing_create; its siblings warmhub_thing_revise, warmhub_thing_retract, warmhub_thing_restore, warmhub_thing_rename, and warmhub_assertion_reaffirm make the other versioned changes. 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_thing_create",
  "arguments": {
    "orgName": "my-org",
    "repoName": "my-repo",
    "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "committer": "claude",
    "message": "Add initial game locations",
    "items": [
      {
        "name": "cave",
        "shapes": ["Location"],
        "data": { "x": 3, "y": 7, "label": "Dark Cave" }
      },
      {
        "name": "cave-safe",
        "shapes": ["Observation"],
        "data": { "about": "cave", "safe": true, "confidence": 0.8 }
      }
    ]
  }
}

submissionId is required for the commit-style write tools (warmhub_thing_create and its siblings warmhub_thing_revise, warmhub_thing_retract, warmhub_thing_restore, warmhub_thing_rename, and warmhub_assertion_reaffirm) — 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 items 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 write fails in a way where you cannot tell whether the server already applied it — for example, the write timed out or hit an internal error after it was submitted — 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 either that eventRequestId or, if the response itself was lost, the submissionId you sent with the commit; pass exactly one. For warmhub_repo_content_set, warmhub_collection_create, and warmhub_collection_revise, pass the eventRequestId you supplied with those calls instead of a submissionId.

Each MCP write tool carries one operation kind: warmhub_thing_create adds, warmhub_thing_revise revises, and so on. A workflow that spans kinds, such as retracting one Thing and adding another, is separate calls with separate receipts. Mixed-operation single-commit batches are available through the CLI and SDK. The response payload may include per-item results — inspect each item’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": "cave"
  }
}

This returns all active Observation assertions about 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.

Most write tools take a retry ID: submissionId or eventRequestId. The tools that write things and assertions — warmhub_thing_create, warmhub_thing_revise, warmhub_thing_retract, warmhub_thing_restore, warmhub_thing_rename, and warmhub_assertion_reaffirm — require a submissionId UUID; reuse it when retrying rather than minting a new one. warmhub_component_install and warmhub_component_uninstall also require a submissionId. The tools warmhub_thing_redact, warmhub_thing_remove, warmhub_thing_rewrite, warmhub_repo_content_set, warmhub_collection_create, and warmhub_collection_revise require an eventRequestId UUID instead; supply a new one per write and reuse it to retry. Other write tools, such as warmhub_repo_create and the subscription tools, take neither. 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 item’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 their name, such as cave (local), or wh:org/repo/cave (canonical); a Shape is hub/shapes/Location. 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