# Workstream [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/ahmad-codex/workstream-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/workstream

## Description
Shared task ledger for AI agents and humans: atomic claims, state machine, GitHub and Slack sync

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "workstream": {
    "url": "http://localhost:8080/demo-insecure-token/mcp"
  }
}
```

## Documentation

## What Workstream MCP server does

The Workstream MCP server acts as a shared system of record for work performed by agents and humans. It stores projects, plans, tasks, claims, findings, fix attempts, and verdicts in Postgres. The supplied plan profiles cover development work, with implement and review stages, and audit work, with find, verify, fix, and re-verify stages.

Task ownership uses short-lived claims. A database transaction locks available work while a task is claimed, so concurrent agents do not receive the same item. Claims can be refreshed and expire when they are not maintained, returning work to the available pool. State changes are checked against the selected plan type's state graph, including permitted roles, transitions, retry limits, and claim lifetimes.

## How it works

Clients send JSON-RPC 2.0 MCP requests over HTTP to `/\u003ctoken\u003e/mcp`. The token identifies the user, so the endpoint does not require an additional authentication header. The API records a state change, its event entry, and any external synchronization work in one database transaction. Event and verdict records are protected from later updates and deletion.

GitHub and Slack work is handled asynchronously. GitHub Projects V2 synchronization can represent tasks as issues or draft items, map statuses to board columns, and add a milestone for audit plans. Signed GitHub webhooks can bring board moves back into the service. Slack notifications use project channels, task threads, Block Kit messages, agent-role personas, and signed interactive actions. Background workers retry queued delivery, so an external service outage does not block the core task operation.

An optional audit dispatcher queues repository audit runs for a sidecar that clones a repository and starts the project's audit orchestrator in a tmux session with Claude Code.

## Setup and configuration

The quick start requires Docker. The included compose configuration starts Postgres and the API, applies SQL migrations, and leaves GitHub, Slack, and the audit dispatcher disabled. Operators create users through the admin API; the response provides the user's MCP URL once. Administrative users can call setup operations such as creating projects, plans, and tasks.

A published demo image can run the API and database on port 8080 with seeded data. Its public demo token has administrator rights, so the port should remain bound to `127.0.0.1`; demo data is removed when the container stops. For a persistent local setup, use the quick-start compose file and stop it with Docker Compose when finished.

The repository also supplies an administrative CLI and `/admin/*` endpoints protected by a static bearer token. GitHub synchronization requires a GitHub App, and Slack synchronization requires Slack configuration including verification of signed requests. The README excerpt does not specify the corresponding environment variable names.

## Tools and capabilities

The Workstream MCP server exposes MCP operations for managing projects and plans, creating and coordinating tasks, claiming work, submitting results, and recording verdicts. Administrative setup operations include project and plan creation. The service also provides a stuck-work report written hourly, counting expired claims, stale findings, and idle plans.

The state graph is stored as JSONB in each plan type, allowing role rules, status transitions, retry caps, lease durations, and board mappings to be data-driven. When a requested transition is invalid, the response identifies the error and reports permitted next states so a calling agent can adjust its action.

## Limitations and notes

The quick-start deployment does not enable GitHub, Slack, or audit dispatch automatically. Those features require their respective external services and worker configuration. The demo token is intentionally insecure and is rejected when demo mode is disabled.

The system is centered on an HTTP MCP endpoint rather than a native local stdio process. Claude Code and Claude Desktop require client-specific connection steps in the documentation, while Cursor is shown in the architecture as a client. Claims depend on expiry and refresh behavior, so agents must maintain a claim while working. External board and notification updates are queued and retried rather than applied synchronously.

_Full upstream README: https://allmcps.com/mcp/workstream/readme_