mcp-task-server

A generic, client-agnostic MCP server for managing tasks, checkpoints, and agent handoffs. Communicates via STDIO (JSON-RPC 2.0) or HTTP/SSE and works with any MCP-capable client.

Use case: Agent A hits its context limit or needs to hand off work. It saves a checkpoint with all relevant state. Agent B (same or different AI system) picks up the task and continues exactly where A left off — with full context, completed steps, remaining steps, and a resume prompt.

Agent A  →  save_checkpoint()  →  handoff_task()  →  [task-server]
                                                            ↓
Agent B  ←  get_task() ←────────────────────────────────────

Features

Task management — create, read, update tasks with full lifecycle tracking
Checkpoint system — agents save progress (completed steps, remaining steps, test results)
Handoff — transfer tasks between any agents with ownership tracking
Artifacts — attach files, diffs, and logs to tasks
Resources — read tasks via task://<id> as MCP resources
Dual transport — STDIO for direct subprocess use, HTTP/SSE for persistent service
SQLite — persistent storage, no external database required
Zero dependencies beyond pydantic

Requirements

Python 3.11+
pydantic >= 2.0

Installation

git clone https://github.com/Mr-Websaint/mcp-task-server.git
cd mcp-task-server

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

STDIO mode (recommended for MCP clients)

python3 server.py

The server reads JSON-RPC messages from stdin and writes responses to stdout. Debug logging goes to stderr:

MCP_DEBUG=1 python3 server.py

HTTP/SSE mode (persistent service)

python3 server.py --http --port 8766

Endpoints:

Endpoint	Description
`GET /health`	Health check → `{"status": "ok"}`
`GET /sse`	SSE stream (MCP SSE transport)
`POST /message?clientId=<id>`	Send JSON-RPC message

Admin CLI (interactive task management)

A bundled admin script lets you inspect and manage the MCP task server directly from the terminal.

python3 /home/websaint/mcp-task-server/admin.py

If you want a shorter command, add this Bash alias for the websaint user:

alias mcptask='python3 /home/websaint/mcp-task-server/admin.py'

After adding the alias, reload your shell configuration:

source ~/.bashrc

The admin CLI provides:

browse tasks in read-only menus
search and filter tasks
open a task detail menu for one task
update status, owners, checkpoints, and handoffs
read task data as JSON or as an MCP resource

Status values can be entered by name or by number (1 to 5) in the menus and direct CLI commands.

MCP Client Configuration

Any client supporting STDIO transport

{
  "mcpServers": {
    "task-handoff": {
      "command": "python3",
      "args": ["/path/to/mcp-task-server/server.py"],
      "env": {
        "MCP_TASK_DB_PATH": "/path/to/tasks.db",
        "MCP_TASK_ARTIFACTS_DIR": "/path/to/artifacts"
      }
    }
  }
}

Claude Code (`~/.claude/settings.json`)

{
  "mcpServers": {
    "task-handoff": {
      "command": "/path/to/mcp-task-server/.venv/bin/python3",
      "args": ["/path/to/mcp-task-server/server.py"]
    }
  }
}

Hermes Agent (`~/.hermes/config.yaml`)

mcp_servers:
  task_handoff:
    command: "/path/to/mcp-task-server/.venv/bin/python3"
    args: ["/path/to/mcp-task-server/server.py"]
    env:
      MCP_TASK_DB_PATH: "/path/to/mcp-task-server/tasks.db"
      MCP_TASK_ARTIFACTS_DIR: "/path/to/mcp-task-server/artifacts"
    timeout: 60
    connect_timeout: 30

HTTP client (SSE transport)

mcp_servers:
  task_handoff:
    url: "http://127.0.0.1:8766/sse"

Environment Variables

Variable	Default	Description
`MCP_TASK_DB_PATH`	`./tasks.db`	Path to the SQLite database
`MCP_TASK_ARTIFACTS_DIR`	`./artifacts/`	Directory for artifacts
`MCP_TASK_BASE_DIR`	Directory of `server.py`	Base path
`MCP_TASK_PORT`	`8766`	HTTP port (overridden by `--port`)
`MCP_DEBUG`	(unset)	Enable debug logging when set

Available Tools

Tool	Description
`create_task`	Create a new task
`get_task`	Read a task by ID
`save_checkpoint`	Save agent progress (steps, tests, resume prompt)
`handoff_task`	Transfer task from one agent to another
`mark_exhausted`	Mark task as "agent cannot proceed"
`attach_artifact`	Attach a file, diff, or log to a task
`list_tasks`	List tasks with optional filters
`update_task`	Update a task with partial field updates
`search_tasks`	Search tasks by text in the goal and title fields

MCP Resource

URI: task://<task_id>
Type: application/json
Returns the full task as JSON (read-only)

Task Lifecycle

open → in_progress → handoff_ready → in_progress → done
                   ↘ agent_exhausted

Example Workflow (JSON-RPC)

1. Initialize

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false}},"serverInfo":{"name":"mcp-task-server","version":"1.0.0"}}}

→ {"jsonrpc":"2.0","method":"notifications/initialized"}

2. Create task

→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_task","arguments":{"task_id":"task-001","title":"Fix login bug","goal":"Resolve auth error on /login","repo_path":"/home/dev/myapp"}}}

3. Save checkpoint (Agent A)

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"save_checkpoint","arguments":{"task_id":"task-001","agent":"claude-code","completed_steps":["Reproduced bug","Found root cause in auth/login.py:42"],"remaining_steps":["Implement fix","Write tests"],"resume_prompt":"Fix null check in auth/login.py line 42"}}}

4. Hand off to Agent B

→ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"handoff_task","arguments":{"task_id":"task-001","from_agent":"claude-code","to_agent":"hermes","reason":"Context limit reached, fix not yet implemented"}}}

5. Agent B reads task

→ {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_task","arguments":{"task_id":"task-001"}}}

Or via resource:

→ {"jsonrpc":"2.0","id":6,"method":"resources/read","params":{"uri":"task://task-001"}}

6. Update task (Agent B makes progress)

→ {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"update_task","arguments":{"task_id":"task-001","title":"Fix login bug","goal":"Implementing solution for auth error","status":"in_progress","current_owner":"hermes","completed_steps":["Reproduced bug","Found root cause","Implemented fix"],"remaining_steps":["Write tests","Deploy to staging"]}}}

Running as a systemd Service

A service template is provided in systemd/mcp-task-server.service.template.

# 1. Copy and adapt the template
cp systemd/mcp-task-server.service.template /etc/systemd/system/mcp-task-server.service
# Edit User=, WorkingDirectory=, ExecStart= and Environment= paths

# 2. Enable and start
systemctl daemon-reload
systemctl enable --now mcp-task-server

# 3. Check status
systemctl status mcp-task-server
journalctl -u mcp-task-server -f

Health Check

# Run the bundled health check script
./healthcheck.sh

# Or hit the HTTP endpoint directly (HTTP mode only)
curl http://127.0.0.1:8766/health

The health check verifies: venv, pydantic import, DB write access, artifacts directory, STDIO response, and HTTP service status.

Project Structure

mcp-task-server/
├── admin.py          # Interactive admin CLI for browsing and managing tasks
├── server.py          # Main server (STDIO + HTTP/SSE transport, MCP protocol)
├── config.py          # Configuration via environment variables
├── models.py          # Pydantic data models (Task, Artifact, TestRun, ...)
├── store.py           # SQLite persistence layer
├── healthcheck.sh     # Health check script
├── requirements.txt   # Python dependencies
├── systemd/
│   └── mcp-task-server.service.template  # systemd unit file template
└── artifacts/         # Runtime artifact storage (gitignored)

License

MIT — do whatever you want with it.

Navigation Menu

Repository files navigation

mcp-task-server

Features

Requirements

Installation

Usage

STDIO mode (recommended for MCP clients)

HTTP/SSE mode (persistent service)

Admin CLI (interactive task management)

MCP Client Configuration

Any client supporting STDIO transport

Claude Code (`~/.claude/settings.json`)

Hermes Agent (`~/.hermes/config.yaml`)

HTTP client (SSE transport)

Environment Variables

Available Tools

MCP Resource

Task Lifecycle

Example Workflow (JSON-RPC)

1. Initialize

2. Create task

3. Save checkpoint (Agent A)

4. Hand off to Agent B

5. Agent B reads task

6. Update task (Agent B makes progress)

Running as a systemd Service

Health Check

Project Structure

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
artifacts		artifacts
systemd		systemd
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
admin.py		admin.py
config.py		config.py
healthcheck.sh		healthcheck.sh
models.py		models.py
requirements.txt		requirements.txt
server.py		server.py
store.py		store.py

Latest commit

History

Folders and files

Repository files navigation

mcp-task-server

Features

Requirements

Installation

Usage

STDIO mode (recommended for MCP clients)

HTTP/SSE mode (persistent service)

Admin CLI (interactive task management)

MCP Client Configuration

Any client supporting STDIO transport

Claude Code (~/.claude/settings.json)

Hermes Agent (~/.hermes/config.yaml)

HTTP client (SSE transport)

Environment Variables

Available Tools

MCP Resource

Task Lifecycle

Example Workflow (JSON-RPC)

1. Initialize

2. Create task

3. Save checkpoint (Agent A)

4. Hand off to Agent B

5. Agent B reads task

6. Update task (Agent B makes progress)

Running as a systemd Service

Health Check

Project Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Claude Code (`~/.claude/settings.json`)

Hermes Agent (`~/.hermes/config.yaml`)