The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Rithmo listing page.
Runnable examples for connecting to Rithmo's read-only MCP server.
Rithmo is a system of record for decisions. This server lets your tools query the decision record before they act — "what did we actually decide about X?" — and react when decisions change. Rithmo emits the record; your tools act on it. Rithmo never takes actions in your systems.
It speaks the Model Context Protocol, so it works with n8n, AI agents, and anything else that speaks MCP.
New here? Start with the Integration Guide — what it is, how to get access, how to connect, and the full tool reference.
Set two values in .env:
RITHMO_MCP_URL — the MCP endpoint of a Rithmo instance. Rithmo Cloud is
https://app.rithmo.ai/api/mcp; a self-hosted deployment exposes the same server at
your own address.RITHMO_MCP_TOKEN — a per-organization Rithmo MCP service token (read-only, scoped to
one org, carrying the mcp:read scope).Then:
query_decision — the current decision, or no_record:
no_record — Rithmo will not fabricate a decision (the differentiator):
A no_record may carry a typed refusal explaining why it is held:
list_decision_changes — a cursor-drained feed of decisions changing state:
query_decisionLook up the current authoritative decision for a natural-language question.
Input
| field | type | required | notes |
|---|---|---|---|
question | string | yes | e.g. "Are we still shipping the new onboarding flow?" |
type | action_item | follow_up | decision | no | restrict to one type |
owner | string | no | restrict to a named owner (substring match, case-insensitive) |
area | string | no | topical hint to bias retrieval |
surface | string | no | the external system this task concerns (e.g. "jira", "salesforce"). When Rithmo does not observe that surface, a miss returns a typed not_observed instead of a bare no_record — absence on an unobserved surface is unknown, not "no". |
Output — a discriminated union on result with three variants:
"found", "found_record", and "no_record".
⚠️ Do not write
result === "found" ? act : treat-as-no-record.found_recordis a real answer, and two-state branching silently routes valid answers into your no-record path.But do not flip to
["found", "found_record"].includes(result)either — that is also wrong. Afound_recordcan name a subject that is genuinely on record while carrying no answer text (subject.currentAnswer === null). The correct rule gates on a usable answer:
result: "found" — a live answer from the commitment ledgersupersedes is the supersession history. It is a linked list, newest-first: each node
is a prior decision this answer replaced, with its own supersedes pointer. Walk it to
reconstruct how the answer changed over time (e.g. cloud → private env → customer
servers). null means this decision superseded nothing. The chain is cycle-guarded and
capped at 12 hops.
result: "found_record" — a live answer from the subject recordReturned when the subject record holds a current answer that the commitment ledger does not. This is an answer, not a refusal.
The answer lives at subject.currentAnswer, not answer.
currentAnswer may be null, and that case is not actionable. The subject is
genuinely on record — Rithmo knows what you are asking about — but there is no answer text
to act on. That is a meaningful signal (the subject exists, its answer does not), and it is
distinct from no_record, which says Rithmo has no confident match at all. Either way you
must hold: route a null-answer found_record down the same path as no_record.
result: "no_record" — no confident answerWhen present, record.status is one of:
record.status | meaning | extra fields |
|---|---|---|
closed | the subject is settled and the premise is dead | disposition: reversed | abandoned | superseded; subject |
no_record | the record was consulted and genuinely has nothing | reason (string) |
not_observed | Rithmo does not observe the surface you asked about, so absence proves nothing | unobserved_surfaces: string[] |
All three carry premise_check, and closed/no_record/not_observed may also carry an
observation.surfaces array describing what was read and over what window.
premise_check.safe_to_proceed is always false when the field is present. It is not
a boolean to evaluate — it is a marker that the answer is held, and held_because tells
you why. Never proceed on a no_record, with or without a premise_check.
One reason value is worth special handling: a record.status: "no_record" whose
reason starts with record_unavailable: means the record could not be read (a transient
failure). That is not "no record" and not "we decided no" — hold and retry.
Notes:
found field except
confidence is byte-identical every call (it's the record verbatim — no LLM in the
response path). confidence is a ranked-retrieval signal and may vary slightly; don't
gate on its exact value.owner and source are discriminated states, never bare nulls — unowned and
unresolved are real, meaningful answers your code can branch on.no_record is expected, not an error. Treat it as a branch: Rithmo has no confident
answer, so don't act on a guess.list_decision_changesDrain decisions whose state changed, since a cursor. Built for a polling trigger.
Input
| field | type | required | notes |
|---|---|---|---|
since | string | no | opaque cursor from a prior call. Omit on the first call to start "from now" (no backfill); pass "0_" to backfill from the start. |
limit | integer | no | 1–200, default 50. Out-of-range or non-integer values are rejected as a validation error, not silently clamped. |
Output
Each change carries the same record core as query_decision's found — including
rationale, conditions, director, and context. It does not carry supersedes,
spine, or confidence; those are query_decision-only.
status is wider here than in found. Reversals are emitted as changes, so status
can be dropped or superseded — values query_decision's found never returns
(it only resolves to live rows). If you mirror this feed into your own store, handle those
two values explicitly.
Cursor semantics:
since) returns changes: [] and the current head cursor. You start
from now and do not replay history. has_more is false.has_more is rows.length === limit — a full page. It can be true on an
exactly-full final page, so the next call legitimately returns zero changes. That is not
an error; it is how the drain terminates.cursor is echoed back unchanged, so re-polling with
it is safe and idempotent.(changed_at, decision_id).whoamiNo arguments. Returns { org_id, scopes } — a quick way to verify your token and
connection.
Every request carries a per-organization service token as a Bearer header:
The token resolves to exactly one organization and must carry the mcp:read scope; every
result is scoped to that org. Keep it in a secret/credential store, never in code.
A request with no token, or an unknown token, is rejected with 401. There is no
anonymous access.
Rithmo's MCP server is described by server.json in this repo, under the
registry identity ai.rithmo/rithmo (version 0.1.0). Full docs live at
https://rithmo.ai/mcp.
The RITHMO_MCP_URL above points at Rithmo Cloud. Self-hosted Rithmo deployments
expose the same MCP server at the customer's own address — same tools, same contract,
different host.
See n8n/ for an importable workflow (query a decision before an execution
step) and setup notes.