MCP Handoff Server

The MCP Handoff Server enables AI agents to pass work between each other with structured handoff documents, progress tracking, and automatic organization. It helps teams keep context, status, and history consistent as tasks move from one agent to another.

How to use

You use the MCP Handoff Server by running it either in MCP mode for agent handoffs or in HTTP mode for direct API access. In MCP mode, agents can create and update handoffs through the provided MCP tools. In HTTP mode, you can interact with the server via REST-like endpoints to create, read, update, complete, and archive handoffs. Use the MCP client configuration to point to the server and start working with handoffs.

Key workflows you will perform include: creating a new handoff when work begins, updating progress as work advances, marking a handoff as complete when finished, and archiving completed work for long-term reference. You can also search and filter active and archived handoffs to find past context quickly.

How to install

Prerequisites you should have installed on your machine: Node.js (and npm or npx). You do not need to install the server globally; you can run it directly with npx.

# Install prerequisites if needed (Node.js provides npm and npx)
node -v
npm -v

# 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

Additional setup notes

The server automatically creates storage folders for active handoffs, archived handoffs, and templates. You can organize work under handoff-system/active, handoff-system/archive, and handoff-system/templates. When you start the HTTP mode, you can test endpoints such as /health to verify the server is running.

Available tools

create_handoff

Start a new handoff document with contextual data and initial state.

read_handoff

Retrieve and view an existing handoff document.

update_handoff

Add progress updates and modify ongoing handoffs.

complete_handoff

Mark the handoff as finished and ready for archival.

archive_handoff

Move completed handoffs into the archive for long-term storage.

list_handoffs

Find and filter handoffs based on status, date, or other criteria.