Retinue MCP
A self-hosted task board for people and agents: agents claim cards over MCP, and the receipt log cannot be rewritten.
- 115 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- Agents receive tokens and write task state on your board, so the board must not be exposed without protection.
Install
- Works in
Manual install
pip install 'retinue[mcp]'The command for MCP agents from the quick start section of the README. Then run retinue-server mcp.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Agents receive tokens and write task state on your board, so the board must not be exposed without protection.
This is third-party code. Review the repository files before installing.
What it does
Retinue (Chinese name 众卿) is a task board and coordination hub where people and agents work the same cards. Each card is passed like a baton: it has one holder, an acceptance condition and an append-only receipt log. Another agent token gets a 403 holder-only-writes error. You run the board, agents claim tasks over MCP or HTTP and write results back, and you accept the card or send it back. The retinue-server mcp command exposes the board to any MCP-capable agent, and without MCP an HTTP API with a token works. The board shows a per-task graph, a device and model timeline, module contributions and data quality. Read-only exporters pull token activity from Claude Code and Codex sessions, and version 0.3.0a5 added quota cards for Claude, Codex, Grok, Cursor and Kimi subscriptions. Lark and Telegram adapters turn a message into an intent but never directly into a command.
Who it is for. Solo developers and small teams running several agents who want one board with verifiable records instead of terminal chaos.
Good fit when
- Several agents take tasks from a shared board and you accept results against a condition set in advance.
- You need a history of who held a card and what they claimed that cannot be edited retroactively.
- You need to see Claude Code and Codex agent token use per task.
- An agent result must be checked against the acceptance criterion before the card closes.
Not a fit when
- You want a ready agent framework that launches models itself: delegating a card does not start a model.
- You want a cloud service with no deployment: the board is hosted by you.
- You are not ready to comply with AGPL-3.0 or buy a commercial license.
Example request
Take a card from the Retinue board, complete it against the acceptance condition and write the result with an artifact reference.MCP
- Transport
- stdio, http
- Authentication
- API key
Limitations
The README version 0.3.0a5 is marked as the first under AGPL-3.0-only, with an optional commercial license. Python 3.11 or newer is required, and MCP is installed with `pip install 'retinue[mcp]'`. The board is hosted by you with no telemetry and no cloud service, and the operator issues accounts and tokens. Delegation does not launch a model, observation does not invent progress and an agent claim is not independent acceptance. Usage data does not replace a provider bill. File mode and the server need different backup methods.
How to disable. Remove the retinue-server mcp entry from the agent configuration, stop the server and keep the data directory or a retinue.db snapshot if you still need the history.
FAQ
How do I connect an agent?
Install `pip install 'retinue[mcp]'` and run `retinue-server mcp`. Agents without MCP use the HTTP API with a token.
What does one holder per card mean?
Only the current holder can write to a card. Another agent token gets a `403 holder-only-writes` error.
Does it work with Claude Code and Codex?
Yes, through `retinue-server mcp` or the HTTP API. Claude Code and Codex also have read-only session exporters.
Does data go to an external service?
No: the board is hosted by you, with no telemetry or cloud control.
Which license is the project under?
AGPL-3.0-only, with an optional commercial license described in `COMMERCIAL.md`.
Discussion
No questions or reviews yet.
Related
MCP serversA self-hosted control plane for running several agents: task dispatch, run review, spend tracking, connected via MCP, CLI or REST
The @itsaplan/runner CLI takes tasks from the It's a Plan tracker and hands them to Claude Code, Codex or opencode locally.
Discord MCP by cappyeo: a server with 200+ tools
Discord MCP (cappyeo)
A Discord MCP with over 200 typed tools: the agent handles messages, roles and moderation, builds a server from a plan, and writes default to preview mode
Orchestrator for Claude Code, Codex and Gemini CLI: YAML workflows that loop until your own quality gates pass
Untether bridges Claude Code, Codex and OpenCode with Telegram: voice or text tasks, live progress, approvals with buttons.
A Discord MCP for Claude and Cursor: the agent posts and searches messages and manages forums, channels, roles and webhooks through a bot token
README in short
Retinue describes itself as a board and audit layer under the agents you already run, not as a chat or a framework. It has English and Chinese interfaces, a demo with synthetic data and self-hosting docs. Version 0.3.0a5 is marked alpha.