QualeQuest Orchestration MCP Server

Model Context Protocol server for autonomous AI agent coordination

Coordinate AI agents across Claude Desktop, Claude Code, and custom platforms with 30+ built-in tools for task management, validation, context synchronization, and inter-agent communication.

Installation

npm install @qualequest/orchestration-mcp

Quick Start

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "qualequest-orchestration": {
      "command": "npx",
      "args": ["-y", "@qualequest/orchestration-mcp"],
      "env": {
        "QUALEQUEST_API_KEY": "your-api-key"
      }
    }
  }
}

Get your API key at intelligence.qualequest.com

Features

• ⭐ V5.1 Intelligence Layer - NEW flagship feature with 85% token reduction
• 38 Coordination Tools - Complete agent orchestration toolkit (updated from 37)
• Task Management - Create, assign, track, and validate tasks
• Evidence System - File-verified validation evidence
• Context Sync - Save and retrieve agent context snapshots
• Inter-Agent Messaging - Priority-based communication with threading
• ML Predictions - Task duration, agent matching, success probability (PRO)
• Pattern Learning - Learn from disasters and optimize workflows (PRO)

⭐ V5.1 Intelligence Layer

New in V5.1: Intelligent session initialization that replaces 3 manual calls with 1 smart call.

intelligent_session_init

The flagship feature of V5.1 delivers 85% token reduction (5,500 → 800 tokens) with role-aware, actionable context.

What it does:

• Automatically retrieves relevant context from your last sessions
• Filters and prioritizes messages by importance
• Detects pending work and suggests next actions
• Identifies anomalies (stuck tasks, urgent messages)
• Optimizes output based on your role (PM, Engineer, Designer)

Before (3 calls, ~5,500 tokens):

retrieve_context(agent_id, query_type, target_agent_id)  // ~2,500 tokens
get_agent_messages(to_agent_id, unread_only)             // ~2,000 tokens
acknowledge_onboarding(agent_id, ...)                     // ~1,000 tokens

After (1 call, ~800 tokens):

intelligent_session_init(
  agent_id="OPUS-001",
  session_purpose="Review V5.1 launch status"
)

Benefits:

• 📉 85% fewer tokens - Massive cost savings on every session start
• ⚡ 40ms average latency - Faster than sequential calls
• 🎯 Role-optimized - Output tailored to PM, Engineer, or Designer
• 🔍 Proactive insights - Detects stuck tasks and urgent issues automatically
• 🚀 Better UX - One call instead of three

Performance:

• Average latency: 40ms (tested: OPUS-001, BE-001, DESIGN-001)
• Target budget: <200ms
• 100% test pass rate across all agent types

See docs/INTELLIGENT-SESSION-GUIDE.md for usage guide and best practices.

Available Tools

Core Coordination

• deploy_agent - Deploy agents with context packages
• update_agent_status - Update agent status (PENDING, ACTIVE, PAUSED, BLOCKED, COMPLETE)
• send_agent_message - Send messages between agents
• get_agent_messages - Retrieve messages for an agent

Task Management

• create_task - Create new tasks (required before starting work)
• start_task - Start working on a task
• query_tasks - Query tasks with filters (status, agent, priority)
• claim_task_completion - Request to mark task complete

Validation & Evidence

• submit_validation_evidence - Submit evidence with file verification
• check_validation_status - Check if task meets validation requirements

Context Management

• save_context_snapshot - Save agent context for future retrieval
• retrieve_context - Retrieve previous context snapshots
• acknowledge_onboarding - Required protocol acknowledgment before work

Decision Intelligence (PRO)

• submit_decision_for_validation - Submit major decisions for AI validation
• query_decision_history - Query past decisions to learn from history
• get_strategic_recommendations - Get AI-powered strategic suggestions

ML Predictions (PRO)

• predict_task_duration - Predict task completion time
• suggest_optimal_agent - Recommend best agent for a task
• predict_success_probability - Predict task success likelihood

Advanced Messaging

• send_priority_message - Send message with priority level
• broadcast_to_agents - Send message to multiple agents

Learning & Optimization (PRO)

• learn_from_disaster - Log disasters for pattern learning
• analyze_patterns - Discover patterns in coordination events
• generate_recommendations - Generate actionable recommendations

Pricing

| Tier | Price | Features | |------|-------|----------| | FREE | $0 | Basic coordination, 5 tools, local storage | | PRO | $29/mo | All 30+ tools, ML predictions, cloud sync | | ENTERPRISE | Custom | Dedicated instance, unlimited agents, SLA |

Requirements

• Node.js >= 18.0.0
• Claude Desktop, Claude Code, or MCP-compatible client
• QualeQuest API key (get at intelligence.qualequest.com)

Development

Local Development Setup

# Clone repository
git clone https://github.com/qualequest/orchestration-mcp.git
cd orchestration-mcp

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Run tests
npm test

Testing the Server Locally

Option 1: Test via Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "qualequest-local": {
      "command": "node",
      "args": ["C:/path/to/qualequest-mcp-server/server.js"],
      "env": {
        "QUALEQUEST_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop and verify tools are available.

Option 2: Test via MCP Inspector

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector node server.js

This opens a web interface to test all MCP tools interactively.

Environment Variables

• QUALEQUEST_API_KEY - Your API key from intelligence.qualequest.com (required)
• DB_PATH - Custom database path (optional, defaults to ~/.qualequest/coordination.db)
• CONFIG_PATH - Custom config path (optional, defaults to ~/.qualequest/config.json)

Graceful Degradation

The server includes intelligent fallbacks for ML predictions when the ML server is unavailable:

• predict_task_duration - Falls back to rule-based estimation using task type and complexity
• suggest_optimal_agent - Falls back to keyword-based routing with pattern matching
• predict_success_probability - Falls back to conservative probability based on complexity and duration

All fallback responses include:

• Clear explanation of fallback method used
• Helpful recommendations for the user
• Automatic resumption when ML server becomes available

Node.js Version

Minimum required: Node.js 18.0.0

The server automatically checks your Node.js version at startup and provides helpful guidance if an upgrade is needed.

Support

• Documentation: docs.qualequest.com
• Issues: GitHub Issues
• Email: [email protected]

License

MIT License - see LICENSE file

Built by QualeQuest | Powered by Model Context Protocol