The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Honesty MCP listing page.
Try the kits in your browser → · Part of honesty kits, a family of small checks for the claims an AI product makes.
An MCP (Model Context Protocol) server that exposes eleven already-built, zero-runtime-dependency "honesty SDK" TypeScript libraries as tools any MCP-compatible coding agent (Claude Code, Claude Desktop, or any other MCP client) can call while building or auditing a product — grounded-citation checking, evidence corroboration grading, payout/mutation-invariance checks (scenario-tested, not a formal proof for every possible input), trust/ authenticity scoring, provenance-claim validation, a claims registry, a tamper-evident audit chain, and recommendation/decision grading plus engine-vs-human divergence, plus scaffolding for two runtime-library kits that don't fit the "check this content" shape.
This server is thin by design: every tool is a Zod input schema plus a handler that imports and calls the real, unmodified export from the wrapped kit. It does not reimplement any of the underlying logic.
Then ask your coding agent to run check_grounding on a draft answer and its
sources. Each sentence comes back as grounded, placeholder, ungrounded or
invalid (a citation whose source is missing from the evidence). It checks
structure only: it does not decide whether a source is true.
Thirteen tools are listed by default. The three paths that run JavaScript the
agent sends are off unless you set HONESTY_MCP_ENABLE_CODE_EXEC=1; read
A note on the code-execution tools first.
honesty-mcp is published on npm and wraps its eleven sibling "honesty SDK"
kits as ordinary registry dependencies (semver ranges, not local file:
paths) — npm install (or a plain npx) resolves everything from the
public registry, with nothing else to check out first.
The fastest way to run it, with no install step at all:
Or add it to a project:
Claude Code:
Any other MCP client that reads an mcpServers config (Claude Desktop's
claude_desktop_config.json uses the same shape):
Three of the tools run JavaScript that the calling agent sends, so they are
off by default. To use them, add the environment variable
HONESTY_MCP_ENABLE_CODE_EXEC=1 to the server's environment (see
A note on the code-execution tools
first):
The server runs on the stdio transport — it reads JSON-RPC requests from stdin and writes responses to stdout, logging only a one-line startup banner to stderr so stdout stays a clean JSON-RPC channel. This is the transport Claude Code, Claude Desktop, and most local/CLI MCP client integrations expect for a locally-run server; it is not an HTTP server and has no port to browse to.
honesty-mcp also ships a server.json (validated against the official
schema) so it can be listed on the
official MCP registry,
under the name io.github.lkopietz3-byte/honesty-mcp. Listing is a manual,
one-time step the maintainer runs after this package is on npm — it is
not run as part of this repo's CI or npm publish. Exact commands,
from the registry's own docs
(publishing guide,
CLI reference):
package.json's mcpName field (io.github.lkopietz3-byte/honesty-mcp)
must match server.json's name field exactly — that's how the registry
verifies the npm package and the registry listing belong to the same
publisher (see
package-types.mdx, "Ownership Verification").
9 content-checking kits, 12 tools (kits 1–9: hand one of these real content or data, get back a structured verdict):
| Tool | Wraps | One-line purpose |
|---|---|---|
check_grounding | grounding-kit | Checks citation structure in AI-generated text, sentence by sentence: uncited claims, honest placeholders, and citations whose marker is missing or whose evidence doesn't match lexically. Structural only; it does not verify that the evidence is true. The word-overlap matcher rejects some faithful paraphrases and accepts a wrong figure or a negated claim when most words overlap, so read invalid as "send to a person". |
corroborate_evidence | corroboration-kit | Reports the evidence direction (supports / contradicts / mixed / none) and a graded verdict from distinct sources, not a vote count. With corroboration-kit 0.3 and later, sources count by independent origin (pages of one site count once unless you declare an origin). Independence is not verified, and confirmed can mean confirmed-contradicted, so read the direction first. |
check_payout_invariance | payout-invariance-kit | Checks, for the scenarios you supply, whether a ranking engine's output changes with who pays more (runtime mode, off unless HONESTY_MCP_ENABLE_CODE_EXEC=1) or whether payout identifiers appear in source text you send (static-imports mode, always available; it never reads files from disk). Static matching is whole-word: commission does not match commissionRate, so list full names or, with payout-invariance-kit 0.3 and later, pass matchIdentifierParts: true. Not a formal proof for every possible payout configuration. |
check_mutation_invariance | mutation-invariance-kit | Off unless HONESTY_MCP_ENABLE_CODE_EXEC=1 (it is not listed otherwise). Checks, for the scenarios you supply, whether a decision/score/ranking function's output depends on a variable it claims not to (protected attribute, geography, price, or anything you name). Not a formal proof for every possible input. |
score_trust_identified | trust-core (identified) | Scores an entity from known, identified contributors (reviewer accounts, raters, inspectors), shrinking thin evidence toward a prior. With no weighted evidence it returns the prior with insufficient confidence, not a measured score. |
assess_anonymous_authenticity | trust-core (anonymous) | Scores unattributed/scraped sentiment on how organic it looks, with a heuristic discount for two specific patterns (source concentration, unusually uniform sentiment). It does not detect fabrication or verify independence, it is not a sentiment ranking (a strongly negative corpus scores lower than a positive one), and it reports no score () when no signal carries weight. |
2 scaffolding tools (agent-receipt-kit, cost-governor-kit — these are
runtime libraries a project installs and imports into its own running
code, not something checked on-demand the same way; see the code comments
in src/tools/agentReceiptScaffold.ts / costGovernorScaffold.ts for why a
"check this content" shape would misrepresent them):
| Tool | Wraps | One-line purpose |
|---|---|---|
scaffold_agent_receipts | agent-receipt-kit | Explains the issue-a-packet / verify-the-claim authorization pattern for AI agents, with an install step, a starter snippet, and (optionally) a live accepted/rejected worked example run against the real kit. |
scaffold_cost_governor | cost-governor-kit | Explains the estimated pre-call spend check + cache-aware pricing math (default 0.1x cache-read rate, overridable per model via cacheReadPerMillion) + advisory (not concurrency-safe) check-then-commit usage-counting pattern (a commit failure after a successful call returns commitError instead of discarding the result), with an install step, a starter snippet, and (optionally) a live worked example. |
That's 9 kits, 12 content-checking tool slots (payout-invariance-kit, audit-chain-kit, and advice-ledger-kit each got 2 tools instead of 1, since each bundles two genuinely distinct operations — runtime check vs. static grep; append vs. verify; grading one decision vs. measuring divergence across a whole population — that read better as separate, single-purpose MCP tools than as one tool with a mode switch) plus 2 scaffolding tools = 14 tools total.
That is 14 tools when code execution is enabled. With it off (the default),
check_mutation_invariance is not listed, so a client sees 13.
These tools are off by default. check_payout_invariance (runtime mode)
and check_mutation_invariance wrap kit functions whose real signature takes
an actual JavaScript function (a ranking function, a mutation closure);
there is no way to represent a function as MCP JSON arguments. Both tools
accept that function as a source-code string and build the real function
via the Function constructor, inside the worker that src/lib/runFunctionJob.ts
starts after the code-execution switch check, before calling the unmodified kit
export with it. (src/lib/buildFunction.ts is the same builder kept as an
independently tested reference copy; nothing calls it at runtime.) compute_divergence's optional
config.groupBySource uses the same mechanism for advice-ledger-kit's
groupBy config function, but only when a caller actually supplies it, and
omitting it (the common case) needs no code execution at all, since the
library's own default groups by each pair's group field. This is equivalent
to eval for that one string.
Because an agent that has been fed hostile text could be talked into sending
code, the server only offers these paths when the operator turns them on by
setting HONESTY_MCP_ENABLE_CODE_EXEC=1 in the server's environment. Exactly
1 enables them; any other value (true, yes, 0, empty) leaves them off.
While they are off:
check_mutation_invariance is not registered, so it does not appear in the
tool list.check_payout_invariance is listed with static-imports mode only.compute_divergence is listed without the groupBySource input, and sending
it is rejected.runFunctionJob (src/lib/runFunctionJob.ts), the one place caller
JavaScript is ever run, refuses to start a worker. Its error names
HONESTY_MCP_ENABLE_CODE_EXEC.Every other tool is unchanged. The default is one named constant,
CODE_EXEC_ENABLED_BY_DEFAULT in src/lib/codeExec.ts.
Turning it on does not isolate anything. The code still runs with this
process's full filesystem, network and environment access. It is the same trust
model as the agent running node -e or vitest run itself, and it is not
designed to be exposed to untrusted, remote, or adversarial input. Only enable
it for a server driven by a trusted local agent, and only pass code you wrote
or trust.
check_payout_invariance's static-imports mode takes files as a map of
path to file content that the caller sends. A list of paths is rejected with an
error. The wrapped kit would read any readable path it was given and return the
matching lines, which would let an agent read arbitrary files from the machine
one line at a time, so this server does not pass paths through. To scan files,
have the agent read them and send the text.
All three of these run inside a worker_threads Worker with a bounded
timeout (src/lib/runFunctionJob.ts), not on the server's own main
thread. Earlier versions called the built function synchronously in-process,
so a while (true) {} source string would block the entire stdio server
forever — every other in-flight or future tool call along with it. Now, if
the worker doesn't finish within the timeout (default 10 seconds,
override with the HONESTY_MCP_WORKER_TIMEOUT_MS environment variable, in
milliseconds, from 1 to 2147483647), it is forcibly terminate()d and the
tool call returns a clear timeout error instead of hanging. Console output
from the supplied code (console.log, console.error) is captured and
written to the server's stderr with a [honesty-mcp worker] prefix, capped
at 16 KiB per call, so it doesn't reach stdout, which carries the MCP
protocol. Code that writes to file descriptor 1 directly (for example with
fs.writeSync(1, ...)) is not intercepted and can corrupt the protocol
stream; that is part of why this is not a sandbox. This is not a sandbox — the
worker has this process's full OS-level privileges (filesystem, network,
environment variables) — it only bounds time. It does not stop caller
code from reading your filesystem, making network requests, or doing
anything else this Node process itself can do. The trust model above still
applies in full: only pass code you wrote or trust, and don't expose this
server to untrusted, remote, or adversarial input.
This server depends on the newer release line of each wrapped kit (the ranges
in package.json). The table lists what that line changes compared with the
0.2 line that honesty-mcp 0.2.x used. At start-up each tool reads the installed
kit's version, words its description for that version, and refuses an input
that the installed kit would silently ignore (for example matchIdentifierParts
with payout-invariance-kit 0.2, if an override installs it) instead of
pretending it worked.
| Kit | Version | What it changes through this server |
|---|---|---|
| grounding-kit | 0.3.0 | Each unit carries reasons, and the result lists nonClaims. Verdicts move in both directions (sentence boundaries after abbreviations, closing quotes and dashes; rules and table separators are no longer units). |
| corroboration-kit | 0.3.0 | Sources count by independent origin. New inputs origin, derivedFrom and inferOrigins; the result gains groups. A verdict can only get stricter. |
| payout-invariance-kit | 0.3.0 | New input matchIdentifierParts; identifiers are trimmed and matched in any script; a runtime ranking function that returns nothing is an error. |
| mutation-invariance-kit | 0.3.0 | An edit made in place to a mutated input is an error; scenarios with the same name are renamed name (2). |
| trust-core | 0.3.0 | Anonymous scores change (small and single-source corpora score lower); new config.fullCountWeight; evidence dated in the future is scored as undated. |
| provenance-kit | 0.3.0 | Verdicts move in both directions (more negation cues and asserting idioms, look-alike letters). A trailing space in a custom phrase no longer prevents the prefix match. |
| claims-registry-kit | 0.4.0 | A claim more than maxAgeDays x 24 hours old is stale (exact milliseconds); a placeholder evidenceRef is unverified. |
| audit-chain-kit | 0.3.0 | The verify result gains entriesChecked. |
| advice-ledger-kit | 0.3.0 | An exact tie in the bad rate is not-holding (it was holding). |
| agent-receipt-kit | 0.3.0 | Scaffold only: the worked example's results gain snapshot and uncoveredFactKeys. |
| cost-governor-kit | 0.3.0 | Scaffold only: the guidance mentions the newer admission-control API. |
test/kitCompat.test.ts runs the matching branch for whichever line is
installed. With the current ranges that is always the newer line, so the
older-line checks can be removed in a later release.
check_payout_invariance, check_mutation_invariance, and
compute_divergence's worker-thread timeout bounds time only, not
behavior — see "A note on the code-execution tools" above. It is not a
sandbox, and these paths are off unless HONESTY_MCP_ENABLE_CODE_EXEC=1.SERVER_VERSION (src/server.ts) and package.json's version are
still bumped by hand. test/drift.test.ts now fails if they, or the two
versions in server.json, disagree, but nothing bumps them for you.To work on this server itself (rather than just use it), clone the repo and build from source:
trustScore: nullcheck_provenance_claims | provenance-kit | Flags certainty-implying language ("(verified)", "guaranteed") not backed by an appropriate provenance tier. The default phrase list is short (eleven phrases) and phrases match as word prefixes. |
check_claims_registry | claims-registry-kit | Buckets public-facing claims as current / stale / unverified against their linked evidence and last-verified date. With claims-registry-kit 0.4 and later, a placeholder reference such as TODO is unverified and the age limit is exact to the millisecond. |
append_audit_entry | audit-chain-kit | Appends one entry to a hash-chained, tamper-evident audit log. |
verify_audit_chain | audit-chain-kit | Independently re-verifies a hash chain from genesis (an empty chain is valid with nothing checked); detects mutation and severed links unconditionally, plain tail deletion with expectedMinLength, and truncate-and-re-append (or a full rewrite) only with anchor; expectedMinLength alone does NOT catch a truncate-and-re-append. |
grade_decision | advice-ledger-kit | Grades one recommendation-and-decision pair against a before/after observation log, exposure-aligned, with separate floors per window and machine-readable refusal codes. holding requires both the exposed bad count to stay under refuteThreshold AND its bad rate to be below the baseline's (exact comparison, not the rounded badRate; with advice-ledger-kit 0.2 an equal rate also held); either failing is not-holding. The refute bar is a fixed count, not a rate (see the tool description). |
compute_divergence | advice-ledger-kit | Measures how often an engine and a human disagreed, and where a later outcome exists, reports engine-right/human-right as separate, never-blended counts. The optional custom groupBySource input is off unless HONESTY_MCP_ENABLE_CODE_EXEC=1. |