Honest Reasoning

Free, self-hosted MCP server. Attach it to any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, etc.) to get three tools that push back against a specific, measured failure mode: AI usage that quietly increases your workload instead of reducing it (surface-plausible output that isn't actually verified, decisional over-trust in AI claims, and review attention spent on the wrong things).

Free for personal/non-commercial use, no redistribution — see LICENSE.md. You run this yourself, with your own OpenAI API key — nothing is sent to any server we operate.

Tools

• honest_reason — structures any analysis/output-review/task around 4 disciplines: ruthless simplification, calibrated confidence labels (with a hard-coded guardrail — a model can't self-report "strong" confidence on fewer than 3 pieces of evidence, the code overrides it), falsification search, and honest limits.
• check_alignment_drift — logs every honest_reason call's "honest limits" locally, and detects when the same gap keeps recurring (e.g., "idempotency key never verified" showing up across many PRs). Pure embedding-similarity clustering, no LLM judgment, deterministic. Verified scope: catches literal/near-literal recurring gaps. Does not currently generalize across differently-worded gaps that share only an abstract category — that would need an added classification layer (not built yet).
• review_scope_card — turns a list of changed files/symbols (with reference counts you compute yourself, e.g. via grep) into a deterministic attention budget: what's worth reading carefully vs. safe to skim, given limited review time.

Setup

npm install

Set your OpenAI key (required — this connects to your OpenAI account, you pay for your own usage):

export OPENAI_API_KEY=sk-...        # macOS/Linux
$env:OPENAI_API_KEY = "sk-..."      # Windows PowerShell

Optional env vars:

• OPENAI_CHAT_MODEL (default gpt-4o-mini — cheaper; set to gpt-4o for higher quality)
• EMBED_MODEL (default text-embedding-3-small)
• HONEST_REASONING_DATA_DIR (default ~/.honest-reasoning — where check_alignment_drift's local signal log lives)

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "honest-reasoning": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Claude Code / Cursor (or any client that reads .mcp.json)

{
  "mcpServers": {
    "honest-reasoning": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Verify it works

node test/smoke.mjs /tmp/honest-reasoning-test-data

Runs review_scope_card and check_alignment_drift without needing an API key, plus confirms honest_reason gives a clear setup error if the key is missing. With OPENAI_API_KEY set, it also exercises the live LLM call.

What this is not

Not a fact-checker, not a source of truth. It structures how an AI reasons about uncertainty — confidence labels, falsification conditions, disclosed limits — it does not verify facts against the world. Don't use it as the sole basis for financial, medical, legal, or safety-critical decisions.