Ouroboros — Claude Code MCP server: spec-first agent workflows
Turns a vague request into a testable spec through interview, crystallize, execute, evaluate. Useful when your agent keeps guessing requirements and redoing the same work.
claude mcp add ouroboros -- uvx ouroboros-aiWhat Ouroboros does
Ouroboros is a local-first runtime for AI coding. It runs a loop: interview, crystallize, execute, evaluate, evolve. You start with a rough idea and end with a Seed — a structured, testable statement of the task. The grading command and expected output stay out of the success contract, so the agent cannot tune its work to a known answer.
Under the hood there is a spec engine, a Ledger, an MCP layer and safety boundaries. The interview runs advisory lanes and reports an ambiguity score; the lower the score, the tighter the task. Install is one command, then ooo setup once inside your coding agent. On Windows the PowerShell script installs Git and uv for you, and Python is not needed.
Running the verify step yourself is the point — otherwise you hand the agent the answer key. The stack splits across three repos: core, domain plugins and a terminal client. Configuration differs per host, and for Cursor and GitHub Copilot it is a JSON block in settings rather than a terminal command.
What it helps with
- turn a vague idea into a testable spec
- stop an agent from tuning code to a known answer
- replay a successful agent run and inspect what happened
- cut ambiguity before the work starts, not after
- compose a domain workflow from core primitives
Example prompts for the agent
- Interview me about this task and show the ambiguity score
- Crystallize this description into a Seed and check it is testable
- Run the loop: interview, crystallize, execute, evaluate
How to install Ouroboros
Platform CLI
claude mcp add ouroboros -- uvx ouroboros-aiuvx runs the command named after the package; if the README names another one, use uvx --from ouroboros-ai <command>
Platform CLI
codex mcp add ouroboros -- uvx ouroboros-aiuvx runs the command named after the package; if the README names another one, use uvx --from ouroboros-ai <command>
Config file
{
"mcpServers": {
"ouroboros": {
"command": "uvx",
"args": [
"ouroboros-ai"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from ouroboros-ai <command>
Config file
{
"servers": {
"ouroboros": {
"type": "stdio",
"command": "uvx",
"args": [
"ouroboros-ai"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from ouroboros-ai <command>
Platform CLI
gemini mcp add ouroboros uvx ouroboros-aiuvx runs the command named after the package; if the README names another one, use uvx --from ouroboros-ai <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Ouroboros
How do I install Ouroboros in Claude?
Run claude mcp add ouroboros -- uvx ouroboros-ai, then run ooo setup once inside your coding agent.
What does Ouroboros do?
It drives agent work through interview, crystallize, execute, evaluate and evolve. A task becomes a spec, and the run becomes replayable.
Why is the grading command kept out of the success contract?
So the agent cannot tune its output to a known answer. The expected result stays with you, not in the task statement.
