docs: clarify ClickHouse vs MCP environment variables - #211
Conversation
Make it explicit that CLICKHOUSE_SECURE/PORT/VERIFY configure the database HTTP(S) connection, not the MCP transport. Group env vars into database connection vs MCP server/transport sections, document HTTP vs native ports, and add common configuration pitfalls. Fixes ClickHouse#172
|
|
|
related: #97 |
joe-clickhouse
left a comment
joe-clickhouse
left a comment
There was a problem hiding this comment.
Hi @sankalpsthakur thanks! Appreciate the work. Hope you don't mind but I pushed a small followup that subtly changes the environment-variable grouping language so it accurately covers both client configuration and tool behavior. I also added the existing CLICKHOUSE_PROXY_PATH setting to make the config reference complete since I found that that one was missing entirely.
There was a problem hiding this comment.
Pull request overview
Restructures the README’s Environment Variables section to clearly separate ClickHouse database connection settings from MCP server/transport settings, addressing the confusion reported in #172 (notably around CLICKHOUSE_SECURE and port selection).
Changes:
- Adds a top-level grouping table and an IMPORTANT note clarifying which variables apply to ClickHouse vs MCP transport.
- Expands ClickHouse connection docs to distinguish HTTP interface ports (
8123/8443) from native TCP ports (9000/9440) and highlights common misconfigurations. - Splits configuration into clearer subsections and adds a “Common configuration pitfalls” list.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Ready on our side whenever you want to merge. |
Fixes #172
What
Restructures and clarifies the Environment Variables section of the README so users can distinguish:
CLICKHOUSE_HOST,CLICKHOUSE_SECURE,CLICKHOUSE_PORT, …)CLICKHOUSE_MCP_*, auth)Why
As reported in #172, variables like
CLICKHOUSE_SECUREare easy to misread as MCP/ingress TLS controls. Users running the server behind Kubernetes ingress have disabled them thinking they applied to the MCP connection, then hit opaque HTTP client errors when the process dialed ClickHouse over the wrong scheme.This PR:
8123/8443) vs native TCP ports (9000/9440)Companion code change: #212 adds actionable connection-failure hints for the same misconfiguration patterns (native port / TLS / scheme).
Validation