Configuring Model Providers

Relevant source files

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

• conf/CLAUDE.md
• providers/CLAUDE.md
• providers/base.py
• providers/gemini.py
• providers/openai.py
• providers/azure_openai.py
• providers/registry.py
• README.md
• conf/openai_models.json
• conf/gemini_models.json

The Zen MCP Server is designed to orchestrate multiple AI models from various providers, such as Google (Gemini), OpenAI, and Microsoft (Azure). The provider system is a modular architecture that allows the server to communicate with different AI services through a unified interface. Configuration is managed through a combination of environment variables for credentials and JSON files for defining model capabilities.

This system is extensible, enabling the addition of new providers by implementing a common abstract base class. The server automatically detects and registers available providers at startup based on the provided API keys, making it easy to enable or disable access to different models. For more details on adding new providers, see the Adding Providers guide.

Sources: README.md, providers/CLAUDE.md, AGENTS.md

Configuration Architecture

The provider configuration relies on two primary mechanisms: environment variables for secrets and JSON files for static model metadata. The server automatically activates any provider for which it finds credentials in the environment.

The diagram below illustrates the configuration loading and provider registration flow.

This diagram shows that API keys from the .env file and model capabilities from conf/ JSON files are used by individual provider modules. The ModelProviderRegistry then uses this information to make providers available to the rest of the application.

Sources: README.md, providers/registry.py, conf/CLAUDE.md

Environment Variables

API keys and provider-specific endpoints are configured via environment variables, typically stored in a .env file at the project root. The server will only activate providers for which the corresponding API key is set.

Variable	Provider	Description
GEMINI_API_KEY	Google Gemini	API key for accessing Gemini models.
OPENAI_API_KEY	OpenAI	API key for accessing OpenAI models like GPT-5 and O3.
AZURE_OPENAI_API_KEY	Azure OpenAI	API key for an Azure OpenAI service deployment.
AZURE_OPENAI_ENDPOINT	Azure OpenAI	The endpoint URL for the Azure OpenAI service.
XAI_API_KEY	X.AI	API key for accessing Grok models.
DIAL_API_KEY	DIAL	API key for the DIAL platform.
OPENROUTER_API_KEY	OpenRouter	API key for the OpenRouter aggregation service.
CUSTOM_API_URL	Custom	URL for a custom OpenAI-compatible endpoint, such as a local Ollama server.
CUSTOM_API_KEY	Custom	Optional API key for the custom endpoint.

Sources: README.md, providers/CLAUDE.md, providers/gemini.py, providers/openai.py, providers/azure_openai.py

Model Capability Files

The conf/ directory contains JSON files that define the static capabilities and metadata for models from each provider. These files include details like context window size, vision support, and pricing.

Below is an example snippet from conf/openai_models.json.

{
    "gpt-5": {
        "name": "gpt-5",
        "display_name": "GPT-5",
        "context_window": 200000,
        "max_output_tokens": 8000,
        "supports_vision": true,
        "supports_functions": true,
        "pricing": {
            "input_tokens": 0.000015,
            "output_tokens": 0.00006
        }
    }
}

Sources: conf/openai_models.json, conf/CLAUDE.md

The structure for these capabilities is defined by the ModelCapability class.

This diagram shows the fields used to define a model's capabilities in the configuration files.

Sources: conf/CLAUDE.md

Provider Registration

The ModelProviderRegistry is responsible for discovering and registering available providers at server startup. It automatically detects which providers are configured by checking for the presence of their respective API keys in the environment.

The registry maintains a priority order for resolving model names:

1. Native API Providers (e.g., Gemini, OpenAI) have the highest priority.
2. Custom Endpoints (e.g., Ollama) are next.
3. OpenRouter serves as a fallback to access a wide range of other models.

The following sequence diagram shows the registration process.

Provider Implementation

All provider-specific implementations inherit from the ModelProvider abstract base class. This ensures a consistent interface for invoking models, regardless of the underlying service.

This class diagram shows that concrete provider classes like OpenAIModelProvider and GeminiModelProvider implement the abstract ModelProvider interface.

Sources: providers/base.py, providers/openai.py, providers/gemini.py, providers/azure_openai.py

Disabling Tools

In addition to configuring providers, you can manage which tools are available to the AI models. This is done via the DISABLED_TOOLS environment variable, which accepts a comma-separated list of tool names to disable. This helps optimize context window usage by not loading the descriptions for unused tools.

Example: Disabling the analyze and refactor tools

You can set this in your .env file or directly in your MCP client settings.

# In .env file
DISABLED_TOOLS=analyze,refactor,testgen,secaudit,docgen,tracer

To enable a tool, simply remove it from this list. To enable all tools, set the variable to be empty.

# Enable all tools
DISABLED_TOOLS=

Sources: README.md