MCP Handoff Server

Manages AI agent handoffs with structured documentation and seamless task transitions.

AModel Context Protocol (MCP) serverthat helps AI agents hand off work to each other with structured documentation and progress tracking.

When AI agents need to pass work between each other, this server provides:

- 📝 Structured handoff documentswith templates
- 🔄 Progress trackingfrom start to completion
- 📁 Automatic organizationof active and archived handoffs
- 🔍 Easy searchingand filtering of past work

Just run it with npx - no installation needed:

# Start in MCP mode (for MCP clients) npx -y mcp-handoff-server # Start HTTP server (for testing/direct API access) npx -y mcp-handoff-server --mode http

That's it! The server automatically creates all needed folders and templates.

{ "mcpServers": { "handoff": { "command": "npx", "args": [ "-y", "mcp-handoff-server" ] } } }

# Start server npx -y mcp-handoff-server --mode http # Test it works curl http://localhost:3001/health

The server provides these MCP tools for AI agents:

graph LR A[📝 create_handoff] --> B[📖 read_handoff] B --> C[🔄 update_handoff] C --> D[✅ complete_handoff] D --> E[📦 archive_handoff] F[📋 list_handoffs] --> B style A fill:#e1f5fe style C fill:#f3e5f5 style D fill:#e8f5e8 style E fill:#fff3e0 style F fill:#fce4ec

- create_handoff- Start a new handoff document
- read_handoff- Read an existing handoff
- update_handoff- Add progress updates
- complete_handoff- Mark work as finished
- archive_handoff- Move completed work to archive
- list_handoffs- Find and filter handoffs

# Start the server npx -y mcp-handoff-server --mode http # Create a new handoff curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "create_handoff", "params": { "type": "quick", "initialData": { "date": "2025-06-30", "time": "14:30 UTC", "currentState": { "workingOn": "Building user login", "status": "50% complete", "nextStep": "Add password validation" }, "environmentStatus": { "details": { "Server": "✅", "Database": "✅" } } } } }'

npx -y mcp-handoff-server [options] Options: --mode <mode> 'mcp' or 'http' (default: mcp) --port <port> HTTP port (default: 3001) --handoff-root <dir> Storage directory (default: ./handoff-system) --help Show help --version Show version

- Createa handoff when starting work
- Updateprogress as you work
- Completewhen finished
- Archivefor future reference

graph TD A[🤖 Agent Starts Work] --> B{New Work?} B -->|Yes| C[📝 create_handoff] B -->|No| D[📖 read_handoff] C --> E[📁 Active Handoff] D --> E E --> F[🔄 update_handoff] F --> G{Work Done?} G -->|No| F G -->|Yes| H[✅ complete_handoff] H --> I[📦 archive_handoff] I --> J[🗄️ Archived] style C fill:#e1f5fe style F fill:#f3e5f5 style H fill:#e8f5e8 style I fill:#fff3e0

The server automatically organizes everything in folders:

- handoff-system/active/- Current work
- handoff-system/archive/- Completed work
- handoff-system/templates/- Document templates

📋 Standard Handoff- For complex work with detailed context⚡ Quick Handoff- For simple updates and brief transitions

- ✅Working- Everything good
- ⚠️Warning- Some issues but not blocked
- ❌Error- Problems that need fixing

# Clone and install git clone <repository-url> cd mcp-handoff-server npm install # Run in development npm run dev # Build for production npm run build

MIT License - feel free to use this in your projects!

- Issues:GitHub Issues
- MCP Protocol:Model Context Protocol Docs

A multi-agent mesh network designed for completing AI tasks in parallel.