The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Model Council listing page.
English | 简体中文
An MCP server that seats other LLMs at your table. Your assistant asks them, reads their answers as tool results, relays those answers back and forth for critique, and gives you one merged conclusion — inside a single normal conversation, with no copy-paste.
Your assistant chairs the council. Any number of members, from any mix of OpenAI-compatible and Anthropic-compatible endpoints — a hosted API, a self-run gateway, a local server, or several of each.
| Tool | What it does |
|---|---|
ask(model, prompt, materials?) | Ask one member by id |
ask_all(prompt, models?, rounds?, guests?, materials?, steelman?) | Ask everyone (or a named subset) the same prompt in parallel, answers side by side. rounds=2 turns it into a discussion; steelman seats a standing objection that argues back every round; guests seats answers you already have; materials hands them a file to read |
revise(prompt, answers, round?, materials?) | Run one more round yourself: show the members everything said last round — including answers only you can produce — and get them back revised |
revision_prompt(prompt, answers, seat, materials?) | The prompt to hand your own seat for the next round, word-for-word what the members got. No network calls |
list_council() | The roster: ids, endpoints, weights, what each member can be shown, the route each takes out, call budget, and whether it is ready. No network calls |
probe_models(model?) | Ask a provider's /models route what ids it really exposes |
Members are stateless and cannot see your conversation, so the chair passes
everything they need in each call. That is exactly what makes cross-review work:
it puts one member's answer inside another's prompt.
A question is usually about something — a spec, a log, a diff, a screenshot. The
obvious way to include it is to paste it into prompt, and that is the expensive
one, in the place nobody watches: prompt is an argument the chair writes, so
a long document costs a full copy of itself in generated tokens on every call,
and what reaches the members is whatever the chair managed to reproduce. For
forty pages that is not reliably the document. A council reviewing a paraphrase
is not reviewing the thing, and nothing in the transcript would say so.
materials names it instead:
The server reads each one and puts it ahead of the question, in the same place for every member and every round. The position is not presentation:
cache_control breakpoint at that boundary; endpoints
that cache by prefix on their own get the shape they need either way. Set
"cache": false on a member whose gateway rejects the field.ask_all carries the material into round 2 and 3 by itself.Images are the case that matters most. Without them the chair has to describe
the screenshot in prose — and then every member reads the same description, so
anything the chair misread is misread by the whole council at once, and
cross-review cannot recover it. It is the one input where passing it badly
quietly removes the independence the council is for. Png, jpeg, gif and webp go
to every member whose model can see; a member that cannot should be configured
"vision": false, and it then sits out the calls that carry an image rather than
answering about text alone as though it had seen the picture. The transcript
names who sat out.
How to tell which members those are: a member that cannot see rarely says so.
One Anthropic-compatible gateway tested while building this accepted the image
blocks, discarded them, and the model then named a colour — not "I was sent no
image", which the prompt had explicitly asked for in that case. Text material
through the same endpoint arrived intact, so nothing about the call looked wrong.
Show a member one unambiguous picture and ask what is in it; a confidently wrong
answer is the symptom, and "vision": false is the fix.
Two limits worth knowing. A material that cannot be read stops the call — a
council asked about a document it never received will answer anyway, fluently,
and read exactly like one that had. And revision_prompt names your files
rather than pasting them back, at the position the members were given them, so
open them for your own seat before you hand it the rest.
Whether this server will read a path at all depends on how it was started; over
HTTP it will not, unless its operator named a directory.
list_council says which, in a line above the table.
ask_all(prompt, rounds=2) runs that cross-review for you. Round 1 is the usual
parallel ask. Round 2 goes back to each member carrying the question plus every
answer from round 1 — its own and the others', verbatim — and asks it to revise:
take what is right, correct what is not, and say where it still disagrees and
why. The transcript comes back round by round, so you can see who moved and who
held their ground.
Carrying the previous round back is the whole mechanism. Members remember nothing between calls, so without it a second round is just the same question asked twice. Up to 3 rounds; each one costs another call per member and a longer prompt than the last, so 1 is right for a survey of opinion and 2 for a question where the disagreement is the interesting part.
rounds is chosen before anything has been asked, which is the one thing
wrong with it: you commit to a second round without having read the first, and a
council that turns out to agree costs exactly what one still arguing would. Ask
with rounds=1 when you would rather look first, then buy the next round with
revise — it runs exactly one more, as many
times as you judge it worth, and has no ceiling of its own. Reading before you
buy is usually the cheaper side: another round is a full call per member, while
revise costs you only the answers written back into it. The 3 on ask_all is a
ceiling on what one call will spend, not on what the discussion can have, and the
transcript says so when you reach it.
Members can also carry different weights, for the common case where the council is not a council of equals.
A council mostly agrees, and its agreement is the least informative thing it produces. Everything above works against convergence — the members are anonymous to each other, they are never told the weights, and the closing instruction tells them not to cave — but none of it creates any pressure to diverge. The strongest objection to a plan is not volunteered by members who think the plan is fine.
steelman seats one:
One member writes the strongest case against whatever the table has converged on, each round, and it goes back to everyone as an ordinary anonymous answer. In the next round they have to deal with it.
No member is told to argue a side it does not hold. That is the line, and it is what separates this from a debate mode. What the members say is still what they think; the assignment lives in one extra call they are never told about. Handed a seat marked "arguing against", a model discounts the argument instead of answering it — so the provenance goes to you, in a note at the end of the transcript, and the argument goes to them.
It speaks every round, not once. This is the part that looks like a detail
and is not. An objection that cannot reply to its own rebuttal is quoted rather
than represented: it cannot correct a misreading of itself, so by the third round
the table is arguing with its paraphrase and calling that an answer. tenure
buys fewer rounds than the default, and when the seat is retired early the
transcript says it was retired by configuration — because an unexplained silence
reads exactly like a position abandoned.
The mirror of that is worth as much: the last thing the objection says is the
last thing in the transcript, so nobody has been asked to take it on, and the
transcript says that too. An objection nobody answered is not a point that
stood — it is a point that was never examined. With rounds=2 that is true of
everything it said, which is why the note names the setting that fixes it rather
than leaving you to notice after paying.
Read what it produces as the strongest objection this council can make to order, never as evidence that anyone holds it. A point of its that survives being answered is worth something; the same point in the round it appeared is worth nothing yet.
By default the first member being asked writes it, and also answers as itself —
the two calls are unrelated as far as it knows. Name another with
steelman={"model": "glm"}.
Your assistant is not only the chair — it can answer too, and in Claude Code or
Codex it can spawn a subagent to answer as well. Those answers used to sit
beside the council's, compared by hand at the end. guests puts them in it:
Round 1 prints it beside the members. From round 2 every member is handed the text verbatim and asked to argue with it:
That is the whole difference. Without it the models never learn your subagent had an opinion, and you are left doing the comparison yourself — which is the work the rounds mechanism already does better, because it lets the models answer each other rather than answering into a void.
Notes worth having:
weight works on guests too, on the same scale as the members'.A guest speaks once. To let a voice you produce yourself keep up with the
members — answer, read the others, revise, round after round, exactly as they do
— you have to drive the rounds, because this server cannot spawn your subagent.
revise runs one round on demand:
Naming the member with model is what makes it a revision: that member is handed
its own previous answer back as its own, and asked to move from it rather than
answer fresh. An entry with label instead is a voice from outside the roster.
The members cannot tell the difference. An outsider passed to revise is
presented exactly as another member is — a bare letter, --- ROUND-1 ANSWER C ---
— because it will answer again next round, and it is the same reason an ask_all
guest is flagged as finished. Describing a voice as done when it is about to
speak again misrepresents the discussion to the models doing the arguing.
Prompt your subagent with revision_prompt, not with the original question.
This is the one way to get the loop wrong, and it fails silently: a subagent
handed the question again simply reproduces its previous answer, the transcript
still looks like a discussion, and nothing marks the round where that seat
stopped taking part.
It returns exactly what the members were given — its own previous answer marked
as its own, everyone else's, and the same closing instruction, including the line
telling it not to abandon a position it still believes just because it is
outnumbered. That sentence is most of what keeps a council from collapsing into
agreement, and a seat prompted without it is not being asked the same question as
the others. The call is local and makes no network requests, so run it alongside
revise rather than after it.
revise is unbounded — the 3-round ceiling on ask_all exists because that call
spends its own budget, while here every round is one you chose to pay for.
ask_all(guests=…) | revise(answers=…) | |
|---|---|---|
| Calls | one | one per round |
| Your voice | speaks once | revises every round |
| Rounds driven by | the server | you |
Inside a revision round the other answers arrive as letters, never as names:
A model name is the same kind of signal as a weight, and the stronger of the two: models hold firm priors about each other's makers. Withholding the number while printing the brand would close the smaller channel and leave the larger one open. What reaches a member is the argument, which is the thing we wanted weighed.
Letters come from position at the table, so they are stable: B is the same seat
to every member and in every round, which is what lets one of them say "B was
wrong about the index" and still be understood next round.
You keep the names. Every transcript that contains a revision round ends with the key:
You are the exception because you are the one who has to tell them apart — see who moved, who held, and who was talking about whom.
One honest limit: this covers the labels the server writes, not a name a model puts inside its own answer. That prose is carried verbatim into the next round, because the alternative is editing the text the others are meant to be critiquing. Anonymity here removes the standing signal, not every mention.
A call that fails transiently is retried before it is reported: HTTP 429 and
5xx, and dropped or timed-out connections. Backoff is exponential from 1s with
jitter, and a Retry-After header wins over that curve — unless it asks for
longer than 30s, in which case the call stops and says so rather than sitting on
it. Failures that will not change on a second look — 401, 404, a malformed
response body — are reported immediately; retrying them only spends the same
quota to be told the same thing. Defaults to 2 retries; set retries: 0 for the
old single-shot behaviour.
A member that exhausts its attempts returns its error as that member's answer, so the rest of the council still answers — unless it has somewhere else to go, in which case it goes there. See Backups.
The server is listed on the official MCP Registry
as io.github.Totti0135/model-council, so a client that browses the registry can
find and add it there. To wire it up by hand instead, read on.
It runs from PyPI with no clone and no virtualenv. You need uv:
Easiest is the desktop extension. Download model-council-<version>.mcpb from
the latest release
and drag it onto Settings → Extensions. The app asks for the endpoints and keys
in a form and keeps the keys in your OS keychain, so no file on disk holds them.
The form seats two models; for a larger council, point its "Config file" field
at a JSON config (see below).
To wire it up by hand instead, edit claude_desktop_config.json
(Settings → Developer → Edit Config), add the block below, then fully quit and
reopen the app — Cmd-Q, not just closing the window. You will know it worked
when the tools menu lists model-council.
Anything that launches a stdio server works: run uvx model-council-mcp and
pass the same environment variables.
Everything above runs one copy of the server per person, launched by their own
MCP client, configured with their own keys. --http is the other shape: one
deployment holds one set of keys and answers a whole team, who configure a URL
and no secret at all.
Colleagues then add it as a remote server, with nothing sensitive in the config:
deploy/ has a Dockerfile, a
compose file and a systemd unit.
Over stdio the operating system answers this: whoever launched the process
already had the keys. HTTP removes that guarantee — one port now stands in front
of shared provider quota — so the server refuses to start on a non-loopback
address until --allow says who may reach it. Loopback needs no flag, and is
always admitted.
| Flag | |
|---|---|
--allow | CIDRs, bare addresses, or the names private (RFC1918), loopback, any |
--trust-proxy | reverse proxies whose X-Forwarded-For may be believed |
--allow-origin | permit a browser Origin; repeatable |
--materials-root | the one directory materials paths may name; without it, HTTP refuses paths |
--trust-proxy is the one worth reading twice. Without it X-Forwarded-For is
ignored entirely and the peer address decides — behind nginx that is nginx, so
the allowlist matches everyone or no one. With it, the client is the rightmost
hop in the chain that is not a trusted proxy, which is what stops a caller
from writing X-Forwarded-For: 10.0.0.1 and walking straight through.
Requests carrying an Origin header are refused by default. MCP clients are not
browsers and do not send one; a web page always does. An allowlist admits every
machine on the office network, and each of those runs a browser that will issue
requests on behalf of whatever page it has open — Origin is what tells the two
apart.
Every flag has an environment variable (COUNCIL_ALLOW, COUNCIL_TRUST_PROXY,
COUNCIL_HTTP_HOST, …); --help lists them.
Over stdio, materials reads any file the process can, and needs no flag: the
caller launched this process, so it already had that access — the same reasoning
that lets a loopback bind skip --allow. Over HTTP the reasoning is gone. The
caller is whoever reached the port, a path would make one shared council into a
way to read its host's files, and what it read would leave for an external
provider. So an HTTP deployment refuses paths outright, and callers pass the
contents as text.
--materials-root /srv/council/material opens exactly one directory, resolved
before it is compared, so a symlink is judged by where it lands.
The allowlist is a network boundary, not an identity. Anyone inside it calls without a credential, so usage cannot be attributed to a person, rate-limited per person, or revoked for one person. That is a deliberate trade — it is what makes the client config a bare URL — but it means the network has to be a boundary you actually trust, and it does not survive contact with a VPN that admits contractors, or a CI runner on the same subnet.
If you need per-person attribution or quota, put an LLM gateway (LiteLLM, one-api, or whatever your organisation already runs) behind this server and give each caller their own virtual key there, or run this behind a reverse proxy that does SSO.
One more thing worth knowing before you announce the URL: this service forwards whatever text it is given to an external provider. A shared endpoint with no credential is a data-egress path for everyone who can reach it.
ask_all with rounds=2 is a long request — several models, several attempts
each, at up to COUNCIL_TIMEOUT (180s) per call. Default proxy timeouts will
cut it off well before the server is finished:
Then start the server with --trust-proxy set to the proxy's address, or the
allowlist will only ever see the proxy.
Two layers, so several models can share one endpoint without repeating its credentials:
base_url + api_key + which wire format it speaksConfiguration comes from whichever source is most explicit: the file
COUNCIL_CONFIG points at, else the roster COUNCIL_MODELS names, else a config
file at ~/.config/model-council/config.json, else the built-in default roster.
Explicit beats discovered on purpose — a config file you left lying around must
not silently override settings a client just handed the server.
list_council() always reports which source won.
COUNCIL_MODELS lists the ids; each id gets variables named after it, uppercased
with non-alphanumeric characters turned into underscores (my-model →
MY_MODEL_BASE_URL).
Per member: _BASE_URL, _API_KEY, _MODEL, _FORMAT, _LABEL, _WEIGHT,
_MAX_TOKENS, _TEMPERATURE, _TIMEOUT, _RETRIES, _RETRY_BACKOFF,
_HEADERS (a JSON object), _PROXY, _VISION, _CACHE, _ENABLED. Globally:
COUNCIL_TIMEOUT, COUNCIL_RETRIES, COUNCIL_RETRY_BACKOFF, COUNCIL_PROXY,
COUNCIL_CONFIG, COUNCIL_ENV_FILE, COUNCIL_MATERIALS_ROOT.
Omit COUNCIL_MODELS and the roster defaults to chatgpt,glm, reading
CHATGPT_* and GLM_*.
Better once you have more than a handful of members, or when several share an
endpoint. Set COUNCIL_CONFIG=/path/to/config.json, or drop the file at
~/.config/model-council/config.json where the server finds it on its own.
${ENV_VAR} is expanded from the environment, so the file carries no secrets and
can be shared or committed. See examples/config.json for a
fully annotated version.
A member gets its connection one of two ways, never a mix of both: name a
provider and take that endpoint whole, or omit provider and supply
base_url + api_key + format yourself (as kimi does above). Naming a
provider and overriding one of those three is refused — that member is
disabled and list_council says why. The reason is that a partial override
would pair one endpoint's credentials with another endpoint's URL, quietly
sending your key to a host it was never issued for. Per-member headers,
timeout, temperature, max_tokens and label are not part of that
identity and stay overridable.
The first three travel together as one unit — see the rule above.
| Field | Applies to | Notes |
|---|---|---|
base_url | provider, or a member with no provider | Root the route hangs off — /chat/completions for openai, /v1/messages for anthropic. Usually ends in /v1 for OpenAI-compatible hosts |
api_key | provider, or a member with no provider | |
format | provider, or a member with no provider | openai (default) or anthropic |
model | member | The model id sent to the endpoint |
label | member | Display name in answers; defaults to the id |
weight | member | How far this member's opinion carries. Default 1, max 10, 0 for advisory only. See Weights |
max_tokens | member | Anthropic format only, where it is required. Default 8192 |
temperature | member | Sent only when set |
headers | provider, member | Extra HTTP headers |
timeout | provider, member | Seconds, per attempt. Default 180 |
retries | provider, member | Extra attempts a transient failure gets. Default 2, max 5, 0 to disable |
retry_backoff | provider, member | Seconds before the first retry, doubling from there. Default 1 |
proxy | top level, provider, member | The route out. Omit to follow HTTP_PROXY/HTTPS_PROXY; false to connect directly; a URL to use that proxy; "env" to rejoin the environment's. See Proxies |
vision | member | false for a model that cannot be shown an image. It then sits out calls carrying one, rather than answering about the text alone. Default true |
cache | provider, member | false stops the cache_control breakpoint being sent with material. Anthropic format only; turn it off for a gateway that rejects the field. Default true |
enabled | member | false parks a member without deleting its config |
backups | member | Further endpoints for the same seat, tried in order when the one before them does not answer. Max 4. See Backups |
timeout, retries, retry_backoff and proxy can also be set at the top level
of the config file, as the default every member inherits.
A council is rarely made of equals. weight says how far a member's opinion
carries — everyone is 1 until you say otherwise, and only the ratios mean
anything, so 2 and 1 is the same council as 10 and 5.
It changes nothing about the call. When the weights differ, ask_all labels each
answer with its weight and ends the transcript with the ranking:
Weight belongs to the seat, not the endpoint, so a provider cannot set it: two
members on one relay may be a frontier model and a small fast one. 0 means
advisory — the member answers and is read, but its agreement counts for nothing.
Anything unusable (a negative, a word) falls back to 1 rather than corrupting
the ranking silently; list_council prints the effective value.
The members are never told each other's weights. A model informed that it is outranked stops arguing and starts agreeing, which costs exactly the independent dissent a council is assembled to produce — so round two carries the other answers and not their standing. The weights are for whoever reads the transcript, and they are a prior, not a vote: they break ties and decide who carries the burden of proof. A specific, checkable reason from the lowest weight still beats a bare assertion from the highest.
The same model is often reachable through more than one channel — a company gateway, a public relay, a spare key. Listing each as its own member is the wrong shape: it puts one model in the room several times, so it answers several times, is weighed several times, and in round two argues with itself.
backups are further endpoints for the same seat, tried in order when the one
before them does not answer:
One id, one label, one weight, one vote. You never address a backup —
ask(model="sol") reaches whichever of the three is up.
A backup inherits what the seat settled about the model — model, max_tokens,
temperature, vision, timeout, retries — so the ordinary case, the same
model on a second relay, is the one line above. Name model only when the other
channel calls it something else. Three things are never inherited:
base_url, api_key, format) — that is the point of a
backup. It either names a provider and takes all three from it, or brings all
three itself. Half of each is refused, for the reason in A config file.headers — a header written for one endpoint is routinely a credential for it.proxy — the route belongs to the host, not to the seat. A seat pinned
proxy: false for an internal gateway would otherwise send its public backups
around the very proxy they need. A backup takes its route from its own provider,
or from the council's default.When a seat falls through. Not only on a dead connection: a revoked key, a
model id the relay stopped carrying, a gateway answering 200 with something
that is not an answer. From the seat's point of view these are one event — this
way in is not currently a way to that model, and the config named another.
Transient failures (Retries) are still retried on the connection they
happened on first, so a backup is for an endpoint that is out, not one that is
slow to say yes. Put retries: 0 on the primary if you would rather fail over
than wait.
Which endpoint answered is printed with the answer. A backup is frequently a different model id and sometimes a different model, and a council read as a comparison of models must not quietly compare something else:
list_council shows the chain indented under each seat:
probe_models probes every link, so a backup that has quietly stopped carrying
its model is visible before the day it is needed. A seat where nothing answered
reports each connection it tried and why.
Backups are a config-file feature; the environment-variable roster has no
equivalent. Max 4 per seat — a seat is one model's opinion, not a
high-availability cluster, and ask_all waits on the slowest chain to finish
failing.
Every member follows this machine's HTTP_PROXY/HTTPS_PROXY, which is the
right default until a council spans hosts that do not share a route — a public
API that only answers through the proxy, an internal gateway the proxy cannot
see. One setting cannot be right for both, so the route is chosen per seat.
proxy takes four values, on a member, on a provider, or at the top level of the
config file as the council's own default:
| Value | The route |
|---|---|
| omitted | Follow the council's proxy if it sets one, else HTTP_PROXY/HTTPS_PROXY |
false, or "direct" | Straight out, ignoring both |
| a URL | Through that proxy — http://, https://, socks5:// or socks5h:// |
"env" | Back onto HTTP_PROXY/HTTPS_PROXY, for one seat of a council routed elsewhere |
Most specific wins: member, then provider, then the council, then the environment. So a council that is mostly behind a proxy, with two seats that must not be, says it once and then twice:
The same three moves through environment variables — COUNCIL_PROXY for the
council, <ID>_PROXY for one member:
list_council prints the route it settled on, as env, direct, or the
proxy URL, in a column that appears only when the members can differ:
A password inside a proxy URL is masked wherever it is printed — the table, the warnings, the text of a connection error.
A proxy that cannot be used is caught when the roster is read, not on the
first call. 127.0.0.1:7890 with the scheme left off is read as
http://127.0.0.1:7890 and says so in the warnings; a scheme nothing can dial
parks that member with the reason next to it in list_council, rather than
letting it fail every call with a ValueError raised from inside a request. The
member is parked rather than quietly sent another way: a proxy is named because
someone wants the traffic to go that way.
socks5:// needs one package httpx does not install by default. Install the
extra — pip install 'model-council-mcp[socks]', or
uvx --from 'model-council-mcp[socks]' model-council-mcp — or that member is
parked with a note saying exactly this.
format is not inferred from the URL. Pointing base_url at an
Anthropic-style endpoint without also setting format: "anthropic" leaves the
member on the OpenAI format, and every call fails. This is the single most
common misconfiguration.{base_url}/v1/messages, so
base_url should not already include the /v1./chat/completions, never
/responses. Some gateways expose both, but /responses may inject a
provider-chosen system persona, which is wrong for a general-purpose advisor.ConnectError that never mentions a proxy. Give that member or provider
"proxy": false and it connects directly, while everyone else keeps using the
proxy; see Proxies. Connection errors name the route the member
was on, so the three policies do not all fail the same way.probe_models to see what an endpoint actually
offers today.Things worth typing to the chair:
ask_all and give me a table of where you all agree and disagree."ask_all on this, then tell me who changed their mind and what actually settled it."Copy .env.example to .env, fill in real values, then:
The smoke test checks both configuration paths offline; with a usable .env it
finishes with a live round-trip. To point a client at your working copy, use the
model-council-mcp script inside your environment instead of uvx.
~/Library/Logs/Claude/mcp*.log). The server writes configuration warnings to
stderr at startup.[... is not configured] — that member is missing
base_url, api_key, or model. Run list_council for a per-member breakdown.base_url, or the wrong format for that endpoint.probe_models.gave up after N attempts — it failed transiently every
time. The error text is the last one the endpoint gave. list_council shows
each member's budget as attempts × timeout.timeout, or retries, for a member you would rather have fail fast.ask_all fails with a timeout while the server is still working —
that line is the client's, not this server's, and COUNCIL_TIMEOUT does not
move it: it only decides how soon a member gives up. The reference MCP SDK
draws it at 60 seconds of silence, which one slow member clears unaided. This
server reports progress every ten seconds so that a client which honours it
restarts its clock; a client that does not needs its own setting (Claude Code
takes a per-server timeout in milliseconds in its MCP config, or
MCP_TOOL_TIMEOUT for all of them). Note whose limit applies: it belongs to
the client that spawned the server process, so a server registered with a
desktop app and bridged into another tool is held to the desktop app's number,
not to the one you set where you are typing.probe_models reports that a seat would not list — read the note it prints
under the table. An endpoint that refuses GET /models is often a relay that
serves only the chat route, and that is not a member that cannot answer. ask
is what settles it.ConnectError while the rest are fine — it is
usually the route, not the endpoint. The error names which route that member
was on; list_council's route column shows all of them at once, and
Proxies is how to change one.MIT