HydraMCP

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

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:

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

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.

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.

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.

Local Models

Install Ollama, pull a model, done. Auto-detected.

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)

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

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:

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