Quickstart: MCP

WarmHub exposes an MCP (Model Context Protocol) server so AI agents can read and write structured knowledge using standard tooling. This guide covers how to connect, configure, and start using it.

Prerequisites

Before connecting via MCP, you should have a WarmHub organization and repository set up. If you haven’t done this yet, follow the CLI Quickstart first to create your org, repo, and initial data. The MCP tools work best when there’s existing data to interact with.

What is MCP?

The Model Context Protocol is an open standard for AI agent tool use. Instead of building custom integrations, any MCP-compatible client (Claude Desktop, Cursor, custom agents) can discover and call WarmHub tools automatically. The agent sees typed tool definitions, calls them with JSON arguments, and receives structured responses.

MCP Endpoints

WarmHub provides two MCP endpoint modes, both served over HTTP POST:

Mode	Endpoint	When to use
Global	POST /mcp	Agent works across multiple repos; passes orgName/repoName as tool arguments
Repo-scoped	POST /mcp/:org/:repo	Agent targets a single repo; org/repo is baked into the URL

Repo-scoped mode is simpler for most use cases — the agent never needs to specify which repo it’s talking to, and the tool set is trimmed to only repo-relevant operations.

Configure Your MCP Client

Point your MCP client at the WarmHub MCP endpoint. Claude handles authentication automatically — it discovers the OAuth flow, opens a browser for login, and attaches tokens to all subsequent requests.

Add an entry to the mcpServers section in your client’s settings file.

For repo-scoped mode (recommended):

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

For global mode:

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

In repo-scoped mode, replace myorg/myrepo with your organization and repository names. This works in Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json), and other MCP-compatible clients.

Can’t use OAuth?

If your organization restricts custom MCP connectors, or you’re on WSL2 where the OAuth callback can’t reach the browser, you can authenticate with a personal access token instead.

First Steps with MCP

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

1. Orient with warmhub_repo_describe

Start by calling 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_apply 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.

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

3. Write data with warmhub_commit_apply

Create or update things and assertions through atomic commits:

{
  "name": "warmhub_commit_apply",
  "arguments": {
    "author": "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 commit can contain multiple operations that succeed or fail atomically. Operations support add and revise variants for shapes, things, assertions, and collections.

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

The describe tool is your bootstrap. warmhub_repo_describe returns everything an agent needs to start working — schema definitions, sample data references, wref syntax rules, and commit contract documentation with write examples. Call it first.

All changes go through commits. Every call to warmhub_commit_apply produces an atomic, attributed commit with full version history.

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, workspaces, subscriptions, and actions. See the MCP Tools Reference for the complete list with argument schemas and descriptions.

Next Steps

• Core Concepts — if you haven’t already, review the data model behind things, assertions, and commits
• CLI Quickstart — explore WarmHub from the terminal with the wh CLI
• MCP Server — detailed MCP server configuration and deployment
• MCP Tools Reference — full reference for all MCP tools