Skip to main content
Glama

council-mcp

A Model Context Protocol server that runs multi-model deliberation: several LLMs answer the same question in parallel, then a judge model synthesizes their perspectives into one answer.

It is built for the cases where a single model is not enough — architecture decisions, debugging strategy, high-risk operational changes, or any question where hallucination risk matters. It also treats "the model returned HTTP 200" as a claim to verify, not proof that the model actually said anything useful.

  • Parallel advocates — 2–4 models queried concurrently with a hard per-call wall-clock cap.

  • Judge synthesis — a separate model produces consensus, dissent, a final verdict, and a confidence level from the substantive advocate responses.

  • Degraded-response detection — catches empty bodies, <think> / <thinking> reasoning wrappers, DeepSeek's end-of-thinking marker, and untagged chain-of-thought leaks that used to sail through as valid answers.

  • Bounded retry and backfill — degraded or failed advocates get one retry; unused providers backfill remaining slots, all inside a wall-clock budget so a deliberation cannot run past the caller's deadline.

  • Cost and latency telemetry — every response reports provider, model, latency, estimated cost, finish reason, and degradation status.

How it works

question
   │
   ├──► advocate A ──┐
   ├──► advocate B ──┤  parallel, hard-capped
   ├──► advocate C ──┤
   └──► advocate D ──┘
                     │
             strip reasoning wrappers
             classify degraded output
                     │
          ┌──────────┴──────────┐
          │ retry degraded once │
          │ backfill from pool  │  wall-clock budget
          └──────────┬──────────┘
                     │
              substantive responses only
                     │
                 judge model
                     │
              synthesis + metadata

If no advocate produces substantive content after retry/backfill, the server fails closed: it returns All advocates failed: no substantive responses. instead of feeding raw scratchpad text to the judge.

Related MCP server: Peer Review MCP Server

Install

Requires Python 3.11+.

git clone https://github.com/rudysanchez-mfb/council-mcp.git
cd council-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

That installs the council-mcp console script. You can also run the module directly:

python -m council_mcp.server

Both speak MCP over stdio and print only JSON-RPC to stdout; diagnostics go to stderr.

Configuration

Set API keys in the environment of your MCP host (not in this repository). Only providers with a key present are usable; a missing key is reported as a per-provider error and the rest of the council continues.

Provider

Environment variable

Default model

Endpoint

Moonshot / Kimi

KIMI_API_KEY

kimi-k3.1-pro

https://api.moonshot.ai/v1/chat/completions

DeepSeek

DEEPSEEK_API_KEY

deepseek-v4-pro (judge: deepseek-chat)

https://api.deepseek.com/v1/chat/completions

xAI

XAI_API_KEY

grok-4.20-reasoning

https://api.x.ai/v1/chat/completions

Google Gemini

GEMINI_API_KEY

gemini-2.5-flash

Google OpenAI-compatible endpoint

Default lineup: Kimi, DeepSeek, Grok, Gemini (the first num_advocates are used). DeepSeek is the default judge. See .env.example.

The provider registry lives in council_mcp/providers.py, so adding a model or an OpenAI-compatible endpoint is a small local change.

MCP host configuration

Replace values as needed. Use an absolute path to the installed console script if your host does not inherit your shell PATH (which council-mcp).

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "council": {
      "command": "council-mcp",
      "env": {
        "KIMI_API_KEY": "…",
        "DEEPSEEK_API_KEY": "…",
        "XAI_API_KEY": "…",
        "GEMINI_API_KEY": "…"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "council": {
      "command": "council-mcp",
      "env": {
        "KIMI_API_KEY": "…",
        "DEEPSEEK_API_KEY": "…",
        "XAI_API_KEY": "…",
        "GEMINI_API_KEY": "…"
      }
    }
  }
}

OpenCode

opencode.json:

{
  "mcp": {
    "council": {
      "type": "local",
      "command": ["council-mcp"],
      "environment": {
        "KIMI_API_KEY": "…",
        "DEEPSEEK_API_KEY": "…",
        "XAI_API_KEY": "…",
        "GEMINI_API_KEY": "…"
      },
      "enabled": true
    }
  }
}

Hermes Agent

~/.hermes/config.yaml:

mcp_servers:
  council-mcp:
    command: council-mcp
    args: []
    env:
      KIMI_API_KEY: "…"
      DEEPSEEK_API_KEY: "…"
      XAI_API_KEY: "…"
      GEMINI_API_KEY: "…"

If your host does not support env in the server block, export the keys in the environment that launches the host instead.

Tools

council_deliberate

Runs a deliberation and returns JSON.

Argument

Type

Default

Meaning

question

string

required

The question for the council.

num_advocates

integer (2–4)

3

How many advocate models to query.

include_raw

boolean

true

Include each advocate's raw content in the result.

Result fields include:

  • synthesis — the judge's answer.

  • advocates — per-model content, latency, cost, degraded, degraded_reason.

  • errors — providers that failed after retry/backfill.

  • advocates_count, advocates_failed, degraded_count, contributors_count.

  • retried, backfill_count, cost_total, latency_ms, synthesis_truncated.

Coverage, not capacity: advocates_count includes degraded responses. The real breadth of a deliberation is advocates_count - degraded_count (also exposed as contributors_count). Callers should read the latter before claiming "N models agreed."

council_list_models

Lists the provider/model pairs currently registered.

Degraded response detection

classify_degraded() runs after reasoning wrappers are stripped and returns (degraded, reason). A response is degraded when:

  1. Empty body — nothing substantive after stripping wrappers.

  2. Long reasoning preamble — ≥600 chars before the first required heading plus a chain-of-thought cue, or ≥2000 chars before it regardless.

  3. Re-drafted answer — a required heading appears more than once alongside a chain-of-thought cue.

  4. Missing structure — a ≥1500-char response missing at least two of the VERDICT / REASONING / RISKS headings, with at least one CoT cue.

Detection is deliberately structural first: the advocate prompt requires the three headings, so their absence is the primary signal. A small phrase list only corroborates; it never triggers a flag on its own. Short markerless answers and long but clean structured answers are never flagged.

Degraded responses are retried once and then replaced from the unused-provider pool when possible. Anything still degraded is excluded from the judge input and reported in the result.

Latency budget

The default budgets are tuned for hosts that cap a tool call at 300 seconds:

Constant

Value

Purpose

CALL_TIMEOUT

110 s

Per-request read timeout.

HARD_CAP_S

120 s

Hard wall-clock cap on the parallel advocate phase.

JUDGE_HARD_CAP_S

90 s

Hard cap on the judge call.

RETRY_BUDGET_S

40 s

Total budget for sequential retry/backfill.

ADVOCATE_MAX_TOKENS

4000

Output cap; also a latency cap for reasoners.

JUDGE_MAX_TOKENS

4096

Judge output cap.

Worst case is approximately HARD_CAP_S + RETRY_BUDGET_S + JUDGE_HARD_CAP_S (≈250 s). If your host allows longer calls, tune the constants in council_mcp/council.py.

Tests

The test suite makes no network calls and needs no API keys; provider calls are mocked.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest

Coverage includes strip_think_tags, the reasoning_content fallback, every classify_degraded branch, retry/backfill accounting, the retry budget guard, fail-closed behavior, and server argument forwarding.

License

Apache License 2.0. See LICENSE and NOTICE.

Copyright 2026 Rudy Sanchez.

Available Tools

2 tools
council_deliberateA

Run multi-model deliberation: several models answer a question in parallel, then a judge synthesizes the best answer. Use for high-stakes decisions, architecture questions, debugging strategy, or any question where hallucination risk matters.

Inputs: question (required), include_raw, num_advocates. Returns: result

council_list_modelsA

List the provider/model pairs available for deliberation.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve clearly distinct purposes: one executes a deliberation, the other enumerates available models. There is no plausible way to confuse listing models with running a deliberation.

    Naming Consistency5/5

    Both names use the same 'council_' prefix followed by a clear verb_noun pattern (council_deliberate, council_list_models). The convention is predictable and readable.

    Tool Count3/5

    Two tools is thin for a server, though the domain (multi-model deliberation with a judge) is narrow enough that a discovery tool plus a single execution tool may genuinely be all that's needed. It sits at the borderline of minimal but defensible.

    Completeness3/5

    The surface covers the core operation and model discovery, but there is no way to inspect or retrieve prior deliberations, configure the judge/models per call, or check status of a long-running deliberation. These are notable gaps an agent could hit, though the primary workflow is usable.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Code to send a prompt to multiple LLMs simultaneously and get a judge model's structured comparison of their responses. This surfaces consensus, contradictions, and blind spots, letting Claude write a more informed final answer.
      1
      MIT