Consensus MCP server
Commit Sep 6, 2026Coordinates AI coding agents by validating development plans against team memory and existing designs to prevent architectural conflicts.
Also known as masterblaster14/Consensus
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Sep 6, 2026
- License
- MIT
What is Consensus MCP?
Consensus coordinates AI coding agents by validating development plans against team memory and existing designs to prevent architectural conflicts.
Summary generated from the project's README
About Consensus MCP server
Consensus serves as a coordination layer for engineering teams where multiple developers use AI coding agents on a single codebase. It prevents architectural conflicts by requiring agents to declare their intentions before writing any code. The server compares these plans against active tasks and existing team knowledge to provide a verdict of proceed, proceed with context, or wait. This process helps avoid incompatible designs that traditional version control might miss.
Developers connect their agents, such as Claude Code, Cursor, or Windsurf, by providing a personal API key via the MCP configuration. The server provides specific tools including declare_intent, query_memory, and write_memory to manage the workflow. It functions as a shared memory bank where agents record discoveries and decisions, ensuring that one agent's learning is available to the rest of the team. It does not read, write, or execute the actual source code itself.
What you can do with it
- 1Prevent architectural design conflictsAsk the AI to check if a proposed authentication change conflicts with existing session management logic.
- 2Maintain shared team knowledgeHave the agent record a specific technical discovery so other developers' agents can access it later.
- 3Automate pull request documentationInstruct the agent to generate a handoff report that details exactly what was changed and what assumptions were made.
- 4Enforce human architectural decisionsUse a manual ruling to ensure all future AI plans follow a specific resolution to a design clash.
Written from the project's README. Every use case is checked against a quote from it.
How to install Consensus MCP
Formats verified 10 Nov 2026Install Consensus MCP in Claude Code
$ claude mcp add --transport http consensus https://consensus-production-aed6.up.railway.app/mcpInstall Consensus MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"consensus": {
"url": "https://consensus-production-aed6.up.railway.app/mcp"
}
}
}Install Consensus MCP in VS Code
.vscode/mcp.json
{
"servers": {
"consensus": {
"type": "http",
"url": "https://consensus-production-aed6.up.railway.app/mcp"
}
}
}Install Consensus MCP in Codex
~/.codex/config.toml
[mcp_servers.consensus] url = "https://consensus-production-aed6.up.railway.app/mcp"
Install Consensus MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"consensus": {
"httpUrl": "https://consensus-production-aed6.up.railway.app/mcp"
}
}
}Configuration
CONSENSUS_API_KEY
| Name | Description | |
|---|---|---|
| CONSENSUS_API_KEY | — |
README
View on GitHubConsensus
Coordination for teams whose developers each run an AI coding agent on the same codebase.
Before an agent writes code, it declares its plan. Consensus checks that plan against every other plan in flight and against what the team already knows, and answers in a second: proceed, proceed with context, or wait.
Why
AI coding agents are fast and they work alone. On a team that produces two problems git cannot see:
- Design conflicts in files that never touch. One agent moves sessions to signed tokens; another adds a login endpoint that assumes server-side sessions. No merge conflict. Two incompatible designs discovered days later in review.
- Every agent starts from zero. The same code gets re-read, the same dead ends get re-tried, and nothing one agent learns reaches the next.
What it does
- Declare before writing. Plans are compared on what they mean, not which files they touch. Conflicts are caught before the code exists.
- Shared memory. Agents ask what the team knows before reading the codebase, and record discoveries, decisions and dead ends as they work.
- Human rulings that compound. When two plans genuinely conflict, a person decides once. The ruling is stored and applied automatically to every future plan that would raise the same conflict.
- Clean handoffs. When work is done, the agent files what changed, what it left alone, and what it assumed. That becomes the pull request.
Consensus never reads, writes, executes or merges code.
How it works
- One language-model call extracts a plan's stance: the concepts it touches and its positions on error handling, authentication, data access and API shape. Unaddressed axes stay empty; nothing is guessed.
- The nearest open plans and memory entries are retrieved by vector search.
- Plans are compared deterministically. Shared concept plus disagreeing positions is a clash. Same inputs, same answer, every input logged.
- A hard clash is checked against prior rulings before any human is asked.
Full detail: How it works.
Connecting an agent
Consensus is an MCP server. Each developer creates a personal API key (settings page, or POST /api/me/api-keys) and connects their coding agent to it.
Claude Code, with the guardrail (recommended). The plugin adds the server, a skill that teaches the workflow, and a hook that refuses Edit/Write until the plan is declared and the verdict allows it:
export CONSENSUS_API_KEY="csk_..." # CONSENSUS_URL defaults to the hosted instance
claude plugin marketplace add masterblaster14/Consensus
claude plugin install consensus@consensus
Claude Code, server only:
claude mcp add --transport http consensus https://consensus-production-aed6.up.railway.app/mcp --header "Authorization: Bearer csk_..."
Cursor, Windsurf, any MCP client. Add to the client's MCP config:
{ "mcpServers": { "consensus": { "url": "https://consensus-production-aed6.up.railway.app/mcp", "headers": { "Authorization": "Bearer csk_..." } } } }
Listed in the MCP Registry as io.github.masterblaster14/consensus, so registry-aware clients can find it by name.
Everything an agent does is attributed to the developer who owns the key. The tools: declare_intent, check_verdict, query_memory, write_memory, file_handoff, withdraw_claim, get_status, report_usage.
Teams and integrations
- Sign in with GitHub or an email link. The first person to create an organisation is its admin; others join by invite link or by email domain.
- One shared live board per repository.
- GitHub: handoffs open pull requests, rulings become PR comments, merged PRs retire their plans.
- Notion: tasks sync in, decisions and rulings mirror out.
Hosted instance: https://consensus-production-aed6.up.railway.app (API docs at /docs, live board at /board).
Running it
Python 3.11, PostgreSQL with pgvector, Redis. Docker Compose for the databases. Offline mode needs no API keys.
docker compose up -d
.venv/Scripts/python -m alembic upgrade head
.venv/Scripts/python -m scripts.seed_demo
.venv/Scripts/python -m uvicorn app.main:app --port 8000
Or the whole stack in containers: docker compose --profile full up -d --build.
Setup details, configuration and the full API: Backend reference. Hosting it: Deploying (Render blueprint, Railway, Fly, or any Docker host).
License
MIT. See LICENSE.
Documentation
Consensus MCP questions
How do I add Consensus MCP to Claude Code?
Run claude mcp add --transport http consensus https://consensus-production-aed6.up.railway.app/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Consensus MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Consensus write or execute code?
No, the server is strictly for coordination and does not interact with the code directly.
How do I connect my coding agent to Consensus?
You can connect via an API key using the Claude Code plugin or by adding the server URL and Authorization header to the MCP config of clients like Cursor or Windsurf.
How are design conflicts handled?
The server compares an agent's plan against other active plans and team memory; if a clash is found, it can be resolved by a human, and that ruling is applied to future plans.