Workstream MCP server

workstream-mcp

An MCP server that keeps the state of record for work done by AI agents and humans together: plans, tasks, claims, findings, fix attempts and verdicts, stored in Postgres, mirrored to GitHub Projects and Slack.

Try it in 30 seconds

One container with Postgres and the server in demo mode, seeded with a project, an active plan and three tasks:

docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/ahmad-codex/workstream-mcp:demo
claude mcp add --transport http workstream-demo http://localhost:8080/demo-insecure-token/mcp

Then ask Claude to "list the workstream projects and claim the next task on the demo plan". The demo token is public and gives admin rights, so keep the port on 127.0.0.1; the server refuses that token whenever demo mode is off. Data is gone when the container stops.

Set it up with Claude Code

Clone the repo, open Claude Code in it, and paste:

Set up workstream-mcp for me on this machine. Follow the README quick start using the
published Docker image, create an admin user for me, and connect this Claude Code session
to it. Then create a project and a development plan with three sample tasks, activate it,
and claim one task to show it works. When that is done, ask me whether I want GitHub
Projects or Slack sync, and walk me through docs/github-setup.md or docs/slack-setup.md
step by step, telling me exactly what to click and which values to paste back.

Prefer to do it by hand? See the quick start.

Why

A common way to coordinate agent work is a markdown plan in the repo: a checklist the agent reads, edits and commits. That works for one agent in one session. It breaks down when several agents and people work the same plan at once:

• Two agents pick the same item, because nothing stops them.
• An agent dies mid-task and the item stays "in progress" forever.
• Edits to the file race each other, and the history of who did what lives in git diffs.
• The plan does not show up where the team already looks: the project board and Slack.

workstream-mcp replaces the file with a small service. Agents call MCP tools to claim work, submit results and record verdicts. Claims are atomic and expire, transitions are checked against a state graph, every change is written to an append-only event log, and GitHub and Slack are updated from an outbox so an outage on their side never blocks the agents.

Features

What the code does today:

Shortened. The full README is on GitHub.