superai-mcp

<div align="center"><a name="readme-top"></a>

SuperAI MCP

One MCP server to bridge them all: <br/> Unify Claude Code, Codex CLI, and Gemini CLI for seamless multi-model collaboration.<br/> Broadcast, chain, vote, debate — AI models working together.

English · 简体中文 · [Changelog][changelog] · [Issues][github-issues-link]

<!-- SHIELD GROUP -->

[![][github-release-shield]][github-release-link] [![][python-shield]][python-link] [![][mcp-shield]][mcp-link] [![][github-license-shield]][github-license-link]<br/> [![][github-stars-shield]][github-stars-link] [![][github-forks-shield]][github-forks-link] [![][github-issues-shield]][github-issues-link] [![][github-contributors-shield]][github-contributors-link]<br/> [![][claude-shield]][claude-link] [![][codex-shield]][codex-link] [![][gemini-shield]][gemini-link]

Share SuperAI MCP

[![][share-x-shield]][share-x-link] [![][share-reddit-shield]][share-reddit-link] [![][share-telegram-shield]][share-telegram-link]

^{Multi-model collaboration, one MCP call away}

</div> <details> <summary><kbd>Table of contents</kbd></summary>

TOC

• ✨ Features
  • Multi-Model Broadcast
  • Chain Pipeline
  • Vote Consensus
  • Multi-Round Debate
  • Batch Processing
  • Auto-Retry Fallback
  • Response Cache
  • Streaming Output
  • Model Discovery & Validation
  • Cost Tracking & Quota
  • Security
• 📦 Getting Started
  • Prerequisites
  • Installation
• 🛠️ Tools Reference
• 🧪 Testing
• 🤝 Contributing
• 📝 License

<br/> </details> <br/>

✨ Features

🔀 Multi-Model Broadcast

Send the same prompt to Claude, Codex, and Gemini in parallel and get aggregated results in a single response. Perfect for multi-perspective code reviews, comparing model reasoning, or finding consensus across different AI engines.

• Per-target model and parameter overrides via models and overrides
• System prompt injection for consistent instructions across all targets
• Built-in prompt templates: review, refactor, explain, test, debug, optimize

🔗 Chain Pipeline

Build sequential multi-model pipelines where each step's output automatically flows into the next. Chain different models for tasks that benefit from staged processing — draft with one, refine with another, verify with a third.

• Output auto-injected as <previous_output> tags between steps
• Stops on first failure with partial results returned
• End-to-end timeout budget across all steps

🗳️ Vote Consensus

Run candidates in parallel, then have a judge model pick the best answer. Get the most reliable output by leveraging the strengths of multiple models simultaneously.

• Judge auto-excluded from candidate pool
• Only successful candidate outputs forwarded to judge
• Fully configurable candidate and judge selection

💬 Multi-Round Debate

Stage an alternating debate between two models over multiple rounds. Each round sees the opponent's previous response. Ideal for exploring trade-offs, stress-testing solutions, or generating balanced analysis.

• Configurable number of debate rounds
• Opponent output injected as <opponent_response> tags
• Any two CLIs as debate sides

<details> <summary><kbd>More Features</kbd></summary> <br/>

⚡ Batch Processing

Run N prompts against the same CLI concurrently in a single tool call. Bypasses stdio serialization bottleneck with server-side dispatch via asyncio.Semaphore. Up to 20 tasks with configurable concurrency.

🔁 Auto-Retry Fallback

Automatic cascading degradation on rate-limit, server error, or timeout. Retryable patterns include RESOURCE_EXHAUSTED, overloaded_error, 429, 5xx, timed out, etc.

CLI	Fallback Strategy	Example
Gemini	Switch to flash model	pro → flash
Claude	Model downgrade	current → sonnet → haiku
Codex	Reduce reasoning effort	high → medium → low

🗄️ Response Cache

Opt-in LRU+TTL in-memory cache (use_cache=True). Identical requests (same cli+cd+prompt+model) return cached results instantly. Configure via SUPERAI_MCP_CACHE_TTL (default 300s) and SUPERAI_MCP_CACHE_MAXSIZE (default 128).

📡 Streaming Output

Real-time push of AI response chunks via MCP ctx.info() notifications (stream=True). Get immediate visibility into long-running tasks while the final complete response is still returned as the tool result.

🔍 Model Discovery & Validation