thinking-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@thinking-mcp help me reason through why our API latency spiked, deep mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
thinking-mcp
An MCP server that forces the host AI to reason through a structured protocol.
The protocol itself calls no LLM: no API key, no GPU, no inference cost. On top of it, an optional quality layer (below) can add a semantic audit, per-problem probes, and verification the server runs itself — off until you configure a provider, and never able to fail a submission.
A CAPABLE AI != AN AI THAT THINKS WELL
The problem is not IQ — it is discipline and structure.The problem
Claude 4 and GPT-5 are already smart enough. What they do when answering freely is skip steps:
Failure mode | Symptom |
Anchoring | Jumps on the first hypothesis |
Overconfidence |
|
Sunk cost | Never backtracks after being shown wrong |
Confirmation bias | Only searches for supporting evidence |
Symptom solving | Fixes the leaf, not the root |
Single hypothesis | Offers one possibility and stops |
No inversion | Never attacks its own idea |
thinking-mcp does not make the model smarter. It makes the model not skip steps.
Related MCP server: jev-harness
What it is / isn't
Is: an MCP server that renders a scaffold, validates structure, and formats output. Isn't: an LLM proxy, a model aggregator, a caching layer, a silver bullet, or "an IQ boost".
┌────────────────────────────────────────────────────────────┐
│ HOST AI (Claude / GPT / Agnes in Cursor) — THE BRAIN │
│ • Reasoning · creativity · context understanding │
└───────────────────────┬────────────────────────────────────┘
│ MCP (stdio)
▼
┌────────────────────────────────────────────────────────────┐
│ thinking-mcp — THE COACH │
│ • Scaffold protocol · validate · format │
│ • 0 API calls · 0 API keys (default) │
│ • optional: audit · probes · verify (your key) │
└────────────────────────────────────────────────────────────┘The three modes
QUICK | STANDARD | DEEP | |
When | Simple questions | Most questions | Hard problems |
Steps | 3 | 5 | 11 |
Scaffold tokens (measured, rendered) | ~170 | ~550 | ~1,140 |
For | Factual, lookup | Debugging, design, review | Architecture, strategy, root cause |
The mode is auto-selected from the question text; the caller can always override with
mode="deep". Every mode names its own breaking point: the scaffold tells the host AI
when to switch modes instead of grinding through the wrong depth.
DEEP walks through: Axioms ([TRUTH]/[ASSUMPTION] labels) → Decompose → Root Cause (5 Whys with a multi-cause guard: single-cause linear gets one 5-link chain, multi-cause gets an issue tree with one why-chain per branch) → Explore → Verify (evidence labelled [MEASURED]/[INFERRED]) → Red Team (inversion + tripwires) → System Map → Bias Check (+ base-rate) → Synthesize (bootstrapping pass for estimates) → Self-Critique → Finalize.
Why the guards, and where they come from
The scaffolds carry several evidence-graded guard rails adapted from thinking-framework-skills (an Apache-2.0 library of 63 frameworks graded S/M/P/V/A/C/X) and other reference repos:
Guard | Why | Source |
5 Whys caveat + issue-tree branching | Five Whys is reliable only for simple single-cause linear failures and misleads beyond them (Card 2017) — graded X in the reference library. The scaffold says so and branches multi-cause problems instead. | thinking-framework-skills (Problem Framing) |
| Separate verified facts from inherited conventions so assumptions actually get challenged. | first-principles-thinking-skill |
| Never present an inference as a measurement. | Evidence vs Inference Sort (thinking-framework-skills) |
Red-team tripwires | Premortem's kill criteria: each attack names the observable signal that it is coming true. | Premortem, S/M tier (thinking-framework-skills) |
"When NOT to use" per mode | Every method names where it misleads — mode-mismatch wastes tokens both ways. | thinking-framework-skills (every skill carries one) |
Bootstrapping pass on estimates | Averaging a first estimate with a re-estimate from flipped assumptions measurably beats a single guess (Herzog & Hertwig 2009). | Dialectical Bootstrapping, M tier (thinking-framework-skills) |
Natural-frequency framing | "3 in 1,000" beats "0.3%" for conditional reasoning (Gigerenzer & Hoffrage 1995) — the calibrator warns on bare small percentages. | Natural-Frequency Bayesian Framing, S tier (thinking-framework-skills) |
Not adopted on purpose: ACH (controlled trials found it raises confidence without accuracy — graded X) and Six Thinking Hats-style role lenses (P tier, but the red-team/inversion step already covers the adversarial move). Chain of Draft and token-budget prompting were skipped: the scaffold is a fixed ~1.1k-token cost, and compressing it trades away the very structure being enforced.
Install
Not published to PyPI yet. Install from source:
git clone https://github.com/vipera-iso/thinking-mcp.git thinking-mcp && cd thinking-mcp
uv venv .venv && uv pip install -e .One dependency: mcp. Python ≥ 3.10.
Once published to PyPI, replace the command/args below with "command": "uvx", "args": ["thinking-mcp"] — no clone needed.
Integrate with coding agents
The server speaks stdio (how every MCP host launches local servers). Point your agent at the binary and it gets the think tools:
claude mcp add thinking -- /path/to/thinking-mcp/.venv/bin/thinking-mcp{
"mcpServers": {
"thinking": {
"command": "/path/to/thinking-mcp/.venv/bin/thinking-mcp"
}
}
}{
"mcp": {
"thinking": {
"type": "local",
"command": ["/path/to/thinking-mcp/.venv/bin/thinking-mcp"],
"enabled": true
}
}
}{
"mcpServers": {
"thinking": {
"command": "/path/to/thinking-mcp/.venv/bin/thinking-mcp",
"args": ["--log-level", "error"]
}
}
}It also serves Streamable HTTP for clients without stdio support:
thinking-mcp --http --port 8000 (endpoint :8000/mcp).
Drop .cursorrules into your project so the host AI knows when it must
call think.
Tool surface
Tool | What it does |
| Opens a session and returns the protocol scaffold (not the answer) |
| Takes the JSON response → validates → formats (+ advisory |
| Inspects session state for debugging |
| Lists modes and their scaffold cost |
| Verifies a conclusion: the server runs the refutation itself when the layer is on, otherwise returns prompts |
| Takes the refutation / samples back → verdict + agreement |
The /think <problem> prompt drives the flow: think → reason → think_submit.
Retry flow
think_submit -> validate -- OK --> format + return result
|
FAIL --> { status: "invalid", errors: [...], retry_count: 1 }
| host AI fixes it -> submits again
+-- after 2 failures --> "best_effort" with validation_errorsAfter the retries run out the server does not pretend the result is valid: the status
becomes best_effort and the structural errors are returned verbatim.
Independent verification (think_verify)
Structure enforcement is not the same as being right. think_verify adds two passes that
make the model do independent work:
Pass | What it does |
A. Refutation | A fresh-context pass that never sees the reasoning chain gets only the conclusion and its evidence, and is told to break it. The fresh context is the mechanism — anchoring is the failure mode targeted. |
B. Self-consistency | N answers to the raw problem, majority-voted, so you can see whether the answer is even reproducible. |
Why the host runs the prompts, not the server
MCP was supposed to let the server initiate these calls itself through sampling
(session.create_message). That does not work here: on mcp 2.3.0 both the stdio and the
Streamable HTTP transports raise
NoBackChannelError: Cannot send 'sampling/createMessage':
this transport context has no back-channel for server-initiated requests.— neither transport carries a channel for server-initiated requests, and sampling is deprecated as of 2026-07-28 (SEP-2577). So the server builds the prompts and parses the results, and the host executes them. No API key is involved either way.
The honest weakness
The server cannot enforce that the host ran the refutation in a fresh context. A host
that answers inline from its existing chain gets a weaker version of pass A. The prompt
says so, and the returned output says so too (cannot_enforce).
Neither pass is a judge: A is a model opinion that can reject a correct conclusion, and B
measures reproducibility, not correctness — a confidently wrong answer repeated N times is
still wrong. Both caveats are attached to every result, and when nothing usable comes back
the status is verification_failed with the conclusion labelled UNVERIFIED, never a
pretend-success.
Optional LLM quality layer
Everything above is $0 and needs no key. This layer is the exception, and it is opt-in: with no keys configured it does not exist, and the responses are byte-identical to the version that had no layer at all.
What it adds when configured:
Pass | Fixes | Effect on the result |
Audit ( | "the validator cannot tell a genuine counter from a fake one" | attaches |
Probes ( | a scaffold that cannot know the problem's domain | appends |
Verification ( | "the server cannot enforce a fresh context" | the server calls the model itself; |
Configure it
Keys are read from the environment, or from an existing env file — by default
~/.agentmemory/.env (0600, outside git), so the keys agentmemory already holds are
reused instead of copied:
Variable | Meaning |
|
|
| Env file to read (default |
| Comma/space separated key pool for the OpenAI-compatible provider |
| Key pool for the Gemini provider |
| Singular fallbacks, reused from agentmemory |
| Singular fallbacks for the second provider |
| Per-call timeout in seconds (default 60) |
| Switch one pass off ( |
Agnes (agnes-3.0-flash) is tried first and Gemini (gemini-3.8-flash) is the fallback.
Free tiers rate-limit per key, so a key pool is used: on a 429/5xx the current key is
drained and the next one is tried immediately, which is how "12 rate-limited Gemini
keys" becomes one dependable fallback. When every key of every provider fails, the pass
reports unavailable with the reason, and the submission is unaffected.
What it costs, honestly
Measured on this machine with agnes-3.0-flash (free tier):
Call | Latency | Notes |
probes ( | ~7 s | one call, only when the layer is on |
audit ( | ~9 s | 586 prompt + 458 completion tokens on a standard payload |
refutation ( | ~4 s | plus ~5 s per consistency sample |
Turn it off per pass (THINKING_LLM_PROBES=0) or entirely (THINKING_LLM=0).
The honest weaknesses of the layer
A judge is an opinion, not ground truth — it can call a correct answer hollow. Every
qualityblock says so, and nothing in it can changestatus.The judge can contradict itself. A live run returned
score: 1.0withverdict: "hollow". The contradiction is reported (inconsistent), never averaged away: picking one of the two numbers would be inventing a measurement.Probes cost tokens on every
think, including on problems the protocol already handles well.Self-consistency needs ≥2 samples. One reply is not a majority vote, so the server refuses to run a single sample rather than report
agreement: 1.0from one opinion.Keys never leave the machine and never reach a tool response — asserted in tests.
Validation measures structure, not quality
The host AI can still write a fake counter. The structural validator cannot tell — and
deliberately does not try. With the optional layer off there is no LLM in the loop at all;
with it on, the quality block is a second opinion attached to the result, never a gate.
Validation does not measure quality. It measures structure. The host AI can still write a fake counter. But without structural enforcement, it skips the step entirely.
DEEP, for example, requires: ≥3 assumptions each labelled [TRUTH]/[ASSUMPTION], a
root_cause object with single_cause + branches (1 branch × 5 links if linear,
≥2 branches × 3 links if an issue tree), ≥2 red-team attacks each with a
what_would_change_my_mind and a tripwire, evidence labelled
[MEASURED]/[INFERRED], ≥3 bias checks, and ≥1 piece of disconfirming evidence.
Calibration only warns, never rewrites: confidence: 0.95 with thin evidence returns
a warning and leaves 0.95 untouched — rewriting it would invent a number.
Measured results
agnes-3.0-flash over its OpenAI-compatible API, all 26 tasks in eval/tasks.jsonl,
concurrency 2. Raw output is committed in eval/results/.
.venv/bin/python eval/compliance.py --concurrency 2Two complete runs are committed: the baseline (20261006-123628, 10-step deep scaffold) and the guard-rails run (20261006-143122, 11-step deep with all the guards above). The tables show both where they differ; where only one number is given it is the guard-rails run.
Compliance — does the host AI follow the protocol?
Metric | Baseline | Guard rails |
Valid on first submission | 18 / 26 (69%) | 13 / 26 (50%) |
Valid after retry (final) | 25 / 26 (96%) | 25 / 26 (96%) |
Ran out of retries | 1 / 26 (4%) | 1 / 26 (4%) |
Non-JSON replies | 5, across 4 tasks | 4 |
By mode:
mode | n | first-try (base → rails) | final ok (base → rails) |
quick | 3 | 100% → 100% | 100% → 100% |
standard | 16 | 69% → 50% | 100% → 94% |
deep | 7 | 57% → 29% | 86% → 100% |
Correctness — on the 8 tasks with an objective answer
Baseline | Guard rails | |
Protocol correct | 8 / 8 | 7 / 8 |
Direct correct | 8 / 8 | 8 / 8 |
The regression is math-widgets, and the raw log shows exactly why: the model submitted
confidence: 0.9+ backed by one piece of evidence, was rejected twice by the pre-existing
">0.9 with thin evidence" rule, and exhausted its retry budget. The failure is a retry
mechanics problem, not a guard misfiring — the rule worked as designed, the model just
repeated the same mistake instead of adding evidence or lowering confidence. The flipped
task also swapped: baseline exhausted on debug-useeffect-leak (deep), guard rails run
recovers it. n=8 is far too small to read either flip as signal.
Cost
Metric | Baseline | Guard rails |
Protocol tokens | 90,003 | 113,879 |
Protocol host calls | 37 | 41 |
Direct tokens | 19,058 | 18,120 |
Ratio | 4.72× | 6.28× |
Average latency | 50.1 s / task | 61.2 s / task |
Average scaffold | 539 tokens | 715 tokens |
What this shows — and what it does not
Shows: adding structure costs compliance. The 11-step deep scaffold with mandatory labels and the issue-tree shape cut first-try validity from 69% to 50% overall, and from 57% to 29% in deep — the model needs more retries to produce the richer shape. The retry loop still lands at 96% final validity, and deep final validity went 86% → 100%.
Shows: the new calibrator warnings fire on real output — e.g.
arch-monolith-splitwas told to restate "1%" as "10 in 1,000". They are advisory, so they cost tokens but cannot fail a submission.Does not show a correctness change. 7/8 vs 8/8 on 8 regex-scored tasks is one retry mechanics failure, not evidence either way. The honest headline is unchanged: this measurement supports structure enforcement, not accuracy improvement, and the extra structure is paid for in tokens (6.28×) and latency (61 s/task).
Known limitations
❌ Does not make the AI smarter — only stops it skipping steps
⚠️ Semantic quality needs the optional LLM layer; the structural validator alone cannot tell a genuine counter from a fake one
❌ Cannot force 100% compliance — a model that ignores protocols gets nothing from this
❌ Guard rails have a compliance price: first-try validity fell 69% → 50% (deep 57% → 29%) because the richer shape is harder to produce on the first attempt
❌ Deep mode does not suit every question (scaffold token cost)
⚠️ The eval needs a real host AI to measure compliance; the server itself produces no answer
⚠️
think_verifypasses are opinions, not a judge — the optional layer removes the fresh-context caveat (the server calls the model itself) but not the opinion one
Tests
uv venv .venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q # 216 tests, including e2e over real stdioThe LLM layer is tested two ways, both offline: scripted transports for rotation, fallback and redaction, and an end-to-end run of the real stdio server against a stub provider on localhost (real HTTP, real headers, real JSON — no key, no network):
.venv/bin/python -m pytest tests/test_llm.py tests/test_llm_e2e.py -qThe end-to-end tests spawn the real server over stdio and drive it with mcp.Client —
the same path Cursor / Claude Desktop take.
License
MIT
Available Tools
6 toolsthinkB
Open a thinking session and get the protocol scaffold for a question. It does NOT answer the question — it only builds the structure the host AI reasons through. With an LLM layer configured it also appends domain-specific probes for this problem.
Inputs: problem (required), mode, context. Returns: object
think_list_templatesA
List the thinking modes and their scaffold cost.
Inputs: no named parameters. Returns: object
think_statusC
Inspect a thinking session (for debugging).
Inputs: session_id (required). Returns: object
think_submitB
Submit the JSON response for a session. Validates the structure and returns the formatted result. If the structure is wrong, returns the error list so the host AI can fix it and submit again. With an LLM layer configured the result also carries an advisory quality audit of the substance — it can never change the status.
Inputs: response (required), session_id (required). Returns: object
think_verifyA
Verify a conclusion independently. With an LLM layer configured the server runs the adversarial refutation pass ITSELF in its own fresh context — it never saw the reasoning chain — plus optionally N self-consistency samples; set server_side=false to get only the prompts for the host to run. Without a configured layer it always returns prompts and says nothing ran.
Inputs: problem (required), conclusion (required), counter, samples, +2 more. Returns: object
think_verify_submitB
Submit the refutation reply (and any self-consistency samples) gathered from think_verify. Validates and formats the verdict. Reports verification_failed instead of pretending a pass ran when the replies are unusable.
Inputs: problem (required), conclusion (required), refutation, self_consistency. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct step in a session lifecycle (list, open, submit, status, verify, verify_submit), and descriptions clearly separate think (build scaffold) from think_verify (independent refutation). The only real overlap is think_submit vs think_verify_submit, both of which accept JSON, but their pairing with the parent tool is spelled out.
All tools use snake_case with a consistent think_ prefix and a predictable verb_noun shape (think_list_templates, think_submit, think_status, think_verify, think_verify_submit). The single bare 'think' is the primary entry action and does not break readability.
Six tools is well-scoped for a thinking-session protocol: one entry point plus list, submit, status, verify, and verify_submit. Each tool earns its place with no redundancy.
The lifecycle is largely covered: discovery, session creation, submission, inspection, independent verification, and verdict submission. Minor gaps exist, e.g. no explicit session abort/close or list-sessions operation, but agents can work around these.
Maintenance
Related MCP Connectors
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.
GodPrompt MCP + Agent Skill for coding agents with TDD, debugging, verification, and task routing.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Related MCP Servers
- AlicenseBqualityBmaintenanceLocal-first Agent OS that wraps Claude Code, Codex CLI, and other coding agents in a replayable Seed → Ledger → Runtime contract, driven by an interview → seed → execute → evaluate → evolve workflow loop.3433,002 PyPI6,381MIT
- AlicenseAqualityBmaintenanceZero-dependency token optimizer, test-failure triage gate, and System 1.5 semantic guardrail for AI coding agents. Intercepts compiler errors, missing dependencies, and doom loops in < 500µs.612MIT
- AlicenseAqualityBmaintenanceA machine-enforced workflow protocol for AI coding agents that eliminates false progress. Tasks require verifiable evidence to close, while decisions, assumptions, and open questions persist in a versioned reasoning graph for seamless agent handoffs. Designed to keep deep, long-running projects coherent across sessions, agents, and months.3932AGPL 3.0
- FlicenseNot gradedqualityBmaintenanceEnables MCP-compliant agents to run deterministic iterative self-critique and reflection loops that autonomously evaluate and revise outputs to repair logic defects, test failures, and hallucinations. It connects via JSON-RPC stdio with no external dependencies, supporting fast local execution and agent integration.7-