Theodosia: AI Agent Service Supporting MCP Protocol for Apache Burr Workflows

Theodosia is an MCP protocol-based server implementation designed specifically for Apache Burr state machine workflows, enabling AI agents to drive complex business processes in a controlled and auditable manner, with each execution limited to one mandatory state transition.

Basic Project Information:

• Original Author/Maintainer: msradam
• Source Platform: GitHub
• Release Date: 2026-05-25
• Original Link: https://github.com/msradam/theodosia

Core Value: Addresses the issues of unpredictable behavior, lack of auditability, and difficulty in rollback for LLM agents in production environments. By combining Apache Burr state machines with the MCP protocol, it provides a standardized AI access solution.

In modern AI applications, the demand for LLM agents to automate complex tasks is growing, but predictability, auditability, and rollback capability of their behavior have become key challenges. Traditional stateless API models are difficult to meet production environment requirements.

Apache Burr is a stateful workflow framework that models business processes as traceable state machines; Theodosia implements an MCP server on this basis to provide standardized AI agent access capabilities for Burr workflows.

Theodosia is designed around "controlled AI agent interaction", enforcing the "one state transition at a time" mode: AI agents can only request to advance one workflow step each time, and the system verifies and records at each transition point.

Advantages:

1. Auditability: Each state transition is explicitly recorded, allowing precise reproduction of system states for easy troubleshooting;
2. Security: Limits the impact scope of a single call, making the impact of wrong decisions controllable and easy to roll back and fix;
3. Predictability: The determinism of state machines complements the uncertainty of AI, providing a stable execution framework.

Model Context Protocol (MCP) is an open protocol proposed by Anthropic, standardizing the interaction between AI and external tools/data sources. As an MCP server implementation, Theodosia follows protocol specifications and supports any MCP-compatible AI client to access Burr workflows.

MCP core capabilities include resources, tools, and prompts; Theodosia focuses on tool capabilities: exposing Burr state transitions as MCP tool calls. AI agents initiate requests via MCP, and the server maps them to corresponding state transitions and returns results.

Value: Strong ecological interoperability—developers can use MCP clients like Claude Desktop and Cursor for interaction without worrying about underlying Burr implementation details.

Theodosia adopts a modular Python architecture:

• Core code is located in src/theodosia, including MCP protocol handling, Burr integration, and state management modules;
• Provides examples (samples), bench (benchmark tests), tests (test coverage), and demos (interactive demos) directories;
• Automated quality assurance: Uses .githooks and GitHub Actions for code checks;
• A supporting website directory provides documentation sites to lower the learning threshold.

Theodosia is suitable for the following scenarios:

1. Complex approval process automation: Multi-level approval decisions are clearly recorded at each step, and process states are queryable;
2. Sensitive operation control: For high-risk operations like data modification and fund transfers, the "one transition at a time" mode provides a security gate;
3. Compliance industries: Fields requiring strict audits such as finance, healthcare, and government—state machine models naturally meet compliance requirements;
4. Human-AI collaboration workflows: Easily implement the collaboration mode of "AI proposal → manual review → state advancement".

• vs LangChain/LlamaIndex: Provides higher-level abstraction and stronger constraints, solving the problem of rich tools but lack of workflow control in traditional frameworks;
• vs Temporal/Camunda: Natively designed for AI agents, considering the uncertainty of AI decisions, while traditional engines assume processes are driven by deterministic code.

Future Directions:

• Visual editor: Supports non-technical personnel to design/modify Burr workflows;
• Multi-agent coordination: Allows multiple AI agents to collaborate in the same workflow;
• Advanced audit analysis: Provides decision quality analysis and optimization suggestions based on state history;
• Enterprise integration: Deep integration with infrastructure such as SSO, permission management, and monitoring alerts.

Conclusion: Theodosia balances AI capabilities and process control, representing an important evolutionary direction for AI agent application architectures. It provides a valuable reference implementation for teams integrating LLMs into core business systems.