Usage

Four minutes to a first useful line.

Two things have to be true before this helps you: the server has to be reachable from your assistant, and your question has to name a situation with parts in it. The first is a paste-and-forget; the second is the part worth reading.

1. Connect it

Create an account, then create an API key on your account page. The key is shown once.

{
  "mcpServers": {
    "TrueHeading-MCP": {
      "url": "https://<your deployment>/mcp",
      "headers": { "authorization": "Bearer <your key>" }
    }
  }
}

The endpoint is the same for every client; the key is the only identity used. There is no project, team or workspace to configure, and a second key is a second key, not a second account.

2. Phrase it around something with parts

This is the whole skill. The answer is a pointer, so the question has to contain somewhere for a pointer to land: an artefact, a relationship, a tension, a set of constraints. Describe the situation and say what you are unsure of. Do not ask for a verdict.

• Good: “the retry loop doubles work on the same row and I cannot see where — here is the shape of it, name the first place to read.”
• Good, and the one people miss: “I am about to build X; these are the constraints and these are the parts. Where is it most likely to give way?” You can ask about something that does not exist yet, as long as you give it its parts.
• Wasteful: “what is broken?” — nothing to point at.
• Refused, by design: “is this design right?” — that is a decision, and the decision stays with you.

Nothing but your words is sent — no file, no diff, no repository contents — so the sentence has to carry the situation. It is not given your code, and nothing of yours travels with the question, which is a limit and a guarantee at once: it cannot leak what it was never handed.

3. Read what came back

a line

A direction: an artefact or a relationship, and what to check there. Go and look. A line you read and did not act on is a line you did not receive.

X

Nothing to point at, for the question as you phrased it. A real answer, and a useful one: restate the matter with more of it in the sentence.

no line came back

Our side failed — a provider error or a timeout. Nothing was charged, and nothing was invented. Retrying is reasonable; it is not the same as X.

The loop is ask → go look → change something → ask again with what the look turned up. Two or three rounds on one problem is normal. A fifth is usually you seeking reassurance rather than looking, and the answers start to repeat: that is the signal to stop.

4. The panels, in one sentence each

Seven tools, and the difference is what they take. Three take your words and answer with one line: ask, review, debug — and those three are one call described for a different moment, not three tools with three rules: any of them takes any question, so pick by what you are doing rather than by what you think you are allowed to ask. nudge takes nothing — its one question is fixed on the server, because a question the caller composes is a question you have published — and answers with one line. checkup and sharp take nothing and ask seven fixed questions in one pass, so you get seven labelled lines back: the second is the same shape, aimed at the failure modes this kind of work actually has.

Use a panel when you are about to call something finished, not instead of looking. It costs more than a single question because it asks more; the account page shows exactly what.

On the wire those names carry the vendor and the product in front — ripplenav_trueheading_ask, ripplenav_trueheading_checkup — because a client shows one flat list of every server's tools. This page uses the short form; it is the same tool.

The seventh is balance: no arguments, and it costs nothing — it makes no call to a model, it just reads how many units are left and what a call to each tool spends. Ask it before a long run, or when something refuses because the units ran out.

5. What it costs, and what runs out

• You buy units in advance. Each call spends its own share — a single question spends the least, a panel more, and the schedule is on your account page.
• Units are not money: no cash value, not refundable, and each purchase lasts the period shown when you buy it (twelve months at the time of writing). Buying more does not extend what you already hold, and the expiry date of each purchase is on your account page. The terms govern all of this.
• A failed call is never charged. An answer of X follows your account's setting, which the operator can set either way.

6. For whoever is writing their own client

POST /mcp      JSON-RPC 2.0, protocol 2024-11-05, bearer auth
tools/list     seven tools
tools/call     ask | review | debug   { "question": "1..2000 chars" }
               nudge | checkup | sharp  {}   (no arguments; anything sent is ignored)

Errors are ordinary JSON-RPC errors: -32602 for a missing or malformed question, -32603 when our side failed, and HTTP 401 for a missing or unknown key. The rate limit answers 429 with a retry-after header.