Make MCP server URL configurable via env var and CLI flag

- Add environment variable overrides in config loader:
  MAS_AVIARY_MCP_URL, MAS_AVIARY_MCP_MODE, MAS_AVIARY_MODEL_ID,
  MAS_AVIARY_API_BASE (highest priority, overrides YAML values)
- Add --mcp-url flag to stat_batch_runner.py
- Document configuration hierarchy in README (CLI > env var > YAML)
- Add 6 tests for env var override behavior

Author: Jezemba

README.md

@@ -140,16 +140,46 @@ python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}, de
 
 ---
 
+## MCP Server Configuration
+
+The MCP server URL is configurable at three levels (highest priority wins):
+
+1. **CLI flag**: `--mcp-url http://your-host:port/mcp`
+2. **Environment variable**: `export MAS_AVIARY_MCP_URL=http://your-host:port/mcp`
+3. **YAML config**: edit `mcp.servers[0].url` in `config/aviary_run.yaml`
+
+The default config ships with `http://127.0.0.1:8600/mcp`. Override it for
+remote servers, non-standard ports, or containerized deployments:
+
+```bash
+# Environment variable (persists for the shell session)
+export MAS_AVIARY_MCP_URL=http://192.168.1.50:9000/mcp
+
+# Or pass directly to the runner
+python scripts/stat_batch_runner.py --mcp-url http://192.168.1.50:9000/mcp --repeats 1
+```
+
+Other environment variable overrides:
+
+| Variable | Overrides | Example |
+|----------|-----------|---------|
+| `MAS_AVIARY_MCP_URL` | MCP server URL | `http://10.0.0.5:8600/mcp` |
+| `MAS_AVIARY_MCP_MODE` | MCP mode (`mock` or `real`) | `mock` |
+| `MAS_AVIARY_MODEL_ID` | LLM model | `Qwen/Qwen3-4B` |
+| `MAS_AVIARY_API_BASE` | vLLM API endpoint | `http://localhost:8000/v1` |
+
+---
+
 ## Quickstart
 
 ### 1. Start the Aviary MCP server
 
 The MCP server provides tool-based access to NASA OpenMDAO/Aviary simulations.
-It must be running on port 8600 before launching agents:
+It must be running before launching agents:
 
 ```bash
 # See your Aviary MCP server documentation for startup instructions
-# The server should be accessible at http://127.0.0.1:8600/mcp
+# Default: http://127.0.0.1:8600/mcp (configurable — see above)
 ```
 
 ### 2. Run a single optimization

scripts/stat_batch_runner.py

@@ -33,6 +33,7 @@
 import gc
 import json
 import math
+import os
 import time
 from dataclasses import dataclass
 from pathlib import Path
@@ -835,8 +836,16 @@ def main():
         "--timeout", type=float, default=_DEFAULT_TIMEOUT_MINUTES,
         help=f"Per-run timeout in minutes (default: {_DEFAULT_TIMEOUT_MINUTES})",
     )
+    parser.add_argument(
+        "--mcp-url", type=str, default=None,
+        help="MCP server URL (overrides config; e.g. http://127.0.0.1:8600/mcp)",
+    )
     args = parser.parse_args()
 
+    # Allow --mcp-url to override via environment variable.
+    if args.mcp_url:
+        os.environ["MAS_AVIARY_MCP_URL"] = args.mcp_url
+
     run_stat_batch(
         n_repeats=args.repeats,
         combo_names=args.combinations,

src/config/loader.py

@@ -1,5 +1,6 @@
 """Configuration loader — reads YAML files and returns structured config."""
 
+import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -86,8 +87,42 @@ def _dict_to_dataclass(cls, data: dict[str, Any]):
     return cls(**filtered)
 
 
+def _apply_env_overrides(config: AppConfig) -> AppConfig:
+    """Override config values from environment variables.
+
+    Supported variables:
+        MAS_AVIARY_MCP_URL  — overrides the URL of the first MCP server
+        MAS_AVIARY_MCP_MODE — overrides mcp.mode ("mock" or "real")
+        MAS_AVIARY_MODEL_ID — overrides llm.model_id
+        MAS_AVIARY_API_BASE — overrides llm.api_base (for vLLM)
+    """
+    mcp_url = os.environ.get("MAS_AVIARY_MCP_URL")
+    if mcp_url:
+        if config.mcp.servers:
+            config.mcp.servers[0].url = mcp_url
+        else:
+            config.mcp.servers = [MCPServerConfig(url=mcp_url)]
+
+    mcp_mode = os.environ.get("MAS_AVIARY_MCP_MODE")
+    if mcp_mode:
+        config.mcp.mode = mcp_mode
+
+    model_id = os.environ.get("MAS_AVIARY_MODEL_ID")
+    if model_id:
+        config.llm.model_id = model_id
+
+    api_base = os.environ.get("MAS_AVIARY_API_BASE")
+    if api_base:
+        config.llm.api_base = api_base
+
+    return config
+
+
 def load_config(path: str | Path) -> AppConfig:
-    """Load configuration from a YAML file and return an AppConfig dataclass."""
+    """Load configuration from a YAML file and return an AppConfig dataclass.
+
+    Environment variables override YAML values (see _apply_env_overrides).
+    """
     path = Path(path)
     if not path.exists():
         raise FileNotFoundError(f"Config file not found: {path}")
@@ -96,9 +131,11 @@ def load_config(path: str | Path) -> AppConfig:
         raw = yaml.safe_load(f)
 
     if raw is None:
-        return AppConfig()
+        config = AppConfig()
+    else:
+        config = _dict_to_dataclass(AppConfig, raw)
 
-    return _dict_to_dataclass(AppConfig, raw)
+    return _apply_env_overrides(config)
 
 
 def load_yaml(path: str | Path) -> dict[str, Any]:

tests/test_config_loader.py

@@ -1,5 +1,7 @@
 """Tests for the configuration loader."""
 
+import os
+
 import pytest
 import yaml
 
@@ -172,3 +174,72 @@ def test_appconfig_defaults():
     assert isinstance(cfg.logging, LoggingConfig)
     assert isinstance(cfg.ui, UIConfig)
     assert cfg.agents_config == "config/agents.yaml"
+
+
+# ---- environment variable overrides -------------------------------------------
+
+def test_env_override_mcp_url(tmp_path, monkeypatch):
+    """MAS_AVIARY_MCP_URL overrides the first MCP server URL."""
+    cfg_file = tmp_path / "test.yaml"
+    cfg_file.write_text(yaml.dump({
+        "mcp": {
+            "mode": "real",
+            "servers": [{"url": "http://original:8600/mcp", "transport": "streamable-http"}],
+        }
+    }))
+    monkeypatch.setenv("MAS_AVIARY_MCP_URL", "http://custom-host:9999/mcp")
+    cfg = load_config(str(cfg_file))
+    assert cfg.mcp.servers[0].url == "http://custom-host:9999/mcp"
+
+
+def test_env_override_mcp_url_creates_server(tmp_path, monkeypatch):
+    """MAS_AVIARY_MCP_URL creates a server entry if none exist."""
+    cfg_file = tmp_path / "empty_mcp.yaml"
+    cfg_file.write_text(yaml.dump({"mcp": {"mode": "real"}}))
+    monkeypatch.setenv("MAS_AVIARY_MCP_URL", "http://new-host:7000/mcp")
+    cfg = load_config(str(cfg_file))
+    assert len(cfg.mcp.servers) == 1
+    assert cfg.mcp.servers[0].url == "http://new-host:7000/mcp"
+
+
+def test_env_override_mcp_mode(tmp_path, monkeypatch):
+    """MAS_AVIARY_MCP_MODE overrides mcp.mode."""
+    cfg_file = tmp_path / "test.yaml"
+    cfg_file.write_text(yaml.dump({"mcp": {"mode": "real"}}))
+    monkeypatch.setenv("MAS_AVIARY_MCP_MODE", "mock")
+    cfg = load_config(str(cfg_file))
+    assert cfg.mcp.mode == "mock"
+
+
+def test_env_override_model_id(tmp_path, monkeypatch):
+    """MAS_AVIARY_MODEL_ID overrides llm.model_id."""
+    cfg_file = tmp_path / "test.yaml"
+    cfg_file.write_text(yaml.dump({"llm": {"model_id": "original-model"}}))
+    monkeypatch.setenv("MAS_AVIARY_MODEL_ID", "Qwen/Qwen3-4B")
+    cfg = load_config(str(cfg_file))
+    assert cfg.llm.model_id == "Qwen/Qwen3-4B"
+
+
+def test_env_override_api_base(tmp_path, monkeypatch):
+    """MAS_AVIARY_API_BASE overrides llm.api_base."""
+    cfg_file = tmp_path / "test.yaml"
+    cfg_file.write_text(yaml.dump({"llm": {"backend": "vllm"}}))
+    monkeypatch.setenv("MAS_AVIARY_API_BASE", "http://gpu-box:8080/v1")
+    cfg = load_config(str(cfg_file))
+    assert cfg.llm.api_base == "http://gpu-box:8080/v1"
+
+
+def test_env_override_not_set(tmp_path):
+    """Without env vars, YAML values are preserved as-is."""
+    cfg_file = tmp_path / "test.yaml"
+    cfg_file.write_text(yaml.dump({
+        "mcp": {
+            "mode": "real",
+            "servers": [{"url": "http://yaml-host:8600/mcp"}],
+        }
+    }))
+    for var in ("MAS_AVIARY_MCP_URL", "MAS_AVIARY_MCP_MODE",
+                "MAS_AVIARY_MODEL_ID", "MAS_AVIARY_API_BASE"):
+        os.environ.pop(var, None)
+    cfg = load_config(str(cfg_file))
+    assert cfg.mcp.servers[0].url == "http://yaml-host:8600/mcp"