House of Wisdom MCP

What this is — an MCP (Model Context Protocol) server that asks the same question to several different AI model families at once and hands you back every answer, unmerged.

How to read it — What it is → Quick start → The three modes → The two tools → How a call flows → Installation → Configuration. Go to Sharp edges when something surprises you.

Requires — Python 3.10+, uv/uvx, and at least two enabled models.

Reflects code as of — 2026-07-20, commit 7ac2449, package version 0.6.1.

The medieval Bayt al-Hikma worked because it was diverse: scholars, translators, and copyists from many traditions read the same questions through different lenses, and the reader weighed the results. This server does the same with models — OpenAI, Anthropic and Google via OpenRouter, DeepSeek, local Ollama, or any OpenAI-compatible endpoint.

What it is, and what it is not

There is no synthesizer. The caller — your IDE agent — reads every perspective and decides. Treating any single perspective as ground truth defeats the design.

Do not fire the council on every prompt. It costs several model calls and tens of seconds. Use it only when a different model family seeing the problem would plausibly change the outcome. For work that just needs your own focused reasoning, use a single-mind thinking tool instead.

Quick start

# 1. Get a config file
curl -O https://raw.githubusercontent.com/EzzoHamdan/house-of-wisdom-mcp/master/config.example.yaml

# 2. Edit it — the only field you MUST set is `models`, and at least 2 must be enabled.

# 3. Register the server with your MCP client (see Installation for per-client syntax):
#    command: uvx
#    args:    --from git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master
#             ai-council --config /absolute/path/to/config.yaml

# 4. Restart the client, then ask your agent to call `list_models`.

If list_models returns your roster, the server is loaded. Then try one consult call in scribe mode — it is the fast path and needs no filesystem access.

The three modes

One argument, mode, decides how much freedom each consultant gets. It is the only knob that changes behavior at call time.

With default budgets, wall-clock ordering runs scribe < translator < scholar; absolute numbers depend entirely on which models you configured and whether they are local or remote. Nothing enforces that ordering, though — raising max_tool_iterations above scholar_max_tool_iterations inverts it.

How the effective mode is resolved

Precedence, highest first (synthesis.py::collect_perspectives):

agentic is a deprecated boolean kept so older callers keep working; mode wins whenever both are passed. scholar can only be reached by asking for it explicitly.

⚠ synthesizer_tools.enabled only picks the default in row 4. It is not a gate: an explicit mode: "translator" or mode: "scholar" runs the tool loop even when enabled: false.

The two tools

Renamed in v0.5.0. ai_council → consult and ai_council_list_models → list_models. The old names still work — they are accepted as backward-compatible aliases, so clients or scripts registered before the rename keep functioning. Only the new names are advertised, so your agent will discover and use consult / list_models going forward.

list_models

Takes no arguments. Returns the configured roster straight from loaded config.

{
  "status": "success",
  "data": {
    "models": [
      {"name": "GLM", "model_id": "glm-5.2:cloud", "provider": "custom", "enabled": true},
      {"name": "Kimi", "model_id": "kimi-k2.7-code:cloud", "provider": "custom", "enabled": true}
    ],
    "max_models": 3,
    "enabled_count": 2
  }
}

It does not contact any endpoint and does not validate API keys. enabled: true means "present in config and not switched off", nothing more. Note that models lists every configured entry; when a consult call names no subset, only the first max_models enabled ones fire, but any enabled model can be requested by name — see Who actually fires.

consult

Success shape. One entry per model that was dispatched, in roster order:

{
  "status": "success",
  "data": {
    "perspectives": [
      {"label": "GLM",  "model_name": "GLM",  "code_name": "Alpha", "analysis": "...", "status": "ok",    "mode": "translator"},
      {"label": "Kimi", "model_name": "Kimi", "code_name": "Beta",  "analysis": "...", "status": "error", "mode": "translator"}
    ],
    "consensus": {"models_queried": 2, "models_succeeded": 1, "models_failed": 1}
  }
}

• Failed consultants are returned in-band with status: "error" and the error text sitting in analysis. The call as a whole still reports "status": "success" as long as at least one consultant succeeded.

• label is model_name normally, or code_name when anonymous_perspectives: true.

• consensus counts nothing about agreement — despite the name, it is a dispatch tally, and models_failed is simply the number of status: "error" entries.

Error shape.

{"status": "error", "error": {"code": "...", "message": "...", "type": "...", "details": "..."}, "data": null}

data is null on every error except ALL_MODELS_FAILED, which carries {"attempted_models": N, "failed_responses": N}. Note that no individual analyses survive that path — if you need partial results from a slow batch, raise parallel_timeout rather than retrying.

How a call flows

MCP client (the orchestrator)
  │ consult(context, question, mode?, workspace_root?, scope_hint?, models?)
  ▼
main.py::_process_ai_council
  ├─ validate      context 1..200,000 chars · question 1..10,000 chars   → INVALID_INPUT
  └─ roster        `models` passed?  yes → keep FULL enabled list entries whose name matches
                                          nothing left?  → NO_MATCHING_MODELS
                                     no  → default window = enabled[:max_models]
  ▼
synthesis.py::collect_perspectives
  ├─ mode          mode arg > agentic bool > synthesizer_tools.enabled
  ├─ sandbox       workspace_root arg > config workspace_root > process cwd
  └─ budget        scholar → scholar_max_tool_iterations · else max_tool_iterations
  │
  ├── scribe ───────────► models.py::call_models_parallel
  │                        one chat call per model · temp 0.7 · max_tokens 8000
  │                        ⚠ NO concurrency cap — every model fires at once
  │
  └── translator ───────► models.py::call_models_parallel_agentic
      scholar              semaphore = max_concurrent_consultants
                           per consultant, repeat until it answers or budget runs out:
                             chat(tools=[read_file,list_dir,glob_search,think])
                               ├─ tool_calls? → dispatch in sandbox → append results → loop
                               └─ plain text? → that is the analysis
                           budget exhausted → one forced "answer from what you have" turn
                           temp 0.4 · max_tokens 16000
  ▼
perspectives[]   one per dispatched model, roster order, failures included
  ▼
MCP client weighs them.  No synthesizer runs, in any mode.

How a call flows (rendered)

%%{init: {'themeVariables': {'lineColor': '#8b949e'}}}%%
flowchart TD
    C([MCP client]) -->|consult| V{{"validate<br/>context ≤200k · question ≤10k"}}
    V -->|invalid| E1["INVALID_INPUT"]
    V --> S{{"models arg passed?"}}
    S -->|"yes: match against ALL enabled"| R1["roster = named enabled models"]
    S -->|"no: default window"| R2["roster = first max_models enabled"]
    R1 -->|none match| E2["NO_MATCHING_MODELS"]
    R1 --> M{{"resolve mode"}}
    R2 --> M
    M -->|scribe| P["call_models_parallel<br/>no tools · no semaphore"]
    M -->|translator| A["call_models_parallel_agentic<br/>budget = max_tool_iterations"]
    M -->|scholar| A2["call_models_parallel_agentic<br/>budget = scholar_max_tool_iterations"]
    A --> L
    A2 --> L
    L{{"tool loop, per consultant<br/>capped by max_concurrent_consultants"}}
    L -->|tool_calls| T[("sandbox: read_file · list_dir<br/>glob_search · think")]
    T --> L
    L -->|plain text| O["one perspective per model<br/>errors included in-band"]
    P --> O
    O --> C

    classDef gate stroke-dasharray:4 3;
    class V,S,M,L gate;

Installation

Prerequisites

Step 1 — write a config file

Start from config.example.yaml, which is fully commented:

curl -O https://raw.githubusercontent.com/EzzoHamdan/house-of-wisdom-mcp/master/config.example.yaml
mkdir -p ~/.config/ai-council && mv config.example.yaml ~/.config/ai-council/config.yaml

~/.config/ai-council/config.yaml is the path the server checks when --config is omitted. Any other location works if you pass --config /absolute/path.yaml.

⚠ If the path you pass to --config does not exist, it is ignored without an error. The server then boots on built-in defaults, whose roster is three OpenRouter models — so the symptom of a typo'd path is usually OpenRouter API key is required, not "file not found".

Step 2 — register the server with your MCP client

The launch command is identical everywhere; only the surrounding JSON/TOML differs.

command:  uvx
args:     --from  git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master
          ai-council
          --config  /absolute/path/to/config.yaml

The server key is the display name. The key you give the entry under mcpServers (House-of-Wisdom below) is what your IDE shows as the tool prefix, e.g. House-of-Wisdom [consult]. Rename it to whatever you like — it is purely cosmetic and lives in your client config, not in this repo. The ai-council token inside args is a different thing (the installed console-script name) and must stay as-is.

Claude Desktop — Settings → Developer → Edit Config, which opens ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "House-of-Wisdom": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master",
               "ai-council", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

Cursor — same JSON, in .cursor/mcp.json (project) or via Settings → MCP (global).

Kilo Code — same JSON, in the file opened by the MCP Servers panel (Edit Global MCP → mcp_settings.json, or Edit Project MCP → .kilocode/mcp.json). Kilo kills a server that is slow to answer, so raise its per-server timeout if you use scholar mode:

{
  "mcpServers": {
    "House-of-Wisdom": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master",
               "ai-council", "--config", "/absolute/path/to/config.yaml"],
      "timeout": 240
    }
  }
}

Claude Code (CLI) — the -- separator matters, otherwise claude parses --from as its own flag:

claude mcp add House-of-Wisdom -- uvx --from git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master \
  ai-council --config /absolute/path/to/config.yaml

Codex CLI — ~/.codex/config.toml:

[mcp_servers."House-of-Wisdom"]
command = "uvx"
args = ["--from", "git+https://github.com/EzzoHamdan/house-of-wisdom-mcp@master",
        "ai-council", "--config", "/absolute/path/to/config.yaml"]

Anything else — any client that speaks stdio MCP can run this server. Only the registration syntax changes.

Step 3 — restart the client

Config is read once at process start. Every config edit or server upgrade needs a client restart.

Step 4 — verify

1. Call list_models → your roster comes back.

2. Call consult with mode: "scribe", a short context, and a short question → each model answers. This isolates model connectivity from filesystem/sandbox concerns.

3. Only then try translator with an explicit workspace_root.

Configuration reference

Every key, with both defaults

"Built-in" is what you get when the key is absent from your YAML. "Example file" is what config.example.yaml ships with — these differ, so do not read the example file as documentation of defaults.

A minimal working config is just:

models:
  - name: "GLM"
    provider: "custom"
    model_id: "glm-5.2:cloud"
    base_url: "http://localhost:11434/v1"
    api_key: "ollama"
    enabled: true
  - name: "Kimi"
    provider: "custom"
    model_id: "kimi-k2.7-code:cloud"
    base_url: "http://localhost:11434/v1"
    api_key: "ollama"
    enabled: true

Startup validation — what stops the server from booting

These are checked at load time. Each exits with Configuration error: … on stderr — which your MCP client usually surfaces as "server failed to start" — wrapped in a Pydantic ValidationError, so the strings below appear as a fragment of a longer message rather than on their own.

The base_url requirement is checked independently of api_key (v0.5.1). Previously validation short-circuited on the presence of api_key, so a custom entry with a key but no base_url was never checked and the client fell back to OpenAI's default endpoint — silently sending prompts to api.openai.com. A base_url-less custom entry is now rejected at startup (and guarded again at client construction).

Model entry fields

Consultant recipes

Local Ollama — free, api_key can be any non-empty string:

models:
  - name: "GLM"
    provider: "custom"
    model_id: "glm-5.2:cloud"          # a tag from `ollama list`
    base_url: "http://localhost:11434/v1"
    api_key: "ollama"
    enabled: true

OpenAI — one shared key at the top of the file:

openai_api_key: "sk-..."
models:
  - name: "GPT-5.6-Terra"
    provider: "openai"
    model_id: "gpt-5.6-terra"
    enabled: true

Claude / Gemini / most others via OpenRouter — one key, many families. model_id is the slug from openrouter.ai/models:

openrouter_api_key: "sk-or-..."
models:
  - name: "Claude Opus"
    provider: "openrouter"
    model_id: "anthropic/claude-opus-4"
    enabled: true
  - name: "Gemini Pro"
    provider: "openrouter"
    model_id: "google/gemini-2.5-pro"
    enabled: true

DeepSeek direct, Perplexity, Groq, Together, vLLM, LM Studio — anything OpenAI-compatible uses provider: custom with its own base_url and api_key. Use a ${ENV_VAR} placeholder to keep the secret out of the file (see Keeping keys out of the YAML):

models:
  - name: "DeepSeek-Pro"
    provider: "custom"
    model_id: "deepseek-chat"
    base_url: "https://api.deepseek.com/v1"
    api_key: "${DEEPSEEK_API_KEY}"   # resolved from the environment at load time
    enabled: true

API keys — where they are read from

Per model, first match wins:

1. api_key on the model entry — always wins for that entry, whatever the provider.

2. The provider-level key (openai_api_key for provider: openai, openrouter_api_key for provider: openrouter), which is itself resolved as CLI flag → YAML top-level field → environment variable.

provider: custom entries never fall back to a provider-level key; they require their own api_key.

The environment variable names are AI_COUNCIL_OPENAI_API_KEY and AI_COUNCIL_OPENROUTER_API_KEY (v0.5.1 — the fields no longer declare a Pydantic alias, so the AI_COUNCIL_ prefix applies to them like every other setting). A bare, unprefixed OPENAI_API_KEY / OPENROUTER_API_KEY in the environment your MCP client launches is not picked up — set the prefixed name, or pass the key via YAML or the CLI flags.

All settings use the prefix and match case-insensitively: AI_COUNCIL_OPENAI_API_KEY, AI_COUNCIL_OPENROUTER_API_KEY, AI_COUNCIL_MAX_MODELS, AI_COUNCIL_PARALLEL_TIMEOUT, AI_COUNCIL_LOG_LEVEL, AI_COUNCIL_MAX_CONCURRENT_CONSULTANTS, AI_COUNCIL_ANONYMOUS_PERSPECTIVES.

Keeping keys out of the YAML

The config file describes structure (which models, timeouts, modes); secrets belong in the environment. Keeping config.yaml secret-free means you can hand it to an AI agent to edit, or even commit it, without leaking a key. Three ways to supply keys without touching the file:

1. Environment variables — set the AI_COUNCIL_-prefixed names. For MCP the cleanest place is your client's env block, so the server inherits them at launch:

   "env": {
     "AI_COUNCIL_OPENAI_API_KEY": "sk-...",
     "AI_COUNCIL_OPENROUTER_API_KEY": "sk-or-..."
   }

2. A .env file — the server reads one next to the config file and one in the working directory, before it parses any keys. Copy the committed .env.example to .env (it's gitignored) and fill it in; use the same AI_COUNCIL_-prefixed names:

   AI_COUNCIL_OPENAI_API_KEY=sk-...
   AI_COUNCIL_OPENROUTER_API_KEY=sk-or-...

   A real environment variable (e.g. from the client env block) always wins over the .env file.

3. ${ENV_VAR} placeholders — any api_key or base_url value may reference an env var, which is expanded at load time. This is the only secret-free path for a per-model api_key on a provider: custom entry (DeepSeek, Groq, …), since those never fall back to a provider-level key:

   api_key: "${DEEPSEEK_API_KEY}"

   A referenced-but-unset variable fails loudly at startup, naming the missing var — it is never silently sent as an empty key.

config.yaml, *.local.yaml, and .env are gitignored, so a filled-in config can't be committed by accident.

Who actually fires

The per-call roster is built one of two ways, then bounded by concurrency:

configured models        ── enabled: true ──►  enabled models
                              │
        no `models` arg ◄─────┴─────► `models` arg passed
              │                              │
      [:max_models]                  match names against ALL enabled models
              │                              │
      default window                 this call's roster (any enabled model, any position)
              └──────────────┬───────────────┘
                             ▼
this call's roster       ── semaphore ──►  N running at once (translator/scholar only)

• max_models (1–10) caps the default fan-out — the roster used when a call names no subset. The window is the first max_models enabled entries by position in the YAML list, not by preference.

• The per-call models argument resolves against the full enabled list, so any enabled model is reachable by name regardless of max_models or its position. With eight enabled models and max_models: 3, asking for the seventh by name fires exactly that model. A named subset is not re-capped to max_models — the caller chose the models, and max_concurrent_consultants still bounds how many run at once.

• max_concurrent_consultants (1–32) caps how many tool loops run simultaneously; the rest queue. Match it to your provider's concurrency allowance (Ollama Cloud Pro = 3, Max = 10). ⚠ It is not applied in scribe mode — there, every model in the roster fires at once.

The consultant sandbox

In translator and scholar modes each consultant gets its own read-only tool loop, rooted at workspace_root. These tools are internal to the consultant; they are never exposed to your MCP client.

Restrict the set with synthesizer_tools.allowed_tools; a call to a tool outside the list returns an error string to the model rather than executing. ⚠ Distinguish the two "empty" cases: omitting the key (null) permits all four, while allowed_tools: [] permits none — an empty allowlist advertises no tools, so every consultant loses read access. To narrow the surface, name the tools you want, e.g. ["read_file", "think"]; to grant everything, leave the key out.

What never happens

• No writes, no shell, no network from the tools. The four above are the entire surface (tools.py::ToolRegistry.call).

• No read outside workspace_root. Paths are resolved with Path.resolve() and checked with relative_to(), so symlinks pointing out of the root are rejected as SandboxViolation (tools.py::ToolRegistry._resolve).

• No tool call at all in scribe mode.

• No endpoint contact from list_models.

• No merging of perspectives, in any mode.

Budget accounting

The loop stops when the model replies with plain text instead of tool calls, or when the budget is spent — after which it gets one forced turn to answer from what it gathered, and a second nudge if that comes back empty.

⚠ The budget counts rounds, not individual tool calls: one unit per assistant turn that contains tool calls, however many it contains. A model that requests four files in a single turn spends one unit, not four — and a think batched alongside them is free. The system prompt tells the model that each call costs one unit, so most models behave as if the stricter accounting were real, but a batching model can legitimately read far more of your workspace than the budget number suggests.

Operational envelope

Values are hardcoded in models.py; listed here because they are not otherwise visible from the outside.

Empty responses get one automatic retry. Models that return their answer in a reasoning, thinking, or reasoning_content field instead of content — common with Ollama's cloud thinking models — are handled by models.py::_extract_text.

Per-provider request adaptation (v0.5.2, models.py::_create_completion): for provider: openai the output cap is sent as max_completion_tokens instead of max_tokens (newer OpenAI models reject the latter). If a model still rejects a parameter — e.g. reasoning models accept only the default temperature: 1 — that parameter is dropped and the call retried (up to three strips). custom / openrouter endpoints are sent the classic max_tokens / temperature unchanged.

⚠ Because parallel_timeout also bounds the whole batch, and because queued consultants spend their wait inside that window, a scholar run with more models than max_concurrent_consultants needs a generous value. When the batch timeout fires, only the consultants still running are cancelled and marked as timed out; perspectives that already finished are kept (v0.5.1), so a slow straggler no longer collapses a partial success into ALL_MODELS_FAILED.

Sharp edges

Known divergences between what the system looks like it does and what it does. Each is verified in code.

Fixed in v0.6.1. The per-call models argument now resolves against the full enabled list, so an explicitly named enabled model is reachable regardless of max_models or its position in the YAML. max_models again caps only the default (no-subset) fan-out, and the NO_MATCHING_MODELS detail reports the true full enabled set. config.py::get_enabled_models, main.py::_process_ai_council.

Fixed in v0.5.1. Nine long-standing sharp edges were resolved: the AI_COUNCIL_ env prefix now works (and a bare OPENAI_API_KEY is no longer silently adopted); a batch timeout keeps consultants that already finished; status is carried explicitly instead of guessed from the text; a custom model without base_url is rejected instead of talking to api.openai.com; allowed_tools: [] now permits nothing; code_name auto-assignment no longer skips names or crashes at 10 models; the advertised version tracks the package; synthesis_model_selection (dead) was removed; and the consult description no longer quotes example-config defaults.

CLI arguments

Logs go to stderr, which is where MCP clients collect server output. --log-level DEBUG prints every tool call each consultant makes.

Code map

Run the tests with uv run pytest (or pytest -q inside an activated venv). They cover config parsing and sandbox path resolution; there is no test that exercises a live model call.

Acknowledgments

Inspired by Cognition Wheel, which established the wisdom-of-crowds approach to multi-model consultation. This project diverges from it in dropping the synthesis step entirely, adding the three named modes, giving every consultant its own read-only investigation loop, and pushing the weighing of perspectives back onto the caller. The medieval House of Wisdom supplied the name and the principle: many lenses, weighed by the reader, not merged by an authority.

License

MIT — see LICENSE.