Server API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Zen MCP Server provides a multi-model AI orchestration layer for various AI development tools like Claude Code, Codex CLI, and Cursor. It is not a traditional web server with REST endpoints. Instead, it operates as a Model Context Protocol (MCP) server, communicating via JSON messages over standard input and standard output. This design allows it to be seamlessly integrated as a subprocess by CLI-based AI tools.
The server's primary role is to receive a request from a client tool, dispatch it to one of its specialized internal "tools" (e.g., codereview, planner, chat), which may in turn invoke one or more external AI models from different providers (like Gemini, OpenAI, or Anthropic). It manages conversation context, enabling complex, multi-step, and multi-model workflows.
Sources: README.md, AGENTS.md, server.py
Architecture Overview
The server is designed with a modular architecture, even though the core logic resides in server.py. The main components interact to process a request from a client.
This diagram shows the high-level data flow from a client request to a response.
Sources: optimization_analysis.md, README.md, server.py
Communication Protocol
The server communicates using a simple protocol:
- The client tool launches the
server.pyscript as a subprocess. - The client sends a single-line JSON request object to the server's
stdin. - The server processes the request, which may involve long-running tasks like calling external AI model APIs.
- The server prints a single-line JSON response object to
stdout.
The main processing loop is located in the main function within server.py.
Sources: server.py:950-986, AGENTS.md
Request Processing Flow
This flowchart illustrates how the server handles an incoming request.
Sources: server.py:950-986
API Data Structures
Request Payload
A request to the server is a JSON object containing details about the task. While the exact fields can vary, a typical request includes the following:
| Field | Type | Description | Source |
|---|---|---|---|
tool_name | string | The name of the Zen MCP tool to execute (e.g., chat, consensus). | server.py:968 |
prompt | string | The user's prompt or instruction for the tool. | server.py:968 |
model | string | The preferred AI model to use (e.g., gemini-pro, o3). Can be "auto". | server.py:465 |
files | array of strings | A list of file paths relevant to the prompt. | server.py:968 |
continuation_id | string | An ID to resume a previous conversation, enabling context continuity. | server.py:536 |
Response Payload
The response is also a JSON object. For tasks involving code generation, the model's output often follows a structured XML-like format to separate instructions from code blocks.
Standard Response
A standard response from a tool is wrapped in a JSON structure. An example from a test cassette shows a candidates array containing the model's output.
Sources: tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json
Structured Code Generation Response
When a tool's task is substantial code generation, the model is prompted to return its output within a special <GENERATED-CODE> block. This allows for automated parsing and file operations by the client.
The structure is defined as follows:
<GENERATED-CODE>
[Step-by-step instructions for the coding agent]
1. Create new file [filename] with [description]
2. Update existing file [filename] by [description]
<NEWFILE: path/to/new_file.py>
[Complete file contents...]
</NEWFILE>
<UPDATED_EXISTING_FILE: existing/path.py>
[Complete replacement code for the modified sections...]
</UPDATED_EXISTING_FILE>
</GENERATED-CODE>
This protocol is detailed in the system prompt for code generation.
Sources: systemprompts/generate_code_prompt.py:23-74
Core Tools API
The tool_name in the request payload determines which tool is executed. The server maintains a dictionary of available tools.
# server.py:264-287
TOOLS: Dict[str, "Tool"] = {
"version": VersionTool(),
"listmodels": ListModelsTool(),
"chat": ChatTool(),
"clink": CLinkTool(),
# ... and more
}
The following table lists the core tools enabled by default and their purpose.
| Tool Name | Description | Source |
|---|---|---|
chat | Brainstorm ideas, get second opinions, and validate approaches. | README.md |
thinkdeep | For extended reasoning, edge case analysis, and alternative perspectives. | README.md |
planner | Breaks down complex projects into structured, actionable plans. | README.md |
consensus | Gathers expert opinions from multiple AI models with stance steering. | README.md |
debug | Provides systematic investigation and root cause analysis for code. | README.md |
precommit | Validates changes before committing to prevent regressions. | README.md |
codereview | Performs professional code reviews with severity levels and feedback. | README.md |
clink | Bridges requests to external AI CLIs (e.g., Gemini CLI) as subagents. | README.md |
Sources: README.md, server.py:264-287
Example Tool Interaction Sequence
This sequence diagram shows how the consensus tool might work, involving multiple AI model providers.
Summary
The Zen MCP Server API is a specialized, JSON-based protocol over stdio, tailored for integrating multiple AI models into a developer's command-line workflow. Its power lies in the tool-based architecture, which abstracts complex tasks like code review, planning, and debugging into distinct, executable units. By managing conversation history and routing requests to the appropriate tool and AI model, the server acts as a powerful orchestration engine for collaborative AI-assisted development.