agent-discussion-mcp

Model Context Protocol (MCP) server for reusable role-based agents, structured multi-agent debates, peer critiques, and independent judge consensus.

Supports Solo execution with tag routing and bounded Discussion mode: independent proposals, parallel critique, an independent judge, bounded revision rounds, and SQLite event logs with WAL mode.

See dsaa.md for the original project vision and architectural notes (Russian).

✨ Features

• Role Profiles ("Gems"): Reusable agent profiles with custom roles, system prompts, model overrides, routing tags, temperature, and output token limits.

• Solo Execution (run_solo): Run single-agent tasks directly by agent name or automatically route by tag matching without guessing on ambiguity.

• Structured Discussion Mode (run_discussion):

  1. Independent Proposals: Participating agents draft proposals in parallel without seeing other agents' work.

  2. Peer Critique: Agents review all proposals and produce structured critiques (strengths, concerns, questions).

  3. Independent Judge: A designated judge evaluates the blackboard and decides consensus vs. no-consensus with a defensible final answer and confidence score.

  4. Bounded Revision: If no consensus is reached, agents revise their proposals addressing critiques for up to max_rounds.

• Shared Token Budget: Dynamic token reservation and settlement preventing token overrun in concurrent calls.

• Event Sourcing & Audit Log: Monotonic append-only SQLite log (session_events) recording all proposals, critiques, verdicts, and errors in WAL mode.

• Transient Error Resilience: Exponential backoff with jitter on network/HTTP status errors (408, 409, 429, 5xx) and fallback verdict if a judge fails.

• Client Progress Reporting: Native MCP progress notifications (ctx.report_progress) during multi-round debates.

Related MCP server: Executive Cortex MCP

🚀 Quick Start

Installation & Running

# Clone the repository
git clone https://github.com/ewanni/agent-discussion-mcp.git
cd agent-discussion-mcp

# Install dependencies with uv
uv sync --extra test

# Configure provider settings
export AGENT_DISCUSSION_API_KEY="your-openai-or-compatible-key"
export AGENT_DISCUSSION_BASE_URL="https://api.openai.com/v1"
export AGENT_DISCUSSION_MODEL="gpt-4o-mini"

# Run the MCP server over stdio
uv run agent-discussion-mcp

(Note: legacy API_AGENT_* environment variables and api-agent-mcp CLI binary are also supported for backwards compatibility).

🛠️ MCP Tools & Resources

Tools

• create_agent: Register a new agent profile (name, role, system_prompt, model, tags, temperature, max_output_tokens).

• update_agent: Modify fields of an existing profile.

• list_agents: Inspect all registered profiles (omits private system prompts / credentials).

• run_solo: Execute a task with a named agent or tag-routed agent.

• run_discussion: Run a bounded debate with 2–5 participant agents, a separate judge, round limit (1–5), and a shared completion token budget.

Resources

• agent://profiles/{name}: Read a specific agent profile configuration as JSON.

⚙️ Configuration & Environment Variables

🧪 Testing & Development

Run the test suite with pytest:

uv run pytest

🗺️ Roadmap

1. ✅ Solo mode and profile registry

2. ✅ Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget

3. ⏳ Subagent verification and resumable background execution for long-running discussions

📄 License

MIT