tokonomix-council-mcp

# tokonomix-council-mcp

[![npm version](https://img.shields.io/npm/v/tokonomix-council-mcp.svg)](https://www.npmjs.com/package/tokonomix-council-mcp)
[![license](https://img.shields.io/npm/l/tokonomix-council-mcp.svg)](./LICENSE)
[![node](https://img.shields.io/node/v/tokonomix-council-mcp.svg)](https://nodejs.org)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-.well--known%2Fmcp-blue)](https://tokonomix.ai/.well-known/mcp/server.json)

**A multi-model consensus MCP server** — cross-vendor proposers, an independent judge, and blind-spot/disagreement detection for high-stakes AI decisions. An open reference implementation of AI Decision Engineering — a discipline we are proposing, not yet an external standard.

> **Mission.** *Help autonomous systems make better decisions by combining independent expert reasoning instead of trusting a single model.*

> **In 20 seconds:** *Important AI decisions deserve more than one opinion.*

### The Tokonomix ecosystem (where Council fits)

Council is one specialized component in a larger stack. Each owns exactly one responsibility, so they compose cleanly:

```
   Execution    →  ANS         (run a backlog to completion, unattended)
   Decision     →  Council     (independent review → grounded decision)   ◀── this repo
   Verification →  Media QC    (image / video / document output quality)
   Measurement  →  Benchmark   (intelligence tests, arena, reputation)
   Routing      →  Router      (which provider/model hosts a call)
   Memory       →  Memory      (durable context across sessions)
   Safety       →  Safety      (policy / guardrail enforcement)
```

**Council owns one box: the decision.** It does not execute, schedule, route, or remember — those live in their own components ([details below](#council-in-the-tokonomix-ecosystem)).

---

### Status — what is live right now

So you never call something that isn't there yet. Server-gated features can be off for your account/tier; when they are, the tool returns a clear "not enabled" message instead of erroring.

| Capability | Status |
|---|---|
| `tokonomix_consensus_ask` — modes `consensus` / `diff` / `best_of` / `raw` / `full` | **Live** |
| `tokonomix_single_ask` — single-model passthrough | **Live** |
| `tokonomix_list_models`, `tokonomix_get_balance` | **Live** |
| `tokonomix_skill_version`, `tokonomix_get_skill` | **Live** |
| `tokonomix_onboard`, `tokonomix_onboard_verify` — keyless first-run | **Live** |
| `tokonomix_rate_consensus` — agent rating / feedback-loop | **Live** (platform-gated) |
| `tokonomix_relay_human_feedback` — human verdict channel | **Live** (platform-gated) |
| Vision input (`images` on ask) | **Live** |
| `tokonomix_upload` + `context.session/handles` — large shared context-pack | **Account-gated** (on for eligible accounts) |
| `context.inline` / `context.github_refs` grounding | **Live** (account-gated) |
| Grounding-gate (`needs_context` refusal of thin input) | **Gated** (shadow-first rollout) |
| Reranking, web-search plugin | **Planned** |

---

Council MCP exists to improve **decision quality**, not to chat, generate, or route. The governing idea is simple:

> ### Consensus × Ground Truth = Decision Quality

Consensus is **one** mechanism for decision quality — not the whole of it. **Grounding** (checking a claim against the real artifact) is the strongest lever, stronger than adding more models; **judge-independence** and **verification** are mechanisms too. Several independent expert models assess the same problem in parallel and blind, an **independent, cross-family judge** reconciles their findings, and grounding ties the whole thing to reality — so you get one decision you can act on, with the disagreements a single model would have hidden surfaced rather than smoothed away. **Consensus is a *means*; better decisions are the goal.**

It is **not** a chatbot, a model, an LLM, a prompt library, a multi-model chat, a voting system, or an averaging system. It does not make any model smarter, and it does not pick a winner by majority — it changes how multiple independent models' outputs become *one defensible decision*.

> **What it honestly buys you — and what it does not.** Across our own validation (see [Benchmarks](#benchmarks)), the council **ties the best single model on clean accuracy and beats it nowhere**, and on a SWE-bench bug-detection run it showed **no measurable net uplift in catch rate** over re-running a single agent. So we do **not** claim "more accurate" or "catches more bugs" anywhere. What it does buy is **variance-elimination** (you stop gambling on which single model you happened to ask), a **verification / agent-QA layer**, **judge-independence**, **EU data residency**, and **grounding**. Read [When consensus helps / doesn't / can hurt](#when-consensus-helps--doesnt--can-hurt) before you rely on it — that section is the point, not a disclaimer.

Works with **Claude Code, Cursor, Cline, Continue, and Zed**. One `npx` line to install.

> ### Principles of Decision Engineering
>
> The discipline Council implements rests on ten principles. An autonomous system should:
>
> 1. **Verify before acting** — a decision is provisional until it has been checked.
> 2. **Preserve disagreement** — the lone dissent is often the finding that mattered; never average it away.
> 3. **Separate execution from judgement** — the thing that *does* the work should not also be the thing that *grades* it.
> 4. **Separate reasoning from verification** — generating an answer and checking it are different jobs.
> 5. **Separate confidence from correctness** — a model's tone is identical whether it is right or wrong.
> 6. **Prefer evidence over agreement** — agreement measures agreement, not truth; ground the claim.
> 7. **Expose uncertainty** — surface what was *not* settled, don't hide it behind one confident answer.
> 8. **Make decisions auditable** — record who proposed, who judged, what it cost, on what input.
> 9. **Remain reproducible** — the same input and method should be re-runnable to the same finding.
> 10. **Never hide failure modes** — a decision tool that conceals when it fails is not a decision tool.

---

## What Council owns — and what it explicitly does not

Council is a **Decision Engineering layer**. Its scope is deliberately narrow, because a clear boundary is what makes a component trustworthy to compose with.

**Council owns DECISIONS ONLY:**

- decision quality and decision confidence,
- independent review and reasoned consensus,
- verification of reasoning and claims,
- grounding (checking a claim against the real artifact),
- disagreement analysis,
- judge independence,
- auditability of how a decision was reached.

**Council is explicitly NOT responsible for:** execution, workflow, task scheduling, agent autonomy, long-term memory, provider routing, or browser automation. Those are real responsibilities — they simply live in **other** components.

- Need something **executed** (a backlog run to completion, unattended)? That is **[Agents Never Sleep (ANS)](https://github.com/TokonoMix/agents-never-sleep)**, the execution governor. ANS is the worker/governor; Council is the verifier it can delegate a decision to. Council does not run, schedule, or remember work.

See [Council in the Tokonomix ecosystem](#council-in-the-tokonomix-ecosystem) for where every adjacent responsibility lives.

---

## Why Council exists (the short story — for a human OR an AI agent)

**Why does Council exist?** Because important AI decisions are made by single models that answer with total confidence and never tell you what they didn't consider. For chat that is fine; for a security review, a migration, a GDPR interpretation, or a legal clause, a confidently-wrong decision is expensive and you find out too late.

**Why is one model not enough?** A single model is one opinion with one blind spot. *Which* model is strongest is not stable — it shifts per task, per domain, per bug class. Standardise on the wrong one and you ship real defects without ever seeing a disagreement.

**When does combining models help?** When errors are *uncorrelated*: different vendors are wrong about different things, so you only need one of them to catch the timing side-channel or the missed edge case for it to surface. That decorrelation only exists **across** vendors — a single vendor's "panel" shares its own training data and blind spots.

**When does it NOT help?** On routine work (renames, formatting, lookups) and on easy tasks any strong single model already saturates. There the council only adds cost and noise — use a single model.

**Why does grounding matter more than more models?** Because agreement measures agreement, not truth. Ungrounded, frontier models can agree *and be uniformly wrong* (they share training data). Feeding the council the real artifact — the literal file, diff, spec, logs — is the lever that turns "they agreed" into "they checked it against reality." More models cannot fix a shared blind spot; grounding can.

**Why does judge independence matter?** Because a judge that also wrote one of the answers scores its own work and *inflates* agreement (LLM self-preference is real and measured). A disjoint, cross-family judge is the only honest reconciler.

**Why do failure modes matter?** Because consensus *can* be worse than a single model — lossy synthesis, correlated failures, false consensus, specialist overlap. A decision tool that hides its failure modes is not a decision tool. **Honesty about when consensus does NOT work is the competitive advantage**, not a caveat we bury.

---

## Contents

1. [Why Decision Engineering is becoming necessary](#why-decision-engineering-is-becoming-necessary)
2. [Why LLMs cannot solve this themselves](#why-llms-cannot-solve-this-themselves)
3. [Design principles](#design-principles)
4. [A story: the security review](#a-story-the-security-review)
5. [The problem](#the-problem)
6. [Why single-model review falls short](#why-single-model-review