Joe/171 oauth seems to have been broken in recent updates (#173)

* fix broken oauth

* simplify tests

* address PR comments

Author: joe-clickhouse

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### Added
+- Support for FastMCP OAuth/OIDC auth providers on HTTP/SSE transports via the `FASTMCP_SERVER_AUTH` environment variable (e.g. Azure Entra, Google, GitHub, WorkOS). Static token, FastMCP OAuth, and disabled mode are now mutually exclusive; configure exactly one. ([#171](https://github.com/ClickHouse/mcp-clickhouse/issues/171))
+
+### Changed
+- `/health` endpoint is now unauthenticated across all auth modes (previously gated only under static-token mode, which was asymmetric and incompatible with redirect-based OAuth providers). Response bodies trimmed to `OK` / generic error strings to avoid leaking ClickHouse version information or connection exception details; underlying errors are logged server-side.
+
 ## 0.3.0 - 2026-04-14
 
 ### Added

README.md

@@ -42,13 +42,15 @@ An MCP server for ClickHouse.
 ### 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
+- Returns `200 OK` (body: `OK`) if the server is healthy and can connect to ClickHouse
+- Returns `503 Service Unavailable` with a generic error message if the server cannot connect to ClickHouse
+
+The endpoint is intentionally unauthenticated so orchestrator probes (e.g. Kubernetes liveness/readiness, load balancers) can reach it without credentials. The response body is deliberately minimal to avoid leaking backend version strings or error details; debug failures via the server logs.
 
 Example:
 ```bash
 curl http://localhost:8000/health
-# Response: OK - Connected to ClickHouse 24.3.1
+# Response: OK
 ```
 
 ## Security
@@ -57,6 +59,16 @@ curl http://localhost:8000/health
 
 When using HTTP or SSE transport, authentication is **required by default**. The `stdio` transport (default) does not require authentication as it only communicates via standard input/output.
 
+Three authentication modes are supported. Pick one:
+
+| Mode                       | When to use                               | Env var                                                                                        |
+|----------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------|
+| Static bearer token        | Simple deployments, internal services     | `CLICKHOUSE_MCP_AUTH_TOKEN`                                                                    |
+| OAuth / OIDC (via FastMCP) | Azure Entra, Google, GitHub, WorkOS, etc. | `FASTMCP_SERVER_AUTH=<provider-class-path>` (+ provider-specific `FASTMCP_SERVER_AUTH_*` vars) |
+| Disabled                   | Local development only                    | `CLICKHOUSE_MCP_AUTH_DISABLED=true`                                                            |
+
+Startup fails if none of these are configured for HTTP/SSE transports.
+
 #### Setting Up Authentication
 
 1. Generate a secure token (can be any random string):
@@ -89,10 +101,22 @@ When using HTTP or SSE transport, authentication is **required by default**. The
    }
    ```
 
-   For command-line tools:
-   ```bash
-   curl -H "Authorization: Bearer your-generated-token" http://localhost:8000/health
-   ```
+   Note: the `/health` endpoint is intentionally unauthenticated (see [Health Check Endpoint](#health-check-endpoint) above). To verify that bearer-token auth is actually rejecting unauthenticated requests, hit the MCP endpoint itself e.g. with the MCP Inspector, or by POSTing a JSON-RPC request to `/mcp` with and without the `Authorization` header and confirming the unauthenticated call returns `401`.
+
+#### OAuth / OIDC via FastMCP
+
+For production deployments with identity providers (Azure Entra, Google, GitHub, WorkOS, etc.), delegate authentication to [FastMCP's built-in auth providers](https://gofastmcp.com/servers/auth) instead of using a static token. Set `FASTMCP_SERVER_AUTH` to the **full class path** of a FastMCP auth provider, along with the provider-specific `FASTMCP_SERVER_AUTH_*` variables, and leave `CLICKHOUSE_MCP_AUTH_TOKEN` unset.
+
+Example (Azure Entra):
+
+```bash
+export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
+export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
+export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
+export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"
+```
+
+See the [FastMCP docs](https://gofastmcp.com/servers/auth) for the full list of providers and their required environment variables.
 
 #### Development Mode (Disabling Authentication)
 
@@ -453,11 +477,7 @@ CLICKHOUSE_PASSWORD=clickhouse
    CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main
 
    # Then in another terminal:
-   # Without auth (if disabled):
    curl http://localhost:8000/health
-
-   # With auth:
-   curl -H "Authorization: Bearer your-token" http://localhost:8000/health
    ```
 
 ### Environment Variables
@@ -515,11 +535,15 @@ The following environment variables are used to configure the ClickHouse and chD
 * `CLICKHOUSE_MCP_QUERY_TIMEOUT`: Timeout in seconds for SELECT tools
   * Default: `"30"`
   * Increase this if you see `Query timed out after ...` errors for heavy queries
-* `CLICKHOUSE_MCP_AUTH_TOKEN`: Authentication token for HTTP/SSE transports
+* `CLICKHOUSE_MCP_AUTH_TOKEN`: Static bearer token for HTTP/SSE transports
   * Default: None
-  * **Required** when using HTTP or SSE transport (unless `CLICKHOUSE_MCP_AUTH_DISABLED=true`)
+  * One of `CLICKHOUSE_MCP_AUTH_TOKEN`, `FASTMCP_SERVER_AUTH`, or `CLICKHOUSE_MCP_AUTH_DISABLED=true` is **required** for HTTP/SSE transports
   * Generate using `uuidgen` or `openssl rand -hex 32`
   * Clients must send this token in the `Authorization: Bearer <token>` header
+* `FASTMCP_SERVER_AUTH`: Delegate authentication to a [FastMCP auth provider](https://gofastmcp.com/servers/auth)
+  * Default: None
+  * Value is the **full class path** of an AuthProvider subclass, e.g. `fastmcp.server.auth.providers.azure.AzureProvider` or `fastmcp.server.auth.providers.google.GoogleProvider`
+  * When set, FastMCP auto-loads the provider from its own `FASTMCP_SERVER_AUTH_*` environment variables; leave `CLICKHOUSE_MCP_AUTH_TOKEN` unset in this mode
 * `CLICKHOUSE_MCP_AUTH_DISABLED`: Disable authentication for HTTP/SSE transports
   * Default: `"false"` (authentication is enabled)
   * Set to `"true"` to disable authentication for local development/testing only
@@ -620,7 +644,7 @@ CLICKHOUSE_PASSWORD=clickhouse
 CLICKHOUSE_MCP_SERVER_TRANSPORT=http
 CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
 CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
-CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # Required for HTTP/SSE
+CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)
 ```
 
 For local development with HTTP transport (authentication disabled):

mcp_clickhouse/mcp_env.py

@@ -300,10 +300,12 @@ 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_AUTH_TOKEN: Authentication token for HTTP/SSE transports (required
-            unless CLICKHOUSE_MCP_AUTH_DISABLED=true)
-        CLICKHOUSE_MCP_AUTH_DISABLED: Disable authentication (default: false, use
-            only for development)
+        CLICKHOUSE_MCP_AUTH_TOKEN: Static bearer token for HTTP/SSE transports.
+            One authentication mode must be configured for HTTP/SSE; the other two
+            options are FASTMCP_SERVER_AUTH (FastMCP OAuth/OIDC providers) and
+            CLICKHOUSE_MCP_AUTH_DISABLED=true.
+        CLICKHOUSE_MCP_AUTH_DISABLED: Disable authentication entirely (default: false,
+            development only)
     """
 
     @property

mcp_clickhouse/mcp_server.py

@@ -71,51 +71,73 @@ class Table:
 
 load_dotenv()
 
-# Configure authentication for HTTP/SSE transports
-auth_provider = None
-mcp_config = get_mcp_config()
-http_transports = [TransportType.HTTP.value, TransportType.SSE.value]
+_HTTP_TRANSPORTS = (TransportType.HTTP.value, TransportType.SSE.value)
+
+
+def _resolve_auth(mcp_config) -> Dict[str, Any]:
+    """Resolve FastMCP auth kwargs for the current transport.
+
+    An empty return dict omits the `auth` kwarg so FastMCP auto-detects its
+    provider from FASTMCP_SERVER_AUTH / FASTMCP_SERVER_AUTH_* env vars.
+    Returning {"auth": None} instead explicitly disables auth.
+    """
+    if mcp_config.server_transport not in _HTTP_TRANSPORTS:
+        return {}
+
+    configured = {
+        "CLICKHOUSE_MCP_AUTH_DISABLED": mcp_config.auth_disabled,
+        "CLICKHOUSE_MCP_AUTH_TOKEN": bool(mcp_config.auth_token),
+        "FASTMCP_SERVER_AUTH": bool(os.getenv("FASTMCP_SERVER_AUTH")),
+    }
+    active = [name for name, is_set in configured.items() if is_set]
+
+    if len(active) > 1:
+        raise ValueError(
+            "Multiple authentication modes configured for HTTP/SSE transport: "
+            f"{', '.join(active)}. These are mutually exclusive; unset all but one."
+        )
+
+    if not active:
+        raise ValueError(
+            "Authentication is required for HTTP/SSE transports. Configure exactly one of:\n"
+            "  - CLICKHOUSE_MCP_AUTH_TOKEN=<token>   (static bearer token)\n"
+            "  - FASTMCP_SERVER_AUTH=<class-path>    (FastMCP auth provider, full class path;\n"
+            "       e.g. fastmcp.server.auth.providers.azure.AzureProvider)\n"
+            "  - CLICKHOUSE_MCP_AUTH_DISABLED=true   (disables auth; development only)"
+        )
 
-if mcp_config.server_transport in http_transports:
     if mcp_config.auth_disabled:
         logger.warning("WARNING: MCP SERVER AUTHENTICATION IS DISABLED")
         logger.warning("Only use this for local development/testing.")
         logger.warning("DO NOT expose to networks.")
-    elif mcp_config.auth_token:
-        auth_provider = StaticTokenVerifier(
+        return {"auth": None}
+
+    if mcp_config.auth_token:
+        verifier = StaticTokenVerifier(
             tokens={mcp_config.auth_token: {"client_id": "mcp-client", "scopes": []}},
             required_scopes=[],
         )
-        logger.info("Authentication enabled for HTTP/SSE transport")
-    else:
-        # No token configured and auth not disabled
-        raise ValueError(
-            "Authentication token required for HTTP/SSE transports. "
-            "Set CLICKHOUSE_MCP_AUTH_TOKEN environment variable or set "
-            "CLICKHOUSE_MCP_AUTH_DISABLED=true (for development only)."
-        )
+        logger.info("Authentication enabled for HTTP/SSE transport (static bearer token)")
+        return {"auth": verifier}
+
+    logger.info(
+        "Authentication delegated to FastMCP provider: %s", os.getenv("FASTMCP_SERVER_AUTH")
+    )
+    # Return empty kwargs so FastMCP auto-loads from FASTMCP_SERVER_AUTH_* env vars.
+    return {}
+
 
-mcp = FastMCP(name=MCP_SERVER_NAME, auth=auth_provider)
+mcp = FastMCP(name=MCP_SERVER_NAME, **_resolve_auth(get_mcp_config()))
 _chdb_client = None
 _chdb_error_message: Optional[str] = None
 
 
 @mcp.custom_route("/health", methods=["GET"])
 async def health_check(request: Request) -> PlainTextResponse:
-    """Health check endpoint for monitoring server status.
+    """Liveness probe. Intentionally unauthenticated and minimal.
 
-    Returns OK if the server is running and can connect to ClickHouse.
+    Debug via server logs.
     """
-    if auth_provider is not None:
-        auth_header = request.headers.get("Authorization")
-        if not auth_header or not auth_header.startswith("Bearer "):
-            return PlainTextResponse("Unauthorized", status_code=401)
-
-        token = auth_header[7:]
-        access_token = await auth_provider.verify_token(token)
-        if access_token is None:
-            return PlainTextResponse("Unauthorized", status_code=401)
-
     try:
         # Check if ClickHouse is enabled by trying to create config
         # If ClickHouse is disabled, this will succeed but connection will fail
@@ -125,26 +147,31 @@ async def health_check(request: Request) -> PlainTextResponse:
             # If ClickHouse is disabled, check chDB status
             chdb_config = get_chdb_config()
             if chdb_config.enabled and _chdb_client is not None:
-                return PlainTextResponse("OK - MCP server running with chDB enabled")
+                return PlainTextResponse("OK")
             elif chdb_config.enabled and _chdb_error_message:
                 return PlainTextResponse(
                     "ERROR. chDB initialization failed. Check server logs for details.",
                     status_code=503,
                 )
             else:
-                # Both ClickHouse and chDB are disabled - this is an error
+                logger.error(
+                    "Health check failed: both CLICKHOUSE_ENABLED=false and CHDB_ENABLED=false"
+                )
                 return PlainTextResponse(
-                    "ERROR - Both ClickHouse and chDB are disabled. At least one must be enabled.",
+                    "ERROR. Server misconfigured. Check server logs for details.",
                     status_code=503,
                 )
 
         # Try to create a client connection to verify ClickHouse connectivity
-        client = create_clickhouse_client()
-        version = client.server_version
-        return PlainTextResponse(f"OK - Connected to ClickHouse {version}")
-    except Exception as e:
-        # Return 503 Service Unavailable if we can't connect to ClickHouse
-        return PlainTextResponse(f"ERROR - Cannot connect to ClickHouse: {str(e)}", status_code=503)
+        create_clickhouse_client()
+        return PlainTextResponse("OK")
+    except Exception:
+        # Log the underlying error server-side, but don't leak details over the wire.
+        logger.exception("Health check failed: ClickHouse connection error")
+        return PlainTextResponse(
+            "ERROR. ClickHouse connection failed. Check server logs for details.",
+            status_code=503,
+        )
 
 
 def result_to_table(query_columns, result) -> List[Table]:

tests/test_auth_config.py

@@ -1,6 +1,7 @@
 import pytest
 
 from mcp_clickhouse.mcp_env import MCPServerConfig
+from mcp_clickhouse.mcp_server import _resolve_auth
 
 
 def test_auth_token_configuration(monkeypatch: pytest.MonkeyPatch):
@@ -68,3 +69,50 @@ def test_auth_token_with_sse_transport(monkeypatch: pytest.MonkeyPatch):
     assert config.server_transport == "sse"
     assert config.auth_token == "sse-auth-token"
     assert config.auth_disabled is False
+
+
+def _clear_auth_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    for var in (
+        "CLICKHOUSE_MCP_AUTH_TOKEN",
+        "CLICKHOUSE_MCP_AUTH_DISABLED",
+        "FASTMCP_SERVER_AUTH",
+    ):
+        monkeypatch.delenv(var, raising=False)
+
+
+def test_resolve_auth_oauth_omits_auth_kwarg(monkeypatch: pytest.MonkeyPatch):
+    """FASTMCP_SERVER_AUTH alone returns empty kwargs (no `auth` key)."""
+    _clear_auth_env(monkeypatch)
+    monkeypatch.setenv("CLICKHOUSE_MCP_SERVER_TRANSPORT", "http")
+    monkeypatch.setenv("FASTMCP_SERVER_AUTH", "fastmcp.server.auth.providers.jwt.JWTVerifier")
+
+    assert _resolve_auth(MCPServerConfig()) == {}
+
+
+def test_resolve_auth_disabled_passes_explicit_none(monkeypatch: pytest.MonkeyPatch):
+    """CLICKHOUSE_MCP_AUTH_DISABLED=true returns {"auth": None}, not {}."""
+    _clear_auth_env(monkeypatch)
+    monkeypatch.setenv("CLICKHOUSE_MCP_SERVER_TRANSPORT", "http")
+    monkeypatch.setenv("CLICKHOUSE_MCP_AUTH_DISABLED", "true")
+
+    assert _resolve_auth(MCPServerConfig()) == {"auth": None}
+
+
+def test_resolve_auth_rejects_multiple_modes(monkeypatch: pytest.MonkeyPatch):
+    """Configuring more than one auth mode raises ValueError."""
+    _clear_auth_env(monkeypatch)
+    monkeypatch.setenv("CLICKHOUSE_MCP_SERVER_TRANSPORT", "http")
+    monkeypatch.setenv("CLICKHOUSE_MCP_AUTH_TOKEN", "secret")
+    monkeypatch.setenv("FASTMCP_SERVER_AUTH", "fastmcp.server.auth.providers.jwt.JWTVerifier")
+
+    with pytest.raises(ValueError, match="mutually exclusive"):
+        _resolve_auth(MCPServerConfig())
+
+
+def test_resolve_auth_http_without_any_mode_raises(monkeypatch: pytest.MonkeyPatch):
+    """HTTP transport with no auth configured raises ValueError."""
+    _clear_auth_env(monkeypatch)
+    monkeypatch.setenv("CLICKHOUSE_MCP_SERVER_TRANSPORT", "http")
+
+    with pytest.raises(ValueError):
+        _resolve_auth(MCPServerConfig())

tests/test_optional_chdb.py

@@ -114,3 +114,30 @@ async def test_health_check_hides_internal_chdb_init_error_details():
     assert b"initialization failed" in body
     assert b"check server logs for details" in body
     assert b"/tmp/private.db" not in body
+
+
+@pytest.mark.asyncio
+async def test_health_check_hides_clickhouse_connection_error_details():
+    """A 503 response from a connection failure does not include the exception's hostname or credentials."""
+    request = Request({"type": "http", "method": "GET", "headers": []})
+
+    def raise_with_secrets():
+        raise ConnectionError(
+            "HTTPConnectionPool(host='internal-ch.prod.mycorp.local', port=8443): "
+            "password=hunter2 failed"
+        )
+
+    with (
+        patch.dict("os.environ", {"CLICKHOUSE_ENABLED": "true"}, clear=False),
+        patch.object(
+            mcp_server, "create_clickhouse_client", side_effect=raise_with_secrets
+        ),
+    ):
+        response = await mcp_server.health_check(request)
+
+    assert response.status_code == 503
+    body = response.body.lower()
+    assert b"clickhouse connection failed" in body
+    assert b"check server logs for details" in body
+    assert b"internal-ch.prod.mycorp.local" not in body
+    assert b"hunter2" not in body