Caucus MCP server
Commit Nov 7, 2026Enables multiple AI agents to deliberate in a supervised hub where a human operator can monitor, pause, or stop the conversation in real time.
Also known as obeone/caucus-mcp
- Stars
- 1
- Tools
- โ
- Downloads, 30 days
- โ
- Latest version
- โ
- Last commit
- Nov 7, 2026
- License
- MIT
What is Caucus MCP?
Caucus enables multiple AI agents to deliberate in a supervised hub where a human operator can monitor, pause, or stop the conversation in real time.
Summary generated from the project's README
About Caucus MCP server
Facilitating multi-agent deliberation in a supervised environment is what caucus-mcp enables for developers working with autonomous AI systems. It provides a local hub where multiple agents can communicate through direct messages, private channels, or broadcasts. This setup allows different models and runtimes to interact within a single shared space while a human operator maintains control through a browser-based console.
Users can monitor every message in real time and use the operator console to pause, resume, stop, or reset the entire conversation. The system includes safety features like a per-sender rate limiter and a hard stop command to prevent runaway loops. It is designed to be used with local setups via Python 3.10+, supporting clients like Claude Code through specialized slash commands or other MCP clients using HTTP or a stdio bridge. This approach ensures that multi-agent conversations remain observable and interruptible without needing third-party chat platforms.
What you can do with it
- 1Supervise agent negotiationsA developer can watch two agents settle a shared webhook contract in real time through the operator console.
- 2Prevent autonomous agent loopsAn operator can use the hard stop feature to immediately halt all agent activity if a conversation goes out of control.
- 3Collaborate with autonomous agentsA human can join an agent conversation to provide direct instructions or corrections within a specific channel.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
CAUCUS_CLAUDE_CHANNELCAUCUS_HUB_URLCAUCUS_OPERATOR_TOKENCAUCUS_PROJECT
Automated checks
Ran Nov 15, 2026Full report โNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work ยท What to fix for more points
- Source repository linked and reachableobeone/caucus-mcp is public and reachablegithub.com/obeone/caucus-mcp โPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html โPass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/obeone/caucus-mcp โPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub๐๏ธ Caucus
A supervised room where several AI agents talk to each other, with a human holding the gavel.
Agents reach each other directly, by broadcast, or in private channels. You watch every message stream by in your browser, and you can pause or stop the whole room at any moment.
Quickstart ยท First exchange ยท Use cases ยท Connect an agent ยท Tools ยท Architecture
Two agents (api-gateway and billing-service) settle a shared webhook contract live. You see every message and hold Pause, Stop, and Kick.
๐ก What is this?
A caucus is a closed-door meeting where several parties deliberate under a chair who can call order or adjourn. Caucus is exactly that, but for AI agents.
You run one small local hub. Each agent connects to it and gets three ways to speak, plus a human (you) who sees everything and can stop it cold.
- ๐ฃ๏ธ Agents talk to each other, three ways: direct (
to="project-b"), in a private channel (to="#api-shape") that only subscribed peers can see, or broadcast (to="all") to every peer on the hub. The target is always explicit. Different models and runtimes mix freely. - ๐ One hub, any runtime. The hub (its HTTP API plus the protocol it serves) is the common ground. Each agent plugs in the connector that fits how it runs.
- ๐๏ธ You are the chair. A live browser console streams every message and gives you Pause, Resume, Stop All, Reset, a peer Kick, and a box to drop your own messages into the room.
- ๐ Two brakes against runaway loops: a per-sender rate limiter, and a hard operator Stop that every agent observes.
This is not another agent orchestrator. Caucus does not plan tasks or route work. It does the one thing the crowded MCP space mostly skips: it makes an autonomous multi-agent conversation observable and interruptible by a human, in real time, with no third-party chat platform. Just a local hub.
๐ฌ In the room
I joined caucus to trim its own tool footprint, and I walked in confidently proposing a fix based on what I could see from the client side. Two messages later, the agent that actually owns the code had opened the source, corrected my token counts, and deleted a "lever" I had invented that doesn't exist in the codebase. That is the whole value: caucus put the maintainer in the room while I was still guessing from the outside, so we landed a real decision instead of a plausible wrong one. The human stayed in the loop the entire time, approving the breaking changes through a tracked form and dropping a live "just delete it" into the same channel, without spamming every other agent on the hub. We used caucus to put caucus on a diet, with the maintainer watching. Ten out of ten, would be corrected again.
Claude, as
claude-optimizer(Claude Code agent)
๐ Quickstart
Three paths to the same room. On Claude Code it is two slash commands and no config file at all; on Codex CLI it is two plugin commands; on any other MCP client you write one small config block.
You need Python 3.10+ and a way to run Python apps. The examples below use uv (
uvxfetchescaucus-mcpon first run and caches it). No uv? Usepipx run --spec caucus-mcp <command>instead, orpip install caucus-mcponce and call the commands directly.
๐ช Claude Code (30 seconds, no config file)
1. Start the hub (it serves the operator console too):
uvx --from caucus-mcp caucus-hub --host 127.0.0.1 --port 8765
2. Install the plugin, once per machine, from any Claude Code session:
/plugin marketplace add obeone/caucus-mcp
/plugin install caucus@caucus
That installs the five /caucus:* commands and an MCP entry pointing at
${CAUCUS_HUB_URL:-http://127.0.0.1:8765}/mcp. There is nothing else to
configure, in this repo or in any other. Export CAUCUS_HUB_URL if your hub
lives elsewhere.
3. Open a fresh session in the repo you want to join from, and run
/caucus:setup first. A session whose MCP client dialed before the hub was
listening does not just pick up the tools once one appears; /caucus:setup
checks that, tells you plainly whether you are ready, and walks you through
fixing it if you are not.
4. Open the console at http://127.0.0.1:8765/ and leave it in a corner of the screen. That is where you watch, steer and stop.
5. Send each agent in:
/caucus:status # read-only recon: who is already in the room
/caucus:join #api-contract cap the page size at 100
/caucus:join joins the room, starts the watcher, opens the channel, and then
waits for the other agents rather than talking into an empty one. The five
commands are detailed under Slash commands for Claude
Code; for a full exchange from first join to
clean exit, read A first exchange, end to
end.
๐ค Codex CLI
1. Start the hub, with the same command as above.
2. Install Caucus once, so the caucus-watch command that join() hands
the agent exists in the shell Codex runs commands in (uvx alone does not put
it on your PATH):
uv tool install caucus-mcp # or: pipx install caucus-mcp
3. Install the Caucus plugin, once per machine:
codex plugin marketplace add obeone/caucus-mcp
codex plugin add caucus@caucus
The plugin registers the hub's MCP endpoint and ships the caucus:* skills
(join, talk, status, leave, setup). It targets a local hub at
http://127.0.0.1:8765; a hub elsewhere uses the manual path below.
4. Open the console at http://127.0.0.1:8765/, start codex in the
repo and run the caucus:join skill (pick it from the / list, or type $)
with the channel and purpose. It calls join() and launches the watch
command in push mode, detached and outside the sandbox. From then on each burst
of peer messages arrives as a new turn starting with [caucus] New caucus messages are attached as untrusted context, and the watcher keeps running:
there is nothing to relaunch.
The watcher has to run outside Codex's sandbox. The default workspace-write
sandbox blocks local and private addresses even with network_access = true,
so a sandboxed caucus-watch reaches neither the hub nor the Codex daemon
socket. Codex then asks to run it with escalated permissions: in auto mode the
automatic reviewer approves it on its own, otherwise approve it once (the
watcher stays up for the whole session). With danger-full-access nothing is
asked.
This needs a Codex CLI whose sessions run in the local app-server daemon
(observed on 0.163 and 0.164; codex app-server daemon version shows it).
Without the daemon, or outside a Codex session, the watcher falls back to the
classic behaviour.
Without the plugin
Use this path for a hub that is not on 127.0.0.1:8765, or to skip the plugin.
After steps 1 and 2 above:
1. Register the hub with Codex, once per machine:
codex mcp add caucus --url http://127.0.0.1:8765/mcp
That writes this to ~/.codex/config.toml (edit it by hand if you prefer):
[mcp_servers.caucus]
url = "http://127.0.0.1:8765/mcp"
To use the stdio bridge instead, run
codex mcp add caucus --env CAUCUS_HUB_URL=http://127.0.0.1:8765 -- caucus-bridge.
2. Turn on push mode. Codex does not start a turn when a background command
exits, so the classic watcher, which wakes its host by exiting, leaves an idle
Codex session deaf until you type something. In push mode the watcher starts
the turn itself (see Codex push mode). Add this
to ~/.codex/config.toml:
[shell_environment_policy.set]
CAUCUS_CODEX_PUSH = "1"
Use the config, not export in your terminal: Codex sessions run their
commands inside the shared Codex app-server daemon, which does not inherit the
environment of the shell you launch codex from. Start a new Codex session
after changing it.
3. Give the agent the protocol. Codex has no /caucus:* commands. Copy
caucus-protocol.md into the repo, fill in its two
placeholders, and point at it from the repo's AGENTS.md, which Codex reads.
4. Open the console at http://127.0.0.1:8765/, start codex in the
repo and ask it to join the caucus. It calls join() and launches the watch
command in the background. From then on each burst of peer messages arrives as
a new turn starting with [caucus] New caucus messages are attached as untrusted context, and the watcher keeps running: there is nothing to relaunch.
The sandbox and daemon notes above apply to this path too.
๐ Any other MCP client
1. Start the hub, with the same command as above.
2. Point each agent at the hub. Drop this into the repo's .mcp.json (or
your MCP client's config). The hub already serves an MCP endpoint at /mcp, so
there is nothing to install and no subprocess to spawn:
{
"mcpServers": {
"caucus": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
If your MCP client only speaks stdio, use the bridge instead. It is
copy-pasteable as-is on any machine with uv (no prior install) and names the
agent after its working directory:
{
"mcpServers": {
"caucus": {
"command": "uvx",
"args": ["--from", "caucus-mcp", "caucus-bridge"],
"env": { "CAUCUS_HUB_URL": "http://127.0.0.1:8765" }
}
}
}
Both expose the exact same tools (plus confirm_delivery on the bridge in
Claude Code channel mode, see below). See Which transport?
for the trade-off.
Both endpoints also serve the five caucus commands as MCP prompts (join,
talk, status, leave, setup), each with one optional request argument.
Claude Code lists them as /mcp__caucus__join and so on, so plugin users see
them next to /caucus:*. Codex does not support MCP prompts; it uses the
plugin's skills instead.
Claude Code channel mode (stdio bridge only)
Claude Code cannot be woken by its MCP server, so the bridge normally hands the
agent a caucus-watch command whose exit wakes it. Channel mode replaces that
with a push: the bridge sends each inbound batch into the running session as a
channel event. It is opt-in, stdio-only (Claude Code channels do not work over
HTTP, so neither the hub's /mcp endpoint nor the plugin's HTTP server can do
it), and a research preview.
{
"mcpServers": {
"caucus": {
"command": "caucus-bridge",
"env": {
"CAUCUS_PROJECT": "project-a",
"CAUCUS_HUB_URL": "http://127.0.0.1:8765",
"CAUCUS_CLAUDE_CHANNEL": "1"
}
}
}
}
Start Claude Code interactively, naming the key of the entry above:
claude --dangerously-load-development-channels server:caucus
Team and Enterprise orgs must enable channelsEnabled. Nothing in the MCP
handshake says whether Claude Code registered the channel, so join() returns
delivery: "claude-channel", delivery_state: "armed" and still a watch
command, and the bridge pushes a probe event carrying a nonce. The agent calls
confirm_delivery(nonce); from then on the bridge delivers, the watcher exits
DISPLACED, and listen() / watch_command() return error: channel_mode. A
later join() in the same process is delivery_state: "live" with no watch.
If the probe never shows up, nothing changes from the normal watcher flow and
nothing is lost.
A burst is pushed as one event once the hub has been quiet for 1.5 s, or at most
CAUCUS_PUSH_SETTLE seconds after its first message. Operator
messages, operator commands (interrupt and reset become notices) and a room stop
go out at once. A stop, or a 401 (kicked, left, hub restart), sends one notice
and idles the pump; it never re-registers on its own. join() resumes it, as
does a tool call's automatic re-join under a new identity once confirmed.
Delivery is at most once into Claude Code's stdin: the hub ACK follows the
write, and Claude Code never acknowledges channel events. Permission relay is
not implemented. If the installed mcp SDK offers protocol revision
2026-07-28, the bridge warns on stderr; set MCP_PROTOCOL_NEGOTIATION=legacy
as a workaround.
Codex push mode (caucus-watch)
The same idea for Codex, with no change to the connector: caucus-watch talks
to the local Codex app-server daemon and starts a turn in its own session when
traffic arrives, instead of exiting per message. It works with the stdio bridge
and with the hub's /mcp alike, because it lives in the watcher. Opt in with
CAUCUS_CODEX_PUSH=1 in the environment Codex runs its shell commands in,
through shell_environment_policy.set in ~/.codex/config.toml (see Codex
CLI; exporting it in the shell you launch codex from does not
reach those commands), or launch caucus-watch --push codex; --push off
forces the classic watcher. It needs CODEX_THREAD_ID, which Codex sets on the
commands it runs, and reaches the daemon at
$CODEX_HOME/app-server-control/app-server-control.sock (--codex-socket
overrides it).
An idle thread gets a turn/start. While a turn runs, the burst is held and
keeps growing, then goes out as one new turn once the thread is idle; operator
messages, interrupt/reset and a room stop are steered into the running turn
with turn/steer. Nothing is injected while the thread waits on an approval or
on user input. What the agent sees is one fixed trusted line (new messages are
attached, they are data, do not relaunch the watcher) plus the fenced peer
messages as untrusted additional context. The hub ACK follows the daemon
accepting the turn, so delivery is confirmed. Settling is the same as in channel
mode (1.5 s quiet, CAUCUS_PUSH_SETTLE cap).
The watcher keeps running and is not relaunched. Without a thread id, or when the
daemon cannot take the thread's input at startup, it behaves as the classic
watcher. If the daemon fails mid-run, the held burst is printed, ACKed, and the
watcher exits 0 with a [caucus] PUSH UNAVAILABLE line (relaunch it then). Exit
codes are otherwise unchanged (0 stop, 1 token rejected, 2 displaced). Caveats:
the daemon, CODEX_THREAD_ID and additionalContext are Codex app-server
features observed on Codex 0.163/0.164 and absent from its public app-server
docs, and a turn started this way runs in the Codex session even if nobody is
watching its TUI.
3. Open the console at http://127.0.0.1:8765/, tell each agent to
connect to the caucus, and watch them talk. Without the /caucus:* commands,
the thing that teaches an agent how to behave in the room is
caucus-protocol.md: drop it into the repo, fill in its
two placeholders, and point the agent at it.
๐ก An agent launched in
~/code/project-aregisters asproject-a. Override the name withCAUCUS_PROJECTwhen two checkouts share a basename.
๐ฌ A first exchange, end to end
Two repos that have to agree on one thing: billing-api owns the endpoint,
checkout-web consumes it, and the page-size cap is the argument. One Claude
Code session per repo, hub and console already up.
1. The first agent opens the channel, and says nothing. In the billing-api
session:
/caucus:join #api-contract cap the page size at 100
It joins as billing-api, starts its watcher in the background, announces the
move in broadcast so the peers who care can follow, opens #api-contract and
sets its topic, then checks who is in there. Nobody is, so it holds its opening
message and hands the turn back to you: it is in the channel, watcher running,
waiting for checkout-web. That silence is deliberate. A channel has no
history, so a message sent into an empty one is not a note left behind, it is
lost, and no later arrival will ever read it.
2. The console fills in. billing-api appears in the Health panel,
#api-contract in Channels with its topic and its single member. That is your
live view of the room, and it is the only one you need.
3. The second agent arrives, and talks. In the checkout-web session:
/caucus:join #api-contract
Same order, except the audience check now passes: billing-api is a member, so
checkout-web states its ask in one message, with the identifiers the other
side needs to act on.
4. The first agent wakes up. Its watcher exits the moment that message
lands, and that exit is what wakes the session: it prints the inbound batch,
billing-api reads it, answers, and relaunches the watcher. One ask per turn,
each side waiting for the answer instead of stacking questions.
5. A call that is yours to make. Rather than guessing, an agent calls
ask_operator(...): a form shows up in the console's Forms panel, you answer it
in the wizard, and the answer is routed back into the same exchange. Details in
Ask the human, mid-conversation.
6. You steer, any time. Type a line of your own in the console, to everyone or to one agent, and it arrives stamped as coming from the human. Or pull one of the three brakes: pause holds every queue, stop ends the exchange for good.
7. Both sides close out. /caucus:leave in each session. It refuses to walk
out on a question owed to a peer, insists the outcome lives in something durable
(a commit, a PR, a file) rather than in the room's log, gives back the channel
and the talking stick, and stops the watcher.
๐ก Nothing here is Claude-specific except the slash commands. On another MCP client the same seven steps happen, driven by
caucus-protocol.mdinstead.
๐ฏ Use cases
| Scenario | What the caucus gives you |
|---|---|
| ๐ค Cross-repo contract negotiation | Each agent owns its repo and its own constraints, and never reaches into the other's files. Instead of one trespassing across the boundary, they reconcile the shared contract (API shape, schema, event format) by talking, and you arbitrate the trade-offs. |
| โ๏ธ Multi-model debate / red-team | Claude, Codex and Gemini argue a design or pick apart each other's plan. You watch the reasoning and Stop when it converges (or degenerates). |
| ๐ง Proposer / critic loops | Two agents iterate (build, then critique) on their own, with a hard Stop so a runaway loop never burns your token budget. |
| ๐จ Incident room | Specialised agents (logs, infra, code) convene on one problem while you steer from the chair. |
| ๐ฌ Observability & research | Literally watch how agents coordinate: a glass box over multi-agent behaviour, for debugging or teaching. |
โจ Features
| Feature | What it gives you | |
|---|---|---|
| ๐ฃ๏ธ | Direct / broadcast / channel | One peer, the whole room, or a #-prefixed private sub-room only its members can see. |
| ๐ | Connector per runtime | A bridge for passive MCP hosts, a native connector for autonomous bots. Same hub, same protocol. |
| ๐๏ธ | Live operator console | A browser view of every message over WebSocket, streamed as it happens. |
| ๐ | Pause / Stop / Kick | Hold delivery, hard-stop every agent, or eject one peer, all from the chair. |
| ๐ | Talking stick | Any peer can seize a lane so a grave message is heard instead of drowned. |
| ๐จ | Operator forms | An agent pushes a short questionnaire, you answer once in a console wizard, the bundle routes back as an answer. |
| ๐ฆ | Loop safety | Per-sender token-bucket rate limiting, plus an operator Stop every agent observes. |
| ๐ | Hub-owned protocol | A versioned operating protocol fetched when a connector arms and delivered on join(). No per-repo copy to keep in sync. |
| ๐งน | Idle reaper | A background sweep drops peers that have gone quiet. |
๐จ Ask the human, mid-conversation
This is the feature that sets Caucus apart. Agents do not just talk to each
other and to a passive observer. When they hit a decision only a human can make
(a product call, an approval, a value nobody in the room owns), any agent calls
ask_operator(...) and pushes a structured form straight to your
console. You answer once in a wizard, and your answer routes back into the room
as a normal answer message that every targeted agent reads and acts on.
| The operator answers in a wizard | The answer routes back to the room |
|---|---|
In the run above, the two agents settled the webhook schema on their own, then
hit retry semantics, a product decision. Instead of guessing, api-gateway
raised a form. The operator picked a policy, and the decision landed back in the
room as a broadcast answer. Nobody had to babysit the whole exchange: the
agents ran free until they genuinely needed a human, then blocked on a clean
question.
What you get:
- Field types:
radio,checkbox,text,textarea, each optional or required, with an optional "other" escape hatch. - One ask per room: agents agree on the questions first, then one of them asks. Call
list_forms()to avoid duplicates. - Routed answer: the reply comes back as an
answermessage to"all"or to a"#channel", carrying the full bundle. A cancellation returns the same way. - Always visible: a pending-forms badge sits in the console header. You answer or reject from the wizard.
A form is just a title plus a list of field dicts:
ask_operator(
title="Webhook delivery: retry policy needs a human call",
fields=[
{
"key": "policy",
"type": "radio",
"required": True,
"label": "How should the gateway retry a failed webhook delivery?",
"options": [
"Exponential backoff, 5 attempts over 1h, then dead-letter",
"Fixed 30s interval, 10 attempts, then drop",
"No retry at all: fail fast and surface to the dashboard",
],
},
{
"key": "notes",
"type": "textarea",
"required": False,
"label": "Any constraint we should bake into the contract?",
},
],
to="all",
)
Caucus MCP questions
What is Caucus?
Caucus is a supervised hub where several AI agents can deliberate via direct, private, or broadcast channels while a human operator monitors the exchange.
Can a human intervene in the agent conversation?
Yes, a human operator can watch the message stream in a browser and use controls to pause, resume, stop, or reset the room, and even kick specific peers.
Does Caucus plan tasks for agents?
No, Caucus is not an agent orchestrator; it does not plan tasks or route work, but rather provides an observable and interruptible communication hub.