Welcome to Zen MCP
Relevant source files
The following files were used as context for generating this wiki page:Zen MCP is a Model Context Protocol (MCP) server designed to supercharge AI-assisted development by enabling a single CLI tool to orchestrate multiple AI models from various providers. It acts as a central hub, allowing tools like Claude Code, Codex CLI, and Cursor to leverage the specialized strengths of different models (e.g., Gemini, GPT-5, O3, local models via Ollama) within a single, continuous conversation.
The core purpose of Zen MCP is to facilitate true AI collaboration. It supports conversation threading, allowing a developer's primary CLI to engage in complex workflows such as debating ideas with multiple models, getting second opinions, and preserving context across different tasks. This enables seamless transitions from analysis to planning, implementation, and validation, all within one conversational thread.
Architecture Overview
Zen MCP is built on a modular architecture, with a central server that handles request routing, tool orchestration, and provider management. The key components are organized into distinct directories, ensuring clear separation of concerns.
This diagram illustrates the high-level structure of the Zen MCP server and its primary modules.
Module Responsibilities
| Module Path | Responsibility |
|---|---|
tools/ | Contains the implementation for the 18+ specialized AI tools. |
providers/ | Provides a unified abstraction layer for different AI model providers. |
systemprompts/ | Stores the system prompt templates that define the behavior of each tool. |
utils/ | Houses core utility functions for file handling, token counting, and conversation memory. |
clink/ | Implements the CLI bridge for integrating external AI CLIs as subagents. |
conf/ | Manages model configurations and client settings. |
tests/ | Contains unit and integration tests. |
Key Features
Conversation Continuity and Context Revival
A cornerstone feature of Zen MCP is its ability to maintain conversational context across different tools and models. This is achieved through an in-memory conversation management system that tracks dialogue turns.
- Conversation Threading: Each session is assigned a unique thread ID, allowing the server to reconstruct the conversation history for subsequent tool calls. This enables complex, multi-step workflows.
- Context Revival: When a primary AI tool's context window is reset, Zen MCP can "remind" it of the prior discussion by using another model to summarize or pass along the essential context. This is managed via a
continuation_id.
Sources: README.md, utils/CLAUDE.md, OPTIMIZATION_ROADMAP.md
The following diagram shows how conversation memory is managed.
Sources: utils/CLAUDE.md
Provider Support
Zen MCP can connect to a wide range of AI model providers. The system activates any provider for which credentials are found in the .env configuration file.
Supported Providers:
- OpenRouter
- Gemini
- OpenAI
- Azure OpenAI
- X.AI (Grok)
- DIAL
- Ollama (for local models)
Sources: README.md
The clink Tool: CLI-to-CLI Bridge
The clink (CLI + Link) tool is a powerful feature that allows the user's main CLI to spawn isolated instances of other external AI CLIs as "subagents." This is useful for offloading specific, heavy tasks like a full code review or planning session to a fresh context without polluting the primary conversation.
This sequence diagram demonstrates the clink workflow.
Sources: README.md
Core Tools
Zen MCP provides a suite of specialized tools, each with a dedicated system prompt that enforces a structured workflow. To optimize performance and context window usage, many tools are disabled by default and can be enabled by editing the DISABLED_TOOLS variable in the .env file.
Sources: README.md, OPTIMIZATION_ROADMAP.md
| Tool | Description | Default Status |
|---|---|---|
clink | Bridges requests to external AI CLIs (e.g., Gemini, Codex). | Enabled |
chat | Brainstorms ideas and gets second opinions from different models. | Enabled |
thinkdeep | Performs extended reasoning and edge case analysis. | Enabled |
planner | Breaks down complex projects into structured, actionable plans. | Enabled |
consensus | Gathers expert opinions from multiple AI models, with stance steering. | Enabled |
debug | Conducts systematic investigation and root cause analysis of errors. | Enabled |
precommit | Validates code changes before committing to prevent regressions. | Enabled |
codereview | Performs professional code reviews with severity levels. | Enabled |
analyze | Understands architecture and dependencies across a codebase. | Disabled |
refactor | Provides intelligent code refactoring with a focus on decomposition. | Disabled |
testgen | Generates comprehensive tests, including edge cases. | Disabled |
docgen | Generates documentation with complexity and call-flow analysis. | Disabled |
Sources: README.md
Tool Prompt Engineering
The reliability of Zen MCP's tools stems from highly structured system prompts. These prompts define the AI's role, its evaluation framework, and a mandatory output format.
For example, the consensus tool's prompt includes a detailed EVALUATION FRAMEWORK that the AI must follow.
Consensus Tool Evaluation Framework:
- TECHNICAL FEASIBILITY: Is it achievable with reasonable effort?
- PROJECT SUITABILITY: Does it fit the existing architecture?
- USER VALUE ASSESSMENT: Will users want this feature?
- IMPLEMENTATION COMPLEXITY: What are the main challenges and risks?
- ALTERNATIVE APPROACHES: Are there simpler ways to achieve the same goal?
- INDUSTRY PERSPECTIVE: What are current best practices?
- LONG-TERM IMPLICATIONS: What is the maintenance burden?
Sources: systemprompts/consensus_prompt.py
Similarly, the codereview tool uses severity definitions to classify issues.
CodeReview Severity Levels:
- 🔴 CRITICAL: Security flaws, crashes, data loss.
- 🟠 HIGH: Bugs, performance bottlenecks, major anti-patterns.
- 🟡 MEDIUM: Maintainability concerns, code smells.
- 🟢 LOW: Style nits, minor clarifications.
Sources: systemprompts/codereview_prompt.py
Structured Code Generation
For tasks involving substantial code creation or modification, capable models are instructed to use a Structured Code Generation Protocol. This ensures that the output is machine-parsable and can be directly applied by a coding agent. The protocol uses specific tags to delineate new and updated files.
Sources: systemprompts/generate_code_prompt.py, tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json
<GENERATED-CODE>
[Step-by-step instructions for the coding agent]
1. Create new file calculator/operations.py to house the core arithmetic functions.
2. ...
<NEWFILE: calculator/operations.py>
"""
Core arithmetic operations.
"""
from typing import Union
Numeric = Union[int, float]
def add(a: Numeric, b: Numeric) -> Numeric:
"""Calculate the sum of two numbers."""
return a + b
</NEWFILE>
</GENERATED-CODE>
This protocol mandates complete, working code blocks with all necessary imports, docstrings, and error handling, eliminating partial implementations.
Sources: systemprompts/generate_code_prompt.py
Example Workflow: Multi-Model Code Review
Zen MCP enables powerful, chained workflows that combine multiple tools and models. A typical code review process might look like this:
This diagram shows a multi-step workflow for a comprehensive code review.
Sources: README.md
Conclusion
Zen MCP Server is a sophisticated orchestration layer that transforms standard AI developer CLIs into a collaborative team of AI experts. By managing conversational context, integrating multiple providers, and enforcing structured workflows through specialized tools, it allows developers to tackle complex software engineering tasks with greater depth, accuracy, and efficiency. Its modular architecture and focus on conversation continuity make it a powerful asset for modern, AI-assisted development.