Emit warning when servers attribute accessed

Author: msabramo

src/mcp/client/config/mcp_servers_config.py

@@ -133,11 +133,50 @@ class SSEServerConfig(MCPServerConfig):
 
 
 class MCPServersConfig(BaseModel):
-    """Configuration for multiple MCP servers."""
+    """Configuration for multiple MCP servers.
+
+    Note:
+        Direct access to the 'servers' field is discouraged.
+        Use the server() method instead for proper input validation and substitution.
+    """
 
     servers: dict[str, ServerConfigUnion]
     inputs: list[InputDefinition] | None = None
 
+    def __getattribute__(self, name: str) -> Any:
+        """Get an attribute from the config.
+
+        This emits a warning if the `servers` field is accessed directly.
+        This is to discourage direct access to the `servers` field.
+        Use the `server()` method instead for proper input validation and substitution.
+        """
+
+        if name == "servers":
+            import inspect
+            import warnings
+
+            # Get the calling frame to check if it's internal access
+            frame = inspect.currentframe()
+            if frame and frame.f_back:
+                caller_filename = frame.f_back.f_code.co_filename
+                caller_function = frame.f_back.f_code.co_name
+
+                # Don't warn for internal methods, tests, or if called from within this class
+                is_internal_call = (
+                    caller_function in ("server", "list_servers", "has_server", "__init__", "model_validate")
+                    or "mcp_servers_config.py" in caller_filename
+                )
+
+                if not is_internal_call:
+                    warnings.warn(
+                        f"Direct access to 'servers' field of {self.__class__.__name__} is discouraged. "
+                        + "Use server() method instead for proper input validation and substitution.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+
+        return super().__getattribute__(name)
+
     def server(
         self,
         name: str,
@@ -163,6 +202,14 @@ def server(
 
         return server
 
+    def list_servers(self) -> list[str]:
+        """Get a list of available server names."""
+        return list(self.servers.keys())
+
+    def has_server(self, name: str) -> bool:
+        """Check if a server with the given name exists."""
+        return name in self.servers
+
     @model_validator(mode="before")
     @classmethod
     def handle_field_aliases(cls, data: dict[str, Any]) -> dict[str, Any]:

tests/client/config/test_mcp_servers_config.py

@@ -183,9 +183,9 @@ def test_servers_field_takes_precedence():
     config = MCPServersConfig.model_validate(config_data)
 
     # Should only have the 'servers' content, not 'mcpServers'
-    assert "new_server" in config.servers
-    assert "old_server" not in config.servers
-    assert len(config.servers) == 1
+    assert config.has_server("new_server")
+    assert not config.has_server("old_server")
+    assert len(config.list_servers()) == 1
 
 
 def test_from_file_with_inputs(tmp_path: Path):
@@ -582,8 +582,8 @@ def test_jsonc_comment_stripping():
     stripped = MCPServersConfig._strip_json_comments(content_with_comments)
     config = MCPServersConfig.model_validate(json.loads(stripped))
 
-    assert "test_server" in config.servers
-    server = config.servers["test_server"]
+    assert config.has_server("test_server")
+    server = config.server("test_server")
     assert isinstance(server, StdioServerConfig)
     assert server.command == "python test.py"
 
@@ -704,10 +704,10 @@ def test_jsonc_multiline_strings_with_comments():
     config = MCPServersConfig.model_validate(json.loads(stripped))
 
     assert len(config.servers) == 2
-    assert "test1" in config.servers
-    assert "test2" in config.servers
+    assert config.has_server("test1")
+    assert config.has_server("test2")
 
-    test1 = config.servers["test1"]
+    test1 = config.server("test1")
     assert isinstance(test1, StdioServerConfig)
     assert test1.command == "python server.py"
 

tests/client/config/test_yaml_functionality.py

@@ -20,12 +20,12 @@ def test_yaml_extension_auto_detection(mcp_yaml_config_file: Path):
     config = MCPServersConfig.from_file(mcp_yaml_config_file)
 
     # Should successfully load the YAML file with all 9 servers
-    assert "stdio_server" in config.servers
-    assert "streamable_http_server_with_headers" in config.servers
-    assert "sse_server_with_explicit_type" in config.servers
+    assert config.has_server("stdio_server")
+    assert config.has_server("streamable_http_server_with_headers")
+    assert config.has_server("sse_server_with_explicit_type")
 
     # Verify a specific server
-    stdio_server = config.servers["stdio_server"]
+    stdio_server = config.server("stdio_server")
     assert isinstance(stdio_server, StdioServerConfig)
     assert stdio_server.command == "python"
     assert stdio_server.args == ["-m", "my_server"]
@@ -40,24 +40,24 @@ def test_use_pyyaml_parameter_with_json_file():
     config = MCPServersConfig.from_file(json_file, use_pyyaml=True)
 
     # Should work fine - PyYAML can parse JSON
-    assert len(config.servers) == 7
-    assert "stdio_server" in config.servers
+    assert len(config.list_servers()) == 7
+    assert config.has_server("stdio_server")
 
     # Verify it produces the same result as normal JSON parsing
     config_json = MCPServersConfig.from_file(json_file, use_pyyaml=False)
-    assert len(config.servers) == len(config_json.servers)
-    assert list(config.servers.keys()) == list(config_json.servers.keys())
+    assert len(config.list_servers()) == len(config_json.list_servers())
+    assert list(config.list_servers()) == list(config_json.list_servers())
 
 
 def test_uvx_time_server(mcp_yaml_config_file: Path):
     """Test the time server configuration with uvx command."""
     config = MCPServersConfig.from_file(mcp_yaml_config_file)
 
     # Should have the time server
-    assert "time" in config.servers
+    assert config.has_server("time")
 
     # Verify the server configuration
-    time_server = config.servers["time"]
+    time_server = config.server("time")
     assert isinstance(time_server, StdioServerConfig)
     assert time_server.type == "stdio"  # Should be auto-inferred from command field
     assert time_server.command == "uvx mcp-server-time"
@@ -74,10 +74,10 @@ def test_streamable_http_server(mcp_yaml_config_file: Path):
     config = MCPServersConfig.from_file(mcp_yaml_config_file)
 
     # Should have the new streamable_http_server
-    assert "streamable_http_server" in config.servers
+    assert config.has_server("streamable_http_server")
 
     # Verify the server configuration
-    http_server = config.servers["streamable_http_server"]
+    http_server = config.server("streamable_http_server")
     assert isinstance(http_server, StreamableHTTPServerConfig)
     assert http_server.type == "streamable_http"  # Should be auto-inferred
     assert http_server.url == "https://api.example.com/mcp"
@@ -89,10 +89,10 @@ def test_npx_filesystem_server(mcp_yaml_config_file: Path):
     config = MCPServersConfig.from_file(mcp_yaml_config_file)
 
     # Should have the filesystem server
-    assert "filesystem" in config.servers
+    assert config.has_server("filesystem")
 
     # Verify the server configuration
-    filesystem_server = config.servers["filesystem"]
+    filesystem_server = config.server("filesystem")
     assert isinstance(filesystem_server, StdioServerConfig)
     assert filesystem_server.type == "stdio"  # Should be auto-inferred from command field
     assert (