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/congress-trading repo and walk the same warmhub_capabilities → warmhub_repo_describe → read-tools sequence against the StockTrade 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/Belief payloads), and skip step 4 (the write step) on public datasets — it needs permission on the target repo. To run writes, repoint your MCP client to a repo you own (e.g. /mcp/<your-org>/<your-repo>).

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) and scoped to the endpoint you connected to (global or repo-scoped).

In repo-scoped mode, global-only discovery tools (warmhub_org_list, warmhub_org_get, warmhub_repo_list, warmhub_repo_create) are omitted.

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"
}

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"
}

Filter by shape or kind for targeted results:

{
  "name": "warmhub_thing_head",
  "arguments": {
    "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 let the authenticated user receive attribution via createdByEmail.

{
  "name": "warmhub_commit_submit",
  "arguments": {
    "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": "Belief/cave-safe",
        "about": "Location/cave",
        "data": { "safe": true, "confidence": 0.8 }
      }
    ]
  }
}

A single MCP write request can carry multiple operations across add (shapes, things, assertions, collections), revise (shapes, things, assertions), and retract (any entity kind). One operation can succeed while another in the same batch fails — warmhub_commit_submit returns a result row for each. Read the rows to see which landed and which need a retry. See the MCP Tools Reference for the exact field 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": {
    "shape": "Belief",
    "about": "Location/cave"
  }
}

This returns all active Belief 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.

MCP writes can succeed in part. warmhub_commit_submit returns a result row per operation, so one failed entry doesn’t poison the batch. See MCP Error Handling for the full failure taxonomy (per-op rows, tool-result errors, and transport-level errors).

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