MDPlanner Setup

MDPlanner is the single source of truth for tasks, notes, decisions, and
progress. It runs in a container and exposes an MCP endpoint that Claude connects
to.

Container Setup

The compose.yml and .env.example are at the cerveau.dev root:

cd cerveau.dev
cp .env.example .env

Edit .env:

MDPLANNER_MCP_TOKEN=replace-with-a-random-secret
MDPLANNER_BRAINS_CONFIG=/cerveau/_configs_/brains.json  # enables Brain Manager UI
MDPLANNER_CACHE=1              # enables SQLite FTS5 full-text search
MDPLANNER_BACKUP_INTERVAL=24   # daily backups

MDPLANNER_BRAINS_CONFIG points to brains.json inside the container.
The compose.yml mounts cerveau.dev/ at /cerveau and ~/.claude at
/root/.claude, so the path above works out of the box.

Generate a token:

openssl rand -hex 32

Initialize the Data Directory

Before starting the container for the first time, initialize the data directory:

podman run -it --rm -v ./data:/data ghcr.io/studiowebux/mdplanner:latest init /data

This creates the required folder structure and default files inside ./data.

Generate the Encryption Secret

MDPlanner encrypts sensitive values (GitHub and Cloudflare tokens). Generate a
secret key and add it to .env:

podman run -it --rm ghcr.io/studiowebux/mdplanner:latest keygen-secret

Copy the output and add it to .env:

MDPLANNER_SECRET_KEY=<output from keygen-secret>

Without init the server will fail to start. Without MDPLANNER_SECRET_KEY
tokens are stored in clear text — set it to enable encryption at rest.

Start:

podman compose up -d

Verify:

curl -s http://localhost:8003/health

Open http://localhost:8003 to confirm the UI loads.

Connect the Brain

Run this from inside your brain directory:

cd cerveau.dev/_brains_/myapp-brain

claude mcp add --transport http mdplanner \
  http://localhost:8003/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"

Replace YOUR_TOKEN_HERE with the value from .env.

Verify:

claude mcp list
# mdplanner  http  http://localhost:8003/mcp

Session Workflow

Claude uses MDPlanner throughout every session:

Boot

• Calls get_context_pack — single MCP call returning active milestone,
  in-progress tasks, top todo tasks, most recent progress note, and decision
  and architecture note titles
• Checks git state: current branch, recent commits, open PRs

Work

• Creates/updates task comments as work progresses
• Moves tasks to Pending Review after commit (owner moves to Done after verification)

Write Back

• Records decisions as MDPlanner notes
• Logs bugs discovered during work
• Updates architecture notes when structure changes

Close

• Writes a progress note (required by stop-progress-check hook)
• Leaves unfinished tasks In Progress (Boot resumes them next session)

Hard Rules

Rule	Description
Ticket before work	No code changes without an MDPlanner task
One task at a time	Only one task in In Progress
Never mark complete	Only the human sets completed: true
Never edit decisions	Supersede decision notes; never modify them

Self-Hosting

MDPlanner is open source: https://github.com/studiowebux/mdplanner

The container image is ghcr.io/studiowebux/mdplanner:latest. Data persists in
the ./data volume.

For the full list of environment variables, see the MDPlanner README.