Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The Zen MCP Server is a Model Context Protocol (MCP) server designed to enable multi-model AI collaboration for development tools like Claude Code, Codex CLI, and Cursor. Its primary purpose is to act as an orchestration layer, allowing a single client tool to interact with multiple AI models from various providers (e.g., Gemini, OpenAI, Anthropic, Ollama) within a single, continuous conversation. This architecture facilitates complex workflows where different models can be leveraged for specific tasks, such as code review, planning, and debugging, while maintaining a shared context.
The system is built on a modular Python architecture. Key features include a unified provider system, a structured tool system for specialized tasks, and a conversation memory mechanism to ensure context continuity. This allows developers to chain commands and pass the full history of an interaction from one model or tool to another, creating a collaborative AI development team.
Core Components
The server's architecture is divided into several distinct modules, each with a specific responsibility. This separation of concerns allows for clear dependency management and extensibility.
Sources: CLAUDE.md:19-33
The following diagram illustrates the high-level module structure of the Zen MCP Server.
Sources: CLAUDE.md:19-33, README.md:159-181
| Component | Description | Source Files |
|---|---|---|
| Server Core | The main entry point (server.py) that implements the MCP protocol, handles client requests, and orchestrates the workflow between tools and providers. | server.py |
| Tools | A collection of specialized AI agents for tasks like code review (codereview), planning (planner), and multi-model debate (consensus). | tools/ |
| Providers | An abstraction layer for interacting with various third-party AI model providers, ensuring a consistent interface for making API calls. | providers/ |
| Utils | Shared utilities and components, most notably the conversation memory system that enables stateful, continuous dialogues. | utils/ |
| System Prompts | A repository of prompt templates that define the roles, behaviors, and output formats for each AI tool. | systemprompts/ |
| CLink | A CLI bridge system that allows the server to integrate with and spawn external AI CLI tools as sub-agents. | clink/, README.md:21-38 |
| Configuration | Manages environment variables, model settings, and tool enablement. | conf/, README.md:184-239 |
Sources: CLAUDE.md:35-43, README.md:21-38, 159-181
Request Handling Flow
When a client sends a request to the Zen MCP Server, it undergoes a standardized processing flow that involves identifying the requested tool, invoking the appropriate model provider, and managing the conversation state.
This sequence diagram shows the typical lifecycle of a request.
- Request Reception: The
server.pyreceives an MCP request from a client. - Context Retrieval: The server interacts with the
ConversationMemoryutility to load the history for the current session, ensuring context continuity. - Tool Dispatch: The server parses the user's prompt to identify which tool to execute (e.g.,
consensus,codereview). - Tool Execution: The selected tool's
executemethod is called. The tool prepares a specific, structured prompt based on its defined behavior insystemprompts. - Provider Invocation: The tool uses a provider instance (e.g.,
GeminiProvider) to send the request to the target AI model. The provider layer handles the specifics of the external API call. - Response Handling: The provider returns the model's raw response to the tool, which then formats it according to the MCP specification.
- State Update: The new request and response are saved to the
ConversationMemory. - Response Streaming: The final, formatted response is streamed back to the client.
Sources: server.py, utils/conversation_memory.py, tools/shared/base_tool.py, providers/base.py
Abstraction Layers
The system's modularity is achieved through two primary abstraction layers: the Tool System and the Provider System. Both rely on base classes that define a common interface for all implementations.
This class diagram shows the inheritance structure for Tools and Providers.
Sources: tools/shared/base_tool.py, providers/base.py
Tool System
All tools inherit from a BaseTool class. This ensures that every tool has a consistent interface, including a name, description, and an execute method. The server dynamically loads and registers these tools, making the system extensible. The behavior of each tool is primarily defined by its corresponding system prompt, which instructs the AI model on its role, evaluation framework, and required output format.
Sources: tools/shared/base_tool.py, systemprompts/consensus_prompt.py:5-101
Provider System
Similarly, all model providers inherit from a BaseProvider class. This class defines a standard contract for interacting with different AI services, including methods like list_models() and generate(). This abstraction allows the core logic and tools to remain vendor-agnostic; adding a new AI provider only requires creating a new class that implements this interface.
Sources: providers/base.py
Conversation and State Management
A core feature of the Zen MCP Server is its ability to maintain conversational context across multiple tool and model interactions. This is managed by the ConversationMemory class.
- Stateful Interaction: It stores a history of "turns" (user requests and model responses) for each conversation thread.
- Context Continuity: When a new request comes in, the memory provides the historical context, which is then passed to the next model. This is how a model can be "reminded" of a previous interaction, even if its own internal context was reset.
- Timeout and Limits: The memory system implements a conversation timeout and a maximum number of turns to manage resources effectively.
This state management is what enables complex, multi-step workflows and the "Context Revival" feature highlighted in the project's documentation.
Sources: utils/conversation_memory.py, README.md:80-82
Summary
The Zen MCP Server is architected as a modular and extensible orchestration engine for multi-model AI workflows. Its key design principles include the separation of concerns through distinct modules (Tools, Providers, Utils), the use of abstraction layers to ensure vendor-agnosticism and tool consistency, and a robust state management system for enabling continuous, context-aware conversations. This architecture allows it to function as a powerful "super-glue" that connects a developer's preferred CLI tool to a collaborative team of specialized AI agents.