An interactive Tic Tac Toe game where three AI agents work together using CrewAI as the agent framework and MCP (Multi-Context Protocol) for distributed communication. This project showcases how multiple LLMs can collaborate through structured communication protocols - each agent runs as both a CrewAI Agent and an MCP Server.

• 🎮 Game: Interactive Tic Tac Toe vs AI team
• 🤖 AI Team: Three MCP agents (Scout, Strategist, Executor) - each a CrewAI Agent + MCP Server
• 🔄 Hot-Swappable Models: Switch LLMs mid-game without restart via MCP protocol
• 📊 Real-time Analytics: MCP protocol monitoring and performance analytics
• 🎨 Modern UI: Streamlit dashboard with live updates
• 🌐 Distributed: Each agent runs as independent MCP server for scalable deployment

Get started in 5 minutes!

This project supports multiple deployment modes and agent frameworks:

1. 🚀 Simple Mode (Fastest) - Direct LLM calls, < 1 second per move, perfect for Tic Tac Toe
2. ⚡ Optimized Mode (Recommended) - Shared resources, LangChain direct calls, < 1 second per move
3. 🏠 Local Mode (Default) - All agents run in the same Python process with direct method calls
4. 🌐 Distributed Mode - Agents run as separate processes communicating via HTTP/JSON-RPC (true MCP transport)

# Simple mode - fastest and most reliable for Tic Tac Toe
git clone https://github.com/arun-gupta/mcp-multiplayer-game.git
cd mcp-multiplayer-game
chmod +x quickstart.sh
./quickstart.sh --simple    # or --s for short

Benefits:

• ⚡ < 1 second per move - 8-19x faster than complex mode
• 🔧 10x simpler - No CrewAI/MCP overhead
• 🛠️ 5x easier maintenance - Direct LLM calls only
• 🎯 Perfect for Tic Tac Toe - No over-engineering

Access the game: http://localhost:8501 API Documentation: http://localhost:8000/docs

# Optimized mode - best balance of speed and structure
git clone https://github.com/arun-gupta/mcp-multiplayer-game.git
cd mcp-multiplayer-game
chmod +x quickstart.sh
./quickstart.sh --optimized    # or --o for short

Benefits:

• ⚡ < 1 second per move - Shared resources, no MCP servers
• 🔧 LangChain direct calls - No CrewAI overhead
• 🛠️ Shared Ollama connection - Memory efficient
• 🎯 Pre-created tasks - No runtime creation overhead
• 🚀 Best balance - Speed + structure

Access the game: http://localhost:8501 API Documentation: http://localhost:8000/docs

# Clone and setup MCP hybrid architecture automatically
git clone https://github.com/arun-gupta/mcp-multiplayer-game.git
cd mcp-multiplayer-game
chmod +x quickstart.sh
./quickstart.sh

Access the game: http://localhost:8501 API Documentation: http://localhost:8000/docs

Choose between different agent frameworks:

# Simple mode (fastest, recommended for Tic Tac Toe)
./quickstart.sh --simple    # or --s for short

# Optimized mode (best balance, recommended)
./quickstart.sh --optimized    # or --o for short

# LangChain agents (faster than CrewAI)
./quickstart.sh --langchain

# CrewAI agents with MCP protocol (complex, full coordination)
./quickstart.sh --crewai

Framework Comparison:

• Simple: Direct LLM calls, < 1 second per move, perfect for Tic Tac Toe
• Optimized: LangChain with shared resources, < 1 second per move, best balance
• LangChain: Direct LLM calls, faster than CrewAI, good balance
• CrewAI: Full agent coordination with MCP protocol, most complex

For true MCP protocol transport between agents:

# Clone and setup
git clone https://github.com/arun-gupta/mcp-multiplayer-game.git
cd mcp-multiplayer-game
chmod +x quickstart.sh
./quickstart.sh -d  # or --d, --dist, --distributed all work

This starts:

• Scout Agent on port 3001
• Strategist Agent on port 3002
• Executor Agent on port 3003
• Main API Server on port 8000 (with --distributed flag)

Access the game: http://localhost:8501 API Documentation: http://localhost:8000/docs

# Clone and setup MCP hybrid architecture
git clone https://github.com/arun-gupta/mcp-multiplayer-game.git
cd mcp-multiplayer-game

# Install dependencies
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Install Ollama models (optional)
ollama pull llama2:7b
ollama pull mistral

# Optimize Ollama for instant AI responses (recommended)
OLLAMA_KEEP_ALIVE=-1 ollama run llama3.2:1b

# Start MCP API server
python main.py &

# Start Streamlit UI (in another terminal)
python run_streamlit.py

The quickstart.sh script automatically:

• ✅ Process cleanup - Kills existing processes on ports 8000/8501
• ✅ Environment setup - Creates venv and installs dependencies
• ✅ Python version checking - Validates Python 3.11+
• ✅ Dependency installation - Installs all requirements with Python 3.13 compatibility
• ✅ Ollama model setup - Optional local model installation
• ✅ File validation - Checks for all required files
• ✅ Application startup - Starts both backend and frontend services
• ✅ Error handling - Comprehensive error checking and colored output

# Full setup and launch (default)
./quickstart.sh

# Launch only (skip setup, venv must exist)
./quickstart.sh --skip-setup

# Setup and launch without cleanup
./quickstart.sh --skip-cleanup

# Show help
./quickstart.sh --help

📖 Complete Setup Guide - Detailed instructions and troubleshooting

• 📋 Quick Start Guide - Complete setup and troubleshooting
• 🎨 Streamlit UI Guide - Frontend features and customization

• 🏗️ Architecture - System architecture and design
• 📡 API Reference - Complete API documentation and examples
• 🎮 User Guide - Game experience and setup instructions
• 🚀 Features - Detailed feature explanations and capabilities
• 🛠️ Development - Development workflow and contribution guidelines

• 🔍 MCP Query Guide - All methods to query MCP servers (Recommended starting point)
• 🌐 REST API Guide - Detailed REST/HTTP API reference with Python examples
• 📋 MCP Protocol - Complete MCP protocol implementation details

To use the AI agents, you'll need API keys for the LLM providers. See the User Guide for detailed setup instructions.

The application uses config.json for all configuration settings. Copy the example file and customize as needed:

cp config.example.json config.json

{
  "mcp": {
    "ports": {
      "scout": 3001,       // MCP server port for Scout agent
      "strategist": 3002,  // MCP server port for Strategist agent
      "executor": 3003     // MCP server port for Executor agent
    },
    "host": "localhost",
    "protocol": "http"
  },
  "api": {
    "host": "0.0.0.0",
    "port": 8000           // FastAPI server port
  },
  "streamlit": {
    "host": "0.0.0.0",
    "port": 8501           // Streamlit UI port
  },
  "models": {
    "default": "gpt-5-mini",  // Default model for all agents
    "fallback": ["gpt-4", "claude-3-sonnet", "llama3.2:3b"]
  },
  "performance": {
    "mcp_coordination_timeout": 15,     // Timeout for MCP coordination (seconds)
    "agent_execution_timeout": 8,       // Timeout for individual agent tasks (seconds)
    "enable_metrics": true              // Enable/disable performance metrics
  }
}

Note: config.json is gitignored for security. Always use config.example.json as a template.

The system uses MCP (Multi-Context Protocol) for distributed communication between CrewAI agents. Each agent runs as both a CrewAI Agent and an MCP Server, enabling modular, scalable deployment.

• 🤖 MCP Agents: Scout, Strategist, Executor (Ports 3001-3003)
• 🌐 FastAPI Server: Main application server (Port 8000)
• 🎨 Streamlit UI: Interactive game interface (Port 8501)
• 📡 MCP Coordinator: Orchestrates agent communication with streamlined real-time coordination

For optimal real-time gaming performance, the system uses a lightweight MCP coordination approach:

• ⚡ Fast Response Times: Sub-second AI moves via optimized agent communication
• 🎯 Strategic Logic: Direct blocking/winning move detection for immediate threats
• 📊 Real-Time Metrics: Accurate request tracking with microsecond precision
• 🔄 Auto-AI Moves: Automatic AI turn triggering via dedicated /ai-move endpoint
• 🎮 Seamless UX: No delays or timeouts during gameplay

Main application server that coordinates everything

Individual agent MCP servers exposing tools for direct communication

📝 MCP Tools: These are tools (actions/operations) that agents can perform, representing capabilities like "analyze", "create", "execute".

The Scout agent analyzes the game board and identifies patterns, threats, and opportunities.

The Strategist agent creates game plans and recommends optimal moves.

The Executor agent validates and executes moves on the game board.

All agents share these standard MCP capabilities:

📚 Complete Architecture & API Documentation - Detailed architecture diagrams, communication flows, and complete API reference.

The Streamlit dashboard provides comprehensive monitoring with real-time analytics, performance tracking, and MCP protocol logging.

📚 Features Documentation - Detailed monitoring capabilities, analytics, and feature status.

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.