Handle code review feedback: add support for default syntax like Claude Code; compile a regex only once; use re.sub.

Author: Walter Gillett

docs/mcp/client.md

@@ -189,29 +189,34 @@ The configuration file should be a JSON file with an `mcpServers` object contain
 
 ### Environment Variables
 
-The configuration file supports environment variable expansion using the `${VAR_NAME}` syntax. This is useful for keeping sensitive information like API keys or host names out of your configuration files:
+The configuration file supports environment variable expansion using the `${VAR}` and `${VAR:-default}` syntax,
+[like Claude Code](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json).
+This is useful for keeping sensitive information like API keys or host names out of your configuration files:
 
 ```json {title="mcp_config_with_env.json"}
 {
   "mcpServers": {
     "python-runner": {
-      "command": "${PYTHON_CMD}",
+      "command": "${PYTHON_CMD:-python3}",
       "args": ["run", "${MCP_MODULE}", "stdio"],
       "env": {
         "API_KEY": "${MY_API_KEY}"
       }
     },
     "weather-api": {
-      "url": "https://${SERVER_HOST}:${SERVER_PORT}/sse"
+      "url": "https://${SERVER_HOST:-localhost}:${SERVER_PORT:-8080}/sse"
     }
   }
 }
 ```
 
-When loading this configuration with [`load_mcp_servers()`][pydantic_ai.mcp.load_mcp_servers], the `${VAR_NAME}` references will be replaced with the corresponding environment variable values.
+When loading this configuration with [`load_mcp_servers()`][pydantic_ai.mcp.load_mcp_servers]:
+
+- `${VAR}` references will be replaced with the corresponding environment variable values.
+- `${VAR:-default}` references will use the environment variable value if set, otherwise the default value.
 
 !!! warning
-    If a referenced environment variable is not defined, a `ValueError` will be raised. Make sure all required environment variables are set before loading the configuration.
+    If a referenced environment variable using `${VAR}` syntax is not defined, a `ValueError` will be raised. Use the `${VAR:-default}` syntax to provide a fallback value.
 
 ### Usage
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -53,6 +53,13 @@
     )
 )
 
+# Environment variable expansion pattern
+# Supports both ${VAR_NAME} and ${VAR_NAME:-default} syntax
+# Group 1: variable name
+# Group 2: the ':-' separator (to detect if default syntax is used)
+# Group 3: the default value (can be empty)
+_ENV_VAR_PATTERN = re.compile(r'\$\{([^}:]+)(:-([^}]*))?\}')
+
 
 class MCPServer(AbstractToolset[Any], ABC):
     """Base class for attaching agents to MCP servers.
@@ -932,7 +939,8 @@ class MCPServerConfig(BaseModel):
 def _expand_env_vars(value: Any) -> Any:
     """Recursively expand environment variables in a JSON structure.
 
-    Environment variables can be referenced using ${VAR_NAME} syntax.
+    Environment variables can be referenced using ${VAR_NAME} syntax,
+    or ${VAR_NAME:-default} syntax to provide a default value if the variable is not set.
 
     Args:
         value: The value to expand (can be str, dict, list, or other JSON types).
@@ -941,17 +949,27 @@ def _expand_env_vars(value: Any) -> Any:
         The value with all environment variables expanded.
 
     Raises:
-        ValueError: If an environment variable is not defined.
+        ValueError: If an environment variable is not defined and no default value is provided.
     """
     if isinstance(value, str):
         # Find all environment variable references in the string
-        env_var_pattern = re.compile(r'\$\{([^}]+)\}')
-        matches = env_var_pattern.findall(value)
-
-        for var_name in matches:
-            if var_name not in os.environ:
+        # Supports both ${VAR_NAME} and ${VAR_NAME:-default} syntax
+        def replace_match(match: re.Match[str]) -> str:
+            var_name = match.group(1)
+            has_default = match.group(2) is not None
+            default_value = match.group(3) if has_default else None
+
+            # Check if variable exists in environment
+            if var_name in os.environ:
+                return os.environ[var_name]
+            elif has_default:
+                # Use default value if the :- syntax was present (even if empty string)
+                return default_value or ''
+            else:
+                # No default value and variable not set - raise error
                 raise ValueError(f'Environment variable ${{{var_name}}} is not defined')
-            value = value.replace(f'${{{var_name}}}', os.environ[var_name])
+
+        value = _ENV_VAR_PATTERN.sub(replace_match, value)
 
         return value
     elif isinstance(value, dict):
@@ -965,7 +983,9 @@ def _expand_env_vars(value: Any) -> Any:
 def load_mcp_servers(config_path: str | Path) -> list[MCPServerStdio | MCPServerStreamableHTTP | MCPServerSSE]:
     """Load MCP servers from a configuration file.
 
-    Environment variables can be referenced in the configuration file using ${VAR_NAME} syntax.
+    Environment variables can be referenced in the configuration file using:
+    - `${VAR_NAME}` syntax - expands to the value of VAR_NAME, raises error if not defined
+    - `${VAR_NAME:-default}` syntax - expands to VAR_NAME if set, otherwise uses the default value
 
     Args:
         config_path: The path to the configuration file.
@@ -976,7 +996,7 @@ def load_mcp_servers(config_path: str | Path) -> list[MCPServerStdio | MCPServer
     Raises:
         FileNotFoundError: If the configuration file does not exist.
         ValidationError: If the configuration file does not match the schema.
-        ValueError: If an environment variable referenced in the configuration is not defined.
+        ValueError: If an environment variable referenced in the configuration is not defined and no default value is provided.
     """
     config_path = Path(config_path)
 

tests/test_mcp.py

@@ -121,6 +121,21 @@ async def test_aexit_called_more_times_than_aenter():
         await server.__aexit__(None, None, None)
 
 
+async def test_is_running():
+    """Test the is_running property."""
+    server = MCPServerStdio('python', ['-m', 'tests.mcp_server'])
+
+    # Server should not be running initially
+    assert not server.is_running
+
+    # Server should be running inside the context manager
+    async with server:
+        assert server.is_running
+
+    # Server should not be running after exiting the context manager
+    assert not server.is_running
+
+
 async def test_stdio_server_with_tool_prefix(run_context: RunContext[int]):
     server = MCPServerStdio('python', ['-m', 'tests.mcp_server'], tool_prefix='foo')
     async with server:
@@ -1577,6 +1592,108 @@ def test_load_mcp_servers_with_non_string_values(tmp_path: Path, monkeypatch: py
     assert server.command == 'python'
 
 
+def test_load_mcp_servers_with_default_values(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Test ${VAR:-default} syntax for environment variable expansion."""
+    config = tmp_path / 'mcp.json'
+
+    # Test with undefined variable using default
+    monkeypatch.delenv('UNDEFINED_VAR', raising=False)
+    config.write_text('{"mcpServers": {"server": {"command": "${UNDEFINED_VAR:-python3}", "args": []}}}')
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.command == 'python3'
+
+    # Test with defined variable (should use actual value, not default)
+    monkeypatch.setenv('DEFINED_VAR', 'actual_value')
+    config.write_text('{"mcpServers": {"server": {"command": "${DEFINED_VAR:-default_value}", "args": []}}}')
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.command == 'actual_value'
+
+    # Test with empty string as default
+    monkeypatch.delenv('UNDEFINED_VAR', raising=False)
+    config.write_text('{"mcpServers": {"server": {"command": "${UNDEFINED_VAR:-}", "args": []}}}')
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.command == ''
+
+
+def test_load_mcp_servers_with_default_values_in_url(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Test ${VAR:-default} syntax in URLs."""
+    config = tmp_path / 'mcp.json'
+
+    # Test with default values in URL
+    monkeypatch.delenv('HOST', raising=False)
+    monkeypatch.setenv('PROTOCOL', 'https')
+    config.write_text('{"mcpServers": {"server": {"url": "${PROTOCOL:-http}://${HOST:-localhost}:${PORT:-8080}/mcp"}}}')
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStreamableHTTP)
+    assert server.url == 'https://localhost:8080/mcp'
+
+
+def test_load_mcp_servers_with_default_values_in_env_dict(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Test ${VAR:-default} syntax in env dictionary."""
+    config = tmp_path / 'mcp.json'
+
+    monkeypatch.delenv('API_KEY', raising=False)
+    monkeypatch.setenv('CUSTOM_VAR', 'custom_value')
+    config.write_text(
+        '{"mcpServers": {"server": {"command": "python", "args": [], '
+        '"env": {"API_KEY": "${API_KEY:-default_key}", "CUSTOM": "${CUSTOM_VAR:-fallback}"}}}}'
+    )
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.env == {'API_KEY': 'default_key', 'CUSTOM': 'custom_value'}
+
+
+def test_load_mcp_servers_with_complex_default_values(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Test ${VAR:-default} syntax with special characters in default."""
+    config = tmp_path / 'mcp.json'
+
+    monkeypatch.delenv('PATH_VAR', raising=False)
+    # Test default with slashes, dots, and dashes
+    config.write_text('{"mcpServers": {"server": {"command": "${PATH_VAR:-/usr/local/bin/python-3.10}", "args": []}}}')
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.command == '/usr/local/bin/python-3.10'
+
+
+def test_load_mcp_servers_with_mixed_syntax(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Test mixing ${VAR} and ${VAR:-default} syntax in the same config."""
+    config = tmp_path / 'mcp.json'
+
+    monkeypatch.setenv('REQUIRED_VAR', 'required_value')
+    monkeypatch.delenv('OPTIONAL_VAR', raising=False)
+    config.write_text(
+        '{"mcpServers": {"server": {"command": "${REQUIRED_VAR}", "args": ["${OPTIONAL_VAR:-default_arg}"]}}}'
+    )
+
+    servers = load_mcp_servers(config)
+    assert len(servers) == 1
+    server = servers[0]
+    assert isinstance(server, MCPServerStdio)
+    assert server.command == 'required_value'
+    assert server.args == ['default_arg']
+
+
 async def test_server_info(mcp_server: MCPServerStdio) -> None:
     with pytest.raises(
         AttributeError, match='The `MCPServerStdio.server_info` is only instantiated after initialization.'