Allow specifying bind host and bind port (ClickHouse#64)

Co-authored-by: Ethan Bell <ebell@hydrolix.io>

Author: iskakaushik

README.md

@@ -27,6 +27,18 @@ Due to the wide variety in LLM architectures, not all models will proactively us
 * Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
   - This prompts the model to write more efficient queries that take advantage of [primary key optimizations](https://hydrolix.io/blog/optimizing-latest-n-row-queries/)
 
+### Health Check Endpoint
+
+When running with HTTP or SSE transport, a health check endpoint is available at `/health`. This endpoint:
+- Returns `200 OK` with the ClickHouse version if the server is healthy and can connect to ClickHouse
+- Returns `503 Service Unavailable` if the server cannot connect to ClickHouse
+
+Example:
+```bash
+curl http://localhost:8000/health
+# Response: OK - Connected to ClickHouse 24.3.1
+```
+
 ## Configuration
 
 The Hydrolix MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.
@@ -129,4 +141,29 @@ The following variables are used to configure the Hydrolix connection. These var
   * Set this to automatically connect to a specific database
 * `HYDROLIX_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server.
   * Default: `"stdio"`
-  * Valid options: `"stdio"`, `"http"`, `"streamable-http"`, `"sse"`. This is useful for local development with tools like MCP Inspector.
+  * Valid options: `"stdio"`, `"http"`, `"sse"`. This is useful for local development with tools like MCP Inspector.
+* `HYDROLIX_MCP_BIND_HOST`: Host to bind the MCP server to when using HTTP or SSE transport
+  * Default: `"127.0.0.1"`
+  * Set to `"0.0.0.0"` to bind to all network interfaces (useful for Docker or remote access)
+  * Only used when transport is `"http"` or `"sse"`
+* `HYDROLIX_MCP_BIND_PORT`: Port to bind the MCP server to when using HTTP or SSE transport
+  * Default: `"8000"`
+  * Only used when transport is `"http"` or `"sse"`
+
+
+For MCP Inspector or remote access with HTTP transport:
+
+```env
+HYDROLIX_HOST=localhost
+HYDROLIX_USER=default
+HYDROLIX_PASSWORD=myPassword
+HYDROLIX_MCP_SERVER_TRANSPORT=http
+HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
+HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)
+```
+
+When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:
+- MCP endpoint: `http://localhost:4200/mcp`
+- Health check: `http://localhost:4200/health`
+
+Note: The bind host and port settings are only used when transport is set to "http" or "sse".

mcp_hydrolix/main.py

@@ -1,11 +1,20 @@
 from .mcp_server import mcp
-from .mcp_env import get_config
+from .mcp_env import get_config, TransportType
 
 
 def main():
     config = get_config()
     transport = config.mcp_server_transport
-    mcp.run(transport=transport)
+
+    # For HTTP and SSE transports, we need to specify host and port
+    http_transports = [TransportType.HTTP.value, TransportType.SSE.value]
+    if transport in http_transports:
+        # Use the configured bind host (defaults to 127.0.0.1, can be set to 0.0.0.0)
+        # and bind port (defaults to 8000)
+        mcp.run(transport=transport, host=config.mcp_bind_host, port=config.mcp_bind_port)
+    else:
+        # For stdio transport, no host or port is needed
+        mcp.run(transport=transport)
 
 
 if __name__ == "__main__":

mcp_hydrolix/mcp_env.py

@@ -7,6 +7,20 @@
 from dataclasses import dataclass
 import os
 from typing import Optional
+from enum import Enum
+
+
+class TransportType(str, Enum):
+    """Supported MCP server transport types."""
+
+    STDIO = "stdio"
+    HTTP = "http"
+    SSE = "sse"
+
+    @classmethod
+    def values(cls) -> list[str]:
+        """Get all valid transport values."""
+        return [transport.value for transport in cls]
 
 
 @dataclass
@@ -29,6 +43,8 @@ class HydrolixConfig:
         HYDROLIX_DATABASE: Default database to use (default: None)
         HYDROLIX_PROXY_PATH: Path to be added to the host URL. For instance, for servers behind an HTTP proxy (default: None)
         HYDROLIX_MCP_SERVER_TRANSPORT: MCP server transport method - "stdio", "http", or "sse" (default: stdio)
+        HYDROLIX_MCP_BIND_HOST: Host to bind the MCP server to when using HTTP or SSE transport (default: 127.0.0.1)
+        HYDROLIX_MCP_BIND_PORT: Port to bind the MCP server to when using HTTP or SSE transport (default: 8000)
     """
 
     def __init__(self):
@@ -89,6 +105,7 @@ def send_receive_timeout(self) -> int:
         Default: 300 (Hydrolix default)
         """
         return int(os.getenv("HYDROLIX_SEND_RECEIVE_TIMEOUT", "300"))
+
     @property
     def proxy_path(self) -> str:
         return os.getenv("HYDROLIX_PROXY_PATH")
@@ -100,14 +117,32 @@ def mcp_server_transport(self) -> str:
         Valid options: "stdio", "http", "sse"
         Default: "stdio"
         """
-        transport = os.getenv("HYDROLIX_MCP_SERVER_TRANSPORT", "stdio").lower()
-        valid_transports = "stdio", "http", "streamable-http", "sse"
-        if transport not in valid_transports:
-            raise ValueError(
-                f"Invalid transport '{transport}'. Valid options: {', '.join(valid_transports)}"
-            )
+        transport = os.getenv("HYDROLIX_MCP_SERVER_TRANSPORT", TransportType.STDIO.value).lower()
+
+        # Validate transport type
+        if transport not in TransportType.values():
+            valid_options = ", ".join(f'"{t}"' for t in TransportType.values())
+            raise ValueError(f"Invalid transport '{transport}'. Valid options: {valid_options}")
         return transport
 
+    @property
+    def mcp_bind_host(self) -> str:
+        """Get the host to bind the MCP server to.
+
+        Only used when transport is "http" or "sse".
+        Default: "127.0.0.1"
+        """
+        return os.getenv("HYDROLIX_MCP_BIND_HOST", "127.0.0.1")
+
+    @property
+    def mcp_bind_port(self) -> int:
+        """Get the port to bind the MCP server to.
+
+        Only used when transport is "http" or "sse".
+        Default: 8000
+        """
+        return int(os.getenv("HYDROLIX_MCP_BIND_PORT", "8000"))
+
     def get_client_config(self) -> dict:
         """Get the configuration dictionary for clickhouse_connect client.
 

mcp_hydrolix/mcp_server.py

@@ -8,7 +8,10 @@
 from clickhouse_connect.driver.binding import format_query_value
 from dotenv import load_dotenv
 from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
 from dataclasses import dataclass, field, asdict, is_dataclass
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
 
 from mcp_hydrolix.mcp_env import get_config
 
@@ -69,6 +72,22 @@ class Table:
 )
 
 
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> PlainTextResponse:
+    """Health check endpoint for monitoring server status.
+
+    Returns OK if the server is running and can connect to Hydrolix.
+    """
+    try:
+        # Try to create a client connection to verify query-head connectivity
+        client = create_hydrolix_client()
+        version = client.server_version
+        return PlainTextResponse(f"OK - Connected to Hydrolix compatible with ClickHouse {version}")
+    except Exception as e:
+        # Return 503 Service Unavailable if we can't connect to Hydrolix
+        return PlainTextResponse(f"ERROR - Cannot connect to Hydrolix: {str(e)}", status_code=503)
+
+
 def result_to_table(query_columns, result) -> List[Table]:
     return [Table(**dict(zip(query_columns, row))) for row in result]
 
@@ -155,9 +174,7 @@ def execute_query(query: str):
         return {"columns": res.column_names, "rows": res.result_rows}
     except Exception as err:
         logger.error(f"Error executing query: {err}")
-        # Return a structured dictionary rather than a string to ensure proper serialization
-        # by the MCP protocol. String responses for errors can cause BrokenResourceError.
-        return {"error": str(err)}
+        raise ToolError(f"Query execution failed: {str(err)}")
 
 
 @mcp.tool()
@@ -217,16 +234,12 @@ def run_select_query(query: str):
         except concurrent.futures.TimeoutError:
             logger.warning(f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds: {query}")
             future.cancel()
-            # Return a properly structured response for timeout errors
-            return {
-                "status": "error",
-                "message": f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds",
-            }
+            raise ToolError(f"Query timed out after {SELECT_QUERY_TIMEOUT_SECS} seconds")
+    except ToolError:
+        raise
     except Exception as e:
         logger.error(f"Unexpected error in run_select_query: {str(e)}")
-        # Catch all other exceptions and return them in a structured format
-        # to prevent MCP serialization failures
-        return {"status": "error", "message": f"Unexpected error: {str(e)}"}
+        raise RuntimeError(f"Unexpected error during query execution: {str(e)}")
 
 
 def create_hydrolix_client():

tests/test_mcp_server.py

@@ -1,6 +1,7 @@
 import pytest
 import pytest_asyncio
 from fastmcp import Client
+from fastmcp.exceptions import ToolError
 import asyncio
 from mcp_clickhouse.mcp_server import mcp, create_clickhouse_client
 from dotenv import load_dotenv
@@ -256,15 +257,12 @@ async def test_run_select_query_error(mcp_server, setup_test_database):
     async with Client(mcp_server) as client:
         # Query non-existent table
         query = f"SELECT * FROM {test_db}.non_existent_table"
-        result = await client.call_tool("run_select_query", {"query": query})
 
-        query_result = json.loads(result[0].text)
+        # Should raise ToolError
+        with pytest.raises(ToolError) as exc_info:
+            await client.call_tool("run_select_query", {"query": query})
 
-        # Should return error structure
-        assert "status" in query_result
-        assert query_result["status"] == "error"
-        assert "message" in query_result
-        assert "Query failed" in query_result["message"]
+        assert "Query execution failed" in str(exc_info.value)
 
 
 @pytest.mark.asyncio
@@ -273,13 +271,12 @@ async def test_run_select_query_syntax_error(mcp_server):
     async with Client(mcp_server) as client:
         # Invalid SQL syntax
         query = "SELECT FROM WHERE"
-        result = await client.call_tool("run_select_query", {"query": query})
 
-        query_result = json.loads(result[0].text)
+        # Should raise ToolError
+        with pytest.raises(ToolError) as exc_info:
+            await client.call_tool("run_select_query", {"query": query})
 
-        # Should return error structure
-        assert query_result["status"] == "error"
-        assert "Query failed" in query_result["message"]
+        assert "Query execution failed" in str(exc_info.value)
 
 
 @pytest.mark.asyncio

tests/test_tool.py

@@ -2,6 +2,7 @@
 import json
 
 from dotenv import load_dotenv
+from fastmcp.exceptions import ToolError
 
 from mcp_hydrolix import create_hydrolix_client, list_databases, list_tables, run_select_query
 
@@ -73,10 +74,12 @@ def test_run_select_query_success(self):
     def test_run_select_query_failure(self):
         """Test running a SELECT query with an error."""
         query = f"SELECT * FROM {self.test_db}.non_existent_table"
-        result = run_select_query.fn(query)
-        self.assertIsInstance(result, dict)
-        self.assertEqual(result["status"], "error")
-        self.assertIn("Query failed", result["message"])
+
+        # Should raise ToolError
+        with self.assertRaises(ToolError) as context:
+            run_select_query.fn(query)
+
+        self.assertIn("Query execution failed", str(context.exception))
 
     def test_table_and_column_comments(self):
         """Test that table and column comments are correctly retrieved."""