mcp-handoff

The MCP Handoff Server provides a structured way for AI agents to transfer work between one another with templates, progress tracking, and easy organization. It exposes a set of MCP tools for creating, reading, updating, completing, archiving, and listing handoffs, all stored in a dedicated folder structure. Agents can interact with the server through the MCP protocol over JSON-RPC or via a lightweight HTTP interface for testing and quick experiments. You can either run the server in MCP mode to be consumed by MCP clients, or run it with the HTTP option to test endpoints directly.

To start using it, you typically run the server with npx -y mcp-handoff-server and then configure your MCP client to point at the server under the server name handoff. The available tooling includes create_handoff to begin a new handoff, read_handoff to fetch details of an existing handoff, update_handoff to append progress, complete_handoff to mark work done, archive_handoff to move finished work to history, and list_handoffs to search and filter existing handoffs. This enables structured handoffs, progress visibility, and automatic organization into active and archived folders.

Prerequisites:

• Node.js and npm installed (or use npx if you have npm installed).
• Basic command-line familiarity.

Installation steps:

1. No global install is required for this server; you can start it directly via npx. Ensure you are in a project directory or any location with network access.

2. Run the server in MCP mode (default):

   npm install -g npm # ensure npm is up to date (optional but recommended) npx -y mcp-handoff-server

3. To expose an HTTP API for testing, run:

   npx -y mcp-handoff-server --mode http

4. Optional: configure a local development environment or add your own scripts to start the server as part of a larger workflow.

Notes and tips:

• The server automatically creates the necessary folders (handoff-system/active, handoff-system/archive, handoff-system/templates) on first run. Ensure there are no permission issues writing to the working directory.
• Use the HTTP mode for quick testing with curl or any HTTP client, then switch back to MCP mode for integration with MCP clients.
• The mcp-handoff-server supports two handoff types: Standard Handoff and Quick Handoff. Choose based on the complexity of the task.
• If you encounter port conflicts, you can override the HTTP port with --port when running in http mode.
• When scripting against the MCP protocol, you typically send JSON-RPC requests to the appropriate endpoints (e.g., create_handoff, read_handoff, update_handoff, complete_handoff, archive_handoff, list_handoffs).
• Ensure your environment adheres to any security or access control requirements for exposing the handoff data in shared environments.