How to Configure the Model Context Protocol (MCP) Using the `mcp_config_path` Setting

Set ENABLE_MCP=true and point MCP_CONFIG_PATH to a JSON file containing an mcpServers array; the Settings model in src/config/settings.py validates the file on startup and injects the configuration into the Claude SDK.

The Model Context Protocol (MCP) enables the Claude Code Telegram bot to communicate with external MCP servers for extended functionality. Configuration is handled entirely through environment variables and a JSON configuration file parsed by the Pydantic Settings model. This guide explains how to enable MCP, structure the configuration file, and validate the setup using the actual source code from the RichardAtCT/claude-code-telegram repository.

Enable MCP with the ENABLE_MCP Flag

Before configuring the file path, you must activate the MCP feature. The application checks the ENABLE_MCP boolean setting during initialization.

Set the environment variable:

export ENABLE_MCP=true

When this flag is true, the application expects a valid MCP_CONFIG_PATH and will validate the referenced file before starting the bot. If enabled but misconfigured, the bot raises a ValueError and exits immediately.

Create the MCP Configuration JSON File

The MCP_CONFIG_PATH must reference a JSON file containing a top-level object with an mcpServers key. This array defines the remote servers Claude Code will connect to via the Model Context Protocol.

Create a file (e.g., mcp_config.json) with the following structure:

{
  "mcpServers": [
    {
      "host": "127.0.0.1",
      "port": 8000,
      "protocol": "http"
    }
  ]
}

Each object in the mcpServers array should specify connection parameters required by your MCP server implementation. The configuration supports multiple servers; simply append additional objects to the array.

Set the mcp_config_path Environment Variable

Point the application to your JSON file using the MCP_CONFIG_PATH environment variable. This path is loaded by the Settings class in src/config/settings.py.

export MCP_CONFIG_PATH=/absolute/path/to/mcp_config.json

Alternatively, you can define this in a .env file or Docker Compose environment block. The setting accepts any absolute or relative path that resolves to a readable file.

Validation Logic in src/config/settings.py

The Settings model performs strict validation on the MCP configuration during instantiation (lines 265–282). According to the source code, the validation routine performs three critical checks:

1. File Existence: Verifies os.path.isfile(v) returns True for the provided path
2. JSON Parsing: Attempts json.load() and surfaces parsing errors as ValueError with descriptive messages
3. Schema Validation: Ensures the loaded data is a Python dict containing the mandatory "mcpServers" key mapped to an array

If any validation fails, the bot refuses to start and outputs a specific error message indicating whether the file is missing, malformed, or structurally invalid. This prevents runtime errors by catching configuration issues at import time.

How the Configuration Reaches the Claude SDK

Once validated, the MCP configuration is injected into Claude's request pipeline through two integration points.

In src/claude/sdk_integration.py (lines 188–197), the parsed configuration is attached to ClaudeAgentOptions when initializing the SDK client. This ensures the MCP server list is included in API requests when ENABLE_MCP is active.

For CLI-based fallbacks, the same configuration logic appears in src/claude/integration.py, ensuring consistent behavior across different Claude Code execution modes.

Complete Configuration Example

Follow these steps to configure MCP for a local development environment:

# 1. Export required Telegram bot token

export TELEGRAM_BOT_TOKEN="your_bot_token_here"

# 2. Enable MCP feature

export ENABLE_MCP=true

# 3. Define configuration file path

export MCP_CONFIG_PATH="$HOME/claude-mcp-config.json"

# 4. Create the configuration file

cat > "$HOME/claude-mcp-config.json" << 'EOF'
{
  "mcpServers": [
    {
      "host": "localhost",
      "port": 3000,
      "protocol": "http"
    }
  ]
}
EOF

# 5. Start the bot

make run

If configured correctly, the application logs will confirm MCP server registration during startup. If the JSON is invalid or the path incorrect, you will see an immediate ValueError detailing the specific validation failure.

Summary

• Enable the feature by setting ENABLE_MCP=true before starting the bot
• Create a JSON configuration file containing an mcpServers array with connection details
• Point to the file using the MCP_CONFIG_PATH environment variable
• Validation occurs automatically in src/config/settings.py, checking file existence, JSON validity, and required schema structure
• Configuration is injected into the Claude SDK via src/claude/sdk_integration.py and CLI integration via src/claude/integration.py

Frequently Asked Questions

What happens if the mcp_config_path file does not exist?

The Settings validator in src/config/settings.py calls os.path.isfile() on the provided path. If the file is missing, the application raises a ValueError immediately upon startup, preventing the bot from launching with an invalid configuration.

Can I configure multiple MCP servers in a single file?

Yes. The JSON schema requires an mcpServers array, allowing you to define multiple server objects within a single configuration file. Each object should specify unique host, port, and protocol values according to your infrastructure.

Does MCP configuration work with both the Claude SDK and CLI modes?

Yes. The repository implements MCP configuration injection in two locations: src/claude/sdk_integration.py for programmatic SDK usage and src/claude/integration.py for CLI fallback scenarios. Both paths read from the same Settings model and apply identical validation logic.

What is the exact JSON schema required for the MCP configuration file?

The file must contain a single JSON object with a mandatory mcpServers key mapped to an array. While the specific fields within each server object (such as host, port, and protocol) depend on your MCP server implementation, the top-level structure must always include the mcpServers array to pass validation in src/config/settings.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}