ClickHouse/mcp-clickhouse

v0.4.0 Breaking

This release includes 3 breaking changes for platform teams planning a safe upgrade.

Published 10h MCP Data & Storage

View tool

✓ No known CVEs patched

Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Affected surfaces

auth

ReleasePort's take

Moderate signal

editorial:auto 10h

Auth modes must now be set exclusively; configure exactly one authentication method.

Why it matters: Breaking change: mutually exclusive auth configuration (severity 70) requires updating all deployments to select a single auth mode before upgrade.

Summary

AI summary

Auth modes are now mutually exclusive and responses changed to JSON‑encoded strings.

Changes in this release

Type	Severity	Summary	CVE
Breaking
Breaking	High	Auth modes are now mutually exclusive; configure exactly one. Auth modes are now mutually exclusive; configure exactly one. Source: llm_adapter@2026-06-03 Confidence: high	—
Breaking	Medium	/health endpoint is now unauthenticated and returns trimmed responses. /health endpoint is now unauthenticated and returns trimmed responses. Source: llm_adapter@2026-06-03 Confidence: low	—
Breaking	Medium	Tool responses are now JSON‑encoded strings instead of raw dicts. Tool responses are now JSON‑encoded strings instead of raw dicts. Source: llm_adapter@2026-06-03 Confidence: low	—
Feature	Medium	Adds OAuth/OIDC authentication providers on HTTP/SSE transports via FASTMCP_SERVER_AUTH. Adds OAuth/OIDC authentication providers on HTTP/SSE transports via FASTMCP_SERVER_AUTH. Source: llm_adapter@2026-06-03 Confidence: high	—
Feature	Medium	Official multi‑arch Docker images on GHCR (ghcr.io/clickhouse/mcp-clickhouse). Official multi‑arch Docker images on GHCR (ghcr.io/clickhouse/mcp-clickhouse). Source: llm_adapter@2026-06-03 Confidence: high	—
Bugfix	Medium	Long‑running queries no longer block other tool calls; concurrent calls are served asynchronously. Long‑running queries no longer block other tool calls; concurrent calls are served asynchronously. Source: llm_adapter@2026-06-03 Confidence: high	—
Bugfix	Medium	Tool responses now return valid JSON strings, avoiding MCP protocol validation errors. Tool responses now return valid JSON strings, avoiding MCP protocol validation errors. Source: llm_adapter@2026-06-03 Confidence: high	—

Full changelog

mcp-clickhouse v0.4.0

This release adds OAuth/OIDC authentication, official GHCR container images, and fixes concurrency and MCP protocol issues. It includes a few behavior changes (see Behavior changes section before upgrading).

Behavior changes

Auth modes are now mutually exclusive. Static token, FastMCP OAuth, and disabled mode can no longer be combined — configure exactly one. If you currently set more than one, pick a single mode.
/health is now unauthenticated in all modes (previously gated under static-token mode). Response bodies are trimmed to OK / a generic error string and no longer expose ClickHouse version or exception details. Update any monitoring that parsed the old body.
Tool responses are now JSON-encoded strings rather than raw dicts. This fixes MCP protocol validation errors, but the wire format clients receive has changed.

Added

OAuth/OIDC auth providers on HTTP/SSE transports via FASTMCP_SERVER_AUTH (Azure Entra, Google, GitHub, WorkOS, etc.). (#173, fixes #171)
Official multi-arch Docker images on GHCR, published automatically on every release: ghcr.io/clickhouse/mcp-clickhouse:0.4.0, :0.4, and :latest (linux/amd64 + linux/arm64). Swap your image reference from mcp/clickhouse to ghcr.io/clickhouse/mcp-clickhouse:latest — same env-var config, same entrypoint. (#174, #187)

Fixed

Long-running queries no longer block other tool calls. run_query and run_chdb_select_query now await their thread-pool futures asynchronously, so concurrent calls are served while a slow query is in flight. (#136, fixes #128)
Tool responses return valid JSON strings, avoiding MCP protocol validation errors on successful queries. (#154)

Docker image

docker pull ghcr.io/clickhouse/mcp-clickhouse:0.4.0

Full changelog: https://github.com/ClickHouse/mcp-clickhouse/compare/v0.3.0...v0.4.0

Breaking Changes

Auth modes (static token, FastMCP OAuth, disabled) are now mutually exclusive; exactly one must be configured.
`/health` endpoint is unauthenticated in all modes and its body is trimmed to simple strings, no longer exposing ClickHouse version or exception details.
Tool responses switched from raw dicts to JSON‑encoded string payloads.

View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track ClickHouse/mcp-clickhouse

Get notified when new releases ship.

About ClickHouse/mcp-clickhouse

ClickHouse database integration with schema inspection and query capabilities

All releases →