AI Tasks MCP Server with Valkey Persistence

Overview

This MCP (Model Context Protocol) server provides a task and plan management backend designed for agentic AI workflows. It exposes a simple MCP interface so AI agents can create, coordinate, prioritize and track tasks inside named plans, while persisting state reliably with Valkey. The server is implemented in Go and uses Valkey (and the Valkey-Glide v2 client) as its durable storage layer, giving you crash-safe task storage and efficient local deployments.

Typical uses include autonomous agents that need to break objectives into plans and tasks, multi-agent coordination where task status and order matter, and human+AI workflows that require persistent notes (Markdown) and auditability of task changes.

Features

• Create, read, update, and delete (CRUD) for plans and tasks
• Task ordering, prioritization and status tracking
• Markdown-formatted notes for plans and tasks
• MCP-compatible server for AI agent integration
• Supports three transport modes: Server-Sent Events (SSE), Streamable HTTP, and STDIO
• Docker container images for quick deployment
• Health endpoint and lightweight API surface
• Built on Valkey for robust local persistence

Installation / Configuration

Prerequisites: Docker and a named Docker volume for Valkey data persistence.

Create a Valkey volume:

docker volume create valkey-data

Run the container with SSE (recommended):

docker run -d --name valkey-mcp \
  -p 8080:8080 \
  -p 6379:6379 \
  -v valkey-data:/data \
  -e ENABLE_SSE=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Run with Streamable HTTP transport:

docker run -d --name valkey-mcp \
  -p 8080:8080 \
  -p 6379:6379 \
  -v valkey-data:/data \
  -e ENABLE_STREAMABLE_HTTP=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Run with STDIO (for direct process communication, useful when an agent spawns the server):

docker run -i --rm --name valkey-mcp \
  -v valkey-data:/data \
  -e ENABLE_STDIO=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Pull image directly:

docker pull ghcr.io/jbrinkman/valkey-ai-tasks:latest
# or a specific tag
docker pull ghcr.io/jbrinkman/valkey-ai-tasks:1.1.0

Configuration note: for safety the server requires you to explicitly enable a transport; by default all are disabled.

Transport and Endpoints

Transport selection depends on the endpoint you use and content type. Summary:

Health check:

GET /health

Streamable HTTP request examples:

• List functions:

{"method":"list_functions","params":{}}

• Invoke a function:

{"method":"invoke","params":{"function":"create_plan","params":{"name":"My Plan","application":"app1"}}}

Available Resources

• Source code and releases: https://github.com/jbrinkman/valkey-ai-tasks
• Container images published to GitHub Container Registry: ghcr.io/jbrinkman/valkey-ai-tasks
• Built with: Go + Valkey (Valkey-Glide v2) + MCP

Core Functions (high level)

Plan management:

• create_plan, get_plan, list_plans, list_plans_by_application, update_plan, delete_plan
• update_plan_notes, get_plan_notes

Task management:

• create_task, get_task, list_tasks_by_plan, list_tasks_by_status, update_task, delete_task
• reorder_task (change position within plan), update_task_notes, get_task_notes

Each function is exposed via the MCP interface on the chosen transport.

Use Cases

1. Agent task orchestration

   • An LLM agent receives a high-level objective, calls create_plan, then iteratively create_task and reorder_task as subtasks are discovered and prioritized. Task states (todo, in-progress, done) are updated as work proceeds.

2. Multi-agent coordination

   • Multiple agents read tasks via list_tasks_by_plan and acquire or assign tasks. Persistent Valkey storage ensures task state survives crashes and restarts.

3. Human-in-the-loop workflows

   • A user-facing UI reads plan notes and task notes (Markdown) and can update content. Agents keep working on the underlying structured tasks while notes provide human context.

4. Debugging and audit

   • Use the get_plan/get_task endpoints and the history of task reorders/updates to audit agent actions and reproduce decision steps.

Getting Started Tips

• Start with SSE for interactive agent development and debugging (browser-friendly stream).
• Use Streamable HTTP for headless or programmatic integrations that expect JSON request/response.
• Use STDIO when an orchestrator process needs to embed the MCP server as a subprocess.
• Keep a persistent Docker volume for Valkey data to avoid losing tasks between container restarts.

For full API details and examples, see the repository: https://github.com/jbrinkman/valkey-ai-tasks