MCP Orchestrator

A sophisticated Model Context Protocol (MCP) server that orchestrates external AI models (Gemini 2.5 Pro and O3) to provide additional perspectives and insights when using Claude. The orchestrator exclusively uses external models since users are already interacting with Claude directly.

Architecture Overview

When you interact with Claude, this MCP server provides tools to consult external models for additional perspectives:

Gemini 2.5 Pro (via OpenRouter): Alternative analysis and perspectives
O3 (via OpenAI): Architectural and system design insights

Note: The orchestrator does NOT use Claude models since you're already talking to Claude. It exclusively orchestrates external models to enhance your Claude experience.

Features

External Model Enhancement: Get perspectives from Gemini 2.5 Pro and O3 to supplement Claude's responses
Network Bridges: REST API (port 5050) and WebSocket (port 8765) for integration with any application
Advanced Reasoning Strategies: External enhancement and multi-model council approaches
MCP-Compliant: Full adherence to Model Context Protocol standards
Secure by Design: Non-root execution, encrypted storage, API key protection
Docker Support: Production-ready containerization with health checks
Cost Controls: Built-in request and daily spending limits
Bug-Free: All known issues fixed including ResponseSynthesizer and lifecycle management

Quick Start

1. Clone and Configure

git clone https://github.com/gramanoid/mcp_orchestrator
cd mcp_orchestrator

# Create .env file with your API keys
cat > .env << EOF
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
EOF

2. Deploy with Docker

# Deploy the service
./scripts/deploy.sh

# Check status
./scripts/deploy.sh status

# View logs
./scripts/deploy.sh logs

3. Start Network Services (Optional)

# Start REST API and WebSocket bridges for network access
./start_network_services.sh

# Test REST API
curl -X POST http://localhost:5050/mcp/get_orchestrator_status

# Test WebSocket (see examples/integration_example.py)

4. Use with MCP Clients

The orchestrator exposes 13 MCP tools that allow Claude to get external perspectives:

orchestrate_task: Get external model perspectives on any task
analyze_task: Analyze task complexity with external models
query_specific_model: Query Gemini 2.5 Pro or O3 directly
code_review: Get external code review perspectives
think_deeper: Request deeper analysis from external models
multi_model_review: Get multiple external perspectives
comparative_analysis: Compare solutions using external models
And more tools for specific use cases

Architecture

┌──────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│   User   │────▶│   Claude    │────▶│MCP Orchestra │────▶│External Models│
└──────────┘     │   (You)     │     │   tor        │     │Gemini 2.5 Pro│
                 └─────────────┘     └──────────────┘     │     O3       │
                        │                    ▲              └──────────────┘
                        │                    │
                        └────────────────────┘
                         MCP Tools Usage

The flow:

User asks Claude a question
Claude responds directly (primary interaction)
Claude can optionally use MCP tools to get external perspectives
MCP Orchestrator queries ONLY external models (Gemini 2.5 Pro and/or O3)
External insights are integrated into Claude's response

Configuration

Environment Variables

Variable	Description	Default
`OPENROUTER_API_KEY`	Your OpenRouter API key (for Gemini 2.5 Pro)	Required
`OPENAI_API_KEY`	Your OpenAI API key (for O3)	Required
`MCP_LOG_LEVEL`	Logging level	INFO
`MCP_MAX_COST_PER_REQUEST`	Max cost per request ($)	5.0
`MCP_DAILY_LIMIT`	Daily spending limit ($)	100.0

Strategy Configuration

Edit config/config.yaml to customize:

models:
  gemini_pro:
    provider: openrouter
    model_id: google/gemini-2.5-pro-preview
    max_tokens: 32768
    temperature: 0.7
    
  o3_architect:
    provider: openai
    model_id: o3
    max_tokens: 16384
    temperature: 0.8

strategies:
  external_enhancement:
    models:
      - gemini_pro
      - o3_architect
    
  max_quality_council:
    models:
      - gemini_pro
      - o3_architect
    require_consensus: true

Integration Options

REST API

import requests

response = requests.post('http://localhost:5050/mcp/orchestrate_task', 
    json={
        "description": "Analyze this architecture decision",
        "strategy": "external_enhancement"
    }
)
print(response.json()['result'])

WebSocket

const ws = new WebSocket('ws://localhost:8765');
ws.send(JSON.stringify({
    method: 'query_specific_model',
    params: {
        model: 'gemini_pro',
        description: 'What are React best practices?'
    }
}));

See INTEGRATION_EXAMPLES.md for more examples in various languages.

Development

Local Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/

# Run locally
python -m src.mcp_server

Testing with Client

# See scripts/mcp-client.py for example usage
python scripts/mcp-client.py

Security

Runs as non-root user in containers
Read-only filesystem with specific writable volumes
Encrypted credential storage
No capabilities beyond essentials
Resource limits enforced

Monitoring

JSON structured logging
Health checks every 30s
Log rotation (3 files, 10MB each)
Cost tracking and limits

Troubleshooting

Container won't start

# Check logs
docker-compose logs

# Verify environment
docker-compose config

API errors

Verify API key in .env
Check rate limits and quotas
Review logs for specific errors

Memory issues

Adjust mem_limit in docker-compose.yml
Monitor with docker stats

License

MIT License - see LICENSE file for details

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A sophisticated server that coordinates multiple LLMs (Claude, Gemini, etc.) using the Model Context Protocol to enhance reasoning capabilities through strategies like progressive deep dive and consensus-based approaches.

Related MCP Servers

Toolkit MCP Server
cyanheads
A
security
A
license
A
quality
A Model Context Protocol server that provides LLM Agents with a comprehensive toolset for IP geolocation, network diagnostics, system monitoring, cryptographic operations, and QR code generation.
Last updated -
16
3
4
TypeScript
Apache 2.0
MCP Database Server
manpreet2000
-
security
A
license
-
quality
A Model Context Protocol server that enables LLMs to interact with databases (currently MongoDB) through natural language, supporting operations like querying, inserting, deleting documents, and running aggregation pipelines.
Last updated -
TypeScript
MIT License
OpenRouter Agents MCP Server
wheattoast11
-
security
F
license
-
quality
A Model Context Protocol server that enables conversational LLMs to delegate complex research tasks to specialized AI agents powered by various OpenRouter models, coordinated by a Claude orchestrator.
Last updated -
10
JavaScript
Multi LLM Cross-Check MCP Server
lior-ps
-
security
A
license
-
quality
A Model Control Protocol server that integrates with Claude Desktop to enable simultaneous querying and cross-checking of responses from multiple LLM providers including OpenAI, Anthropic, Perplexity AI, and Google Gemini.
Last updated -
7
Python
MIT License

View all related MCP servers

MCP Orchestrator