Client connection reuse and server-side query cancellation

README.md

@@ -487,9 +487,9 @@ The following environment variables are used to configure the ClickHouse and chD
 * `CLICKHOUSE_CONNECT_TIMEOUT`: Connection timeout in seconds
   * Default: `"30"`
   * Increase this value if you experience connection timeouts
-* `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds
-  * Default: `"300"`
-  * Increase this value for long-running queries
+* `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds for the underlying HTTP connection
+  * Default: automatically set to `CLICKHOUSE_MCP_QUERY_TIMEOUT + 5` so worker threads unblock shortly after a query timeout
+  * If explicitly set, the value is used as-is (e.g. `"300"` for long-running queries)
 * `CLICKHOUSE_DATABASE`: Default database to use
   * Default: None (uses server default)
   * Set this to automatically connect to a specific database
@@ -503,9 +503,14 @@ The following environment variables are used to configure the ClickHouse and chD
 * `CLICKHOUSE_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"`
-* `CLICKHOUSE_MCP_QUERY_TIMEOUT`: Timeout in seconds for SELECT tools
+* `CLICKHOUSE_MCP_QUERY_TIMEOUT`: Timeout in seconds for query tool calls
   * Default: `"30"`
   * Increase this if you see `Query timed out after ...` errors for heavy queries
+  * When a query times out, the server issues a `KILL QUERY` on the ClickHouse server to cancel it
+  * Unless `CLICKHOUSE_SEND_RECEIVE_TIMEOUT` is explicitly set, the HTTP read timeout is automatically aligned to this value plus a small buffer, so worker threads unblock shortly after a timeout
+* `CLICKHOUSE_MCP_MAX_WORKERS`: Maximum number of concurrent query worker threads
+  * Default: `"10"`
+  * Increase if your workload requires many concurrent tool calls
 * `CLICKHOUSE_MCP_AUTH_TOKEN`: Authentication token for HTTP/SSE transports
   * Default: None
   * **Required** when using HTTP or SSE transport (unless `CLICKHOUSE_MCP_AUTH_DISABLED=true`)

mcp_clickhouse/__init__.py

@@ -2,6 +2,8 @@
 
 from .mcp_server import (
     create_clickhouse_client,
+    _clear_client_cache,
+    _resolve_client_config,
     list_databases,
     list_tables,
     run_query,
@@ -27,6 +29,8 @@
     "list_tables",
     "run_query",
     "create_clickhouse_client",
+    "_clear_client_cache",
+    "_resolve_client_config",
     "create_chdb_client",
     "run_chdb_select_query",
     "chdb_initial_prompt",

mcp_clickhouse/mcp_env.py

@@ -291,6 +291,7 @@ class MCPServerConfig:
         CLICKHOUSE_MCP_BIND_HOST: Bind host for HTTP/SSE (default: 127.0.0.1)
         CLICKHOUSE_MCP_BIND_PORT: Bind port for HTTP/SSE (default: 8000)
         CLICKHOUSE_MCP_QUERY_TIMEOUT: SELECT tool timeout in seconds (default: 30)
+        CLICKHOUSE_MCP_MAX_WORKERS: Maximum thread pool workers for query execution (default: 10)
         CLICKHOUSE_MCP_AUTH_TOKEN: Authentication token for HTTP/SSE transports (required
             unless CLICKHOUSE_MCP_AUTH_DISABLED=true)
         CLICKHOUSE_MCP_AUTH_DISABLED: Disable authentication (default: false, use
@@ -317,6 +318,14 @@ def bind_port(self) -> int:
     def query_timeout(self) -> int:
         return int(os.getenv("CLICKHOUSE_MCP_QUERY_TIMEOUT", "30"))
 
+    @property
+    def max_workers(self) -> int:
+        """Maximum thread pool workers for query execution.
+
+        Default: 10
+        """
+        return int(os.getenv("CLICKHOUSE_MCP_MAX_WORKERS", "10"))
+
     @property
     def auth_token(self) -> Optional[str]:
         """Get the authentication token for HTTP/SSE transports."""