<p align="center">
<img src="assets/HydraMCP.png" width="200" />
</p>
<h1 align="center">HydraMCP</h1>
<p align="center">Connect agents to agents.</p>
An MCP server that lets Claude Code query any LLM — compare, vote, and synthesize across GPT, Gemini, Claude, and local models from one terminal.
## Quick Start
```bash
npx hydramcp setup
```
That's it. The wizard walks you through everything — API keys, subscriptions, local models. At the end it gives you the one-liner to add to Claude Code.
Or if you already have API keys:
```bash
claude mcp add hydramcp -e OPENAI_API_KEY=sk-... -- npx hydramcp
```
## What It Looks Like
Four models, four ecosystems, one prompt. Real output from a live session:
```
> compare gpt-5-codex, gemini-3, claude-sonnet, and local qwen on this function review
## Model Comparison (4 models, 11637ms total)
| Model | Latency | Tokens |
|----------------------------|-----------------|--------|
| gpt-5-codex | 1630ms fastest | 194 |
| gemini-3-pro-preview | 11636ms | 1235 |
| claude-sonnet-4-5-20250929 | 3010ms | 202 |
| ollama/qwen2.5-coder:14b | 8407ms | 187 |
```
All four independently found the same async bug. Then each one caught something different the others missed.
And this is consensus with a local judge:
```
> get consensus from gpt-5, gemini-3, and claude-sonnet. use local qwen as judge.
## Consensus: REACHED
Strategy: majority (needed 2/3)
Agreement: 3/3 models (100%)
Judge: ollama/qwen2.5-coder:14b (686ms)
```
Three cloud models polled, local model judging them. 686ms to evaluate agreement.
## Tools
| Tool | What It Does |
|------|-------------|
| **list_models** | See what's available across all providers |
| **ask_model** | Query any model, optional response distillation |
| **compare_models** | Same prompt to 2-5 models in parallel |
| **consensus** | Poll 3-7 models, LLM-as-judge evaluates agreement |
| **synthesize** | Combine best ideas from multiple models into one answer |
| **analyze_file** | Offload file analysis to a worker model |
| **smart_read** | Extract specific code sections without reading the whole file |
| **session_recap** | Restore context from previous Claude Code sessions |
From inside Claude Code, just say things like:
- "ask gpt-5 to review this function"
- "compare gemini and claude on this approach"
- "get consensus from 3 models on whether this is thread safe"
- "synthesize responses from all models on how to design this API"
## How It Works
```
Claude Code
|
HydraMCP (MCP Server)
|
SmartProvider (circuit breaker, cache, metrics)
|
MultiProvider (routes to the right backend)
|
|-- OpenAI -> api.openai.com (API key)
|-- Google -> Gemini API (API key)
|-- Anthropic -> api.anthropic.com (API key)
|-- Sub -> CLI tools (Gemini CLI, Claude Code, Codex CLI)
|-- Ollama -> local models (your hardware)
```
## Three Ways to Connect Models
### API Keys (fastest setup)
Set environment variables. HydraMCP auto-detects them.
| Variable | Provider |
|----------|----------|
| `OPENAI_API_KEY` | OpenAI (GPT-4o, GPT-5, o3, etc.) |
| `GOOGLE_API_KEY` | Google Gemini (2.5 Flash, Pro, etc.) |
| `ANTHROPIC_API_KEY` | Anthropic Claude (Opus, Sonnet, Haiku) |
### Subscriptions (use your monthly plan)
Already paying for ChatGPT Plus, Claude Pro, or Gemini Advanced? HydraMCP wraps the CLI tools those subscriptions include. No API billing.
```bash
npx hydramcp setup # auto-installs CLIs and runs auth
```
The setup wizard detects which CLIs you have, installs missing ones, and walks you through authentication. Each CLI authenticates via browser once — then it's stored forever.
| Subscription | CLI Tool | What You Get |
|-------------|----------|-------------|
| Gemini Advanced | `gemini` | Gemini 2.5 Flash, Pro, etc. |
| Claude Pro/Max | `claude` | Claude Opus, Sonnet, Haiku |
| ChatGPT Plus/Pro | `codex` | GPT-5, o3, Codex models |
### Local Models
Install [Ollama](https://ollama.com), pull a model, done. Auto-detected.
```bash
ollama pull qwen2.5-coder:14b
```
### Mix and Match
All three methods stack. Use API keys for some providers, subscriptions for others, and Ollama for local. They all show up in `list_models` together.
Route explicitly with prefixes:
- `openai/gpt-5` — force OpenAI API
- `google/gemini-2.5-flash` — force Google API
- `sub/gemini-2.5-flash` — force subscription CLI
- `ollama/qwen2.5-coder:14b` — force local
- `gpt-5` — auto-detect (tries each provider)
## Setup Details
### Option A: npx (recommended)
```bash
npx hydramcp setup # interactive wizard
claude mcp add hydramcp -- npx hydramcp # register with Claude Code
```
Config is saved to `~/.hydramcp/.env` and persists across npx runs.
### Option B: Clone
```bash
git clone https://github.com/Pickle-Pixel/HydraMCP.git
cd HydraMCP
npm install && npm run build
claude mcp add hydramcp -- node /path/to/HydraMCP/dist/index.js
```
### Verify
Restart Claude Code and say "list models". You should see everything you configured.
## Architecture
HydraMCP wraps all providers in a **SmartProvider** layer that adds:
- **Circuit breaker** — per-model failure tracking. After 3 failures, the model is disabled for 60s and auto-recovers.
- **Response cache** — SHA-256 keyed, 15-minute TTL. Identical queries are served instantly.
- **Metrics** — per-model query counts, latency, token usage, cache hit rates.
- **Response distillation** — set `max_response_tokens` on any query and a cheap model compresses the response while preserving code, errors, and specifics.
## Contributing
Want to add a provider? The interface is three methods:
```typescript
interface Provider {
healthCheck(): Promise<boolean>;
listModels(): Promise<ModelInfo[]>;
query(model: string, prompt: string, options?: QueryOptions): Promise<QueryResponse>;
}
```
See `src/providers/ollama.ts` for a working example. Implement it, register in `src/index.ts`, done.
Providers we'd love to see: LM Studio, OpenRouter, Groq, Together AI, or anything that speaks HTTP.
## License
MIT
