Configuration System

Relevant source files

The following files were used as context for generating this wiki page:

• config.py
• conf/
• utils/env.py
• README.md
• AGENTS.md
• CLAUDE.md
• OPTIMIZATION_ROADMAP.md

The Zen MCP Server's configuration system provides a flexible way to manage server behavior, API keys, model settings, and tool enablement. It primarily uses environment variables loaded from an .env file, with support for JSON-based configurations for more complex settings like model capabilities and CLI client integrations. This layered approach allows for easy setup for most users while offering deep customization for advanced scenarios.

The system is designed to activate providers and tools dynamically based on the provided credentials and settings. This ensures that the server is tailored to the user's specific needs and available resources, optimizing performance and context window usage.

Sources: README.md, AGENTS.md, config.py

Configuration Loading

The server loads configuration settings from multiple sources with a specific order of precedence. The core logic is handled by the get_env function in utils/env.py, which orchestrates the loading process.

The following diagram illustrates the configuration loading flow:

This diagram shows that the get_env function centralizes configuration retrieval from system environment variables, the .env file, and the MCP client's JSON settings.

Sources: utils/env.py, README.md

Loading Priority

1. System Environment Variables: These have the highest priority.
2. .env File: Variables defined in the .env file in the project root are loaded. These can override system environment variables if ZEN_MCP_FORCE_ENV_OVERRIDE is enabled.
3. MCP Client Settings: Configuration can also be passed directly from the MCP client (e.g., ~/.claude/settings.json), which is particularly useful for managing API keys and tool settings without modifying server-side files.
4. Default Values: If a variable is not found in any of the above sources, a default value specified in config.py is used.

The run-server.sh script plays a key role in this process by handling the initial setup and regeneration of environments.

Sources: utils/env.py, README.md, AGENTS.md

Environment Variables

Environment variables are the primary method for configuring the Zen MCP Server. They control everything from API keys to logging levels and tool enablement.

Key Configuration Variables

Variable	Description	Default Value	Source File
GEMINI_API_KEY	API key for Google Gemini models.	None	README.md
OPENAI_API_KEY	API key for OpenAI models.	None	README.md
OPENROUTER_API_KEY	API key for OpenRouter service.	None	README.md
DISABLED_TOOLS	A comma-separated list of tools to disable.	analyze,refactor,testgen,secaudit,docgen,tracer	README.md, OPTIMIZATION_ROADMAP.md
ENABLED_TOOLS	A comma-separated list of tools to enable, overriding the default set.	chat,thinkdeep,planner,codereview,debug,batch_query,consensus,precommit	OPTIMIZATION_ROADMAP.md
DEFAULT_MODEL	The default model to use for requests. "auto" enables automatic selection.	"auto"	config.py:28
LOG_LEVEL	Sets the application's logging level (e.g., DEBUG, INFO, ERROR).	"INFO"	config.py:21
CONVERSATION_TIMEOUT_HOURS	Hours after which an inactive conversation thread is cleaned up.	3	config.py:34
MAX_CONVERSATION_TURNS	The maximum number of turns to retain in a conversation's history.	50	config.py:37
MCP_PROMPT_SIZE_LIMIT	The token limit for prompts sent to the MCP client.	60000	config.py:40

Example .env Configuration

The run-server.sh script helps manage the .env file. A typical configuration might look like this:

# .env
# API Keys
GEMINI_API_KEY="your-gemini-key-here"
OPENAI_API_KEY="your-openai-key-here"

# Tool Configuration
DISABLED_TOOLS="analyze,refactor,testgen,secaudit,docgen,tracer"

# Server Behavior
LOG_LEVEL="INFO"
DEFAULT_MODEL="pro"

Sources: README.md, AGENTS.md, OPTIMIZATION_ROADMAP.md

JSON Configuration Files

For more structured and complex configurations, the server utilizes JSON files located in the conf/ directory.

This diagram shows how different parts of the conf/ directory are used by the CLink and Provider systems.

Sources: CLAUDE.md

Model Configuration (conf/*_models.json)

These files define the capabilities, restrictions, and metadata for different AI models supported by the providers. This allows the system to understand which models are available and what their features are without hardcoding this information.

Sources: CLAUDE.md

CLI Client Configuration (conf/cli_clients/)

This directory contains configurations for external CLI tools that are integrated via the clink tool. This allows Zen MCP to act as a bridge, spawning and communicating with subagents like the Gemini CLI or Codex CLI. The system prompts for these specialized roles are also defined here.

Sources: CLAUDE.md, systemprompts/clink/codex_codereviewer.txt, systemprompts/clink/default_codereviewer.txt

Tool Configuration

The server's tools can be enabled or disabled to optimize performance and reduce the context window size consumed by unused tool descriptions.

Enabling and Disabling Tools

The DISABLED_TOOLS environment variable is used to manage which tools are active. By default, several tools are disabled to conserve resources. To enable a tool, you simply remove it from this comma-separated list.

Default Disabled Tools:
analyze, refactor, testgen, secaudit, docgen, tracer

Default Enabled Tools:
chat, thinkdeep, planner, consensus, codereview, precommit, debug, apilookup, challenge

To enable all tools, the DISABLED_TOOLS variable can be set to an empty string.

// Example: Enabling the 'analyze' tool in MCP client settings
{
  "mcpServers": {
    "zen": {
      "env": {
        "DISABLED_TOOLS": "refactor,testgen,secaudit,docgen,tracer"
      }
    }
  }
}

This configuration can be placed in ~/.claude/settings.json or a .mcp.json file.

Sources: README.md, OPTIMIZATION_ROADMAP.md

Summary

The Zen MCP Server's configuration system is a robust and multi-layered framework that combines the simplicity of environment variables with the structure of JSON files. It provides granular control over API providers, model selection, tool management, and server behavior. This flexibility allows developers to tailor the server to their exact workflow, whether for a quick local setup or a complex, multi-model orchestration environment. The clear separation of concerns between .env files for secrets, conf/ for structured data, and config.py for application defaults makes the system both powerful and maintainable.