ClickHouse MCP Server + Agentgateway Integration

Status: Design (pre-plan) Bead: hl-a44o Date: 2026-06-09

Overview

Deploy the ClickHouse MCP server (ghcr.io/clickhouse/mcp-clickhouse:0.4) in-cluster with two instances (read-only + read-write-no-drop), route both through the existing agentgateway at mcp-gw.fzymgc.house, and expose raw ClickHouse ports through Traefik for direct human access.

Architecture

                     ┌──────────────────────────────────────┐
                     │        agentgateway Gateway          │
                     │    mcp-gw.fzymgc.house (MetalLB)     │
                     │                                       │
Claude Code ──VK──►  │  /mcp/clickhouse-ro  ──token──►  ro  │
                     │  /mcp/clickhouse-rw  ──token──►  rw  │
                     └──────────────────────────────────────┘
                                    │
                                    │ cluster-internal
                                    ▼
                     ┌──────────────────────────────────────┐
                     │     clickhouse-mcp namespace          │
                     │                                       │
                     │  deploy/clickhouse-mcp-ro  :8000      │
                     │  deploy/clickhouse-mcp-rw  :8000      │
                     │                                       │
                     │  CLICKHOUSE_HOST=clickhouse.          │
                     │    clickstack.svc:8123                │
                     │  CLICKHOUSE_USER=mcp_readonly/rw      │
                     │  CLICKHOUSE_ALLOW_WRITE= true/false   │
                     └──────────────────────────────────────┘
                                    │
                                    ▼
                     ┌──────────────────────────────────────┐
                     │     clickstack namespace              │
                     │                                       │
-                     │  chi-cs-clickhouse-0-0 :8123 (HTTP)   │
-                     │  chi-cs-clickhouse-0-0 :9000 (native) │
+                     │  svc/clickhouse-headless :8123 (HTTP)  │
+                     │  svc/clickhouse-headless :9000 (native)│
                     │                                       │
                     │  Traefik IngressRoute                 │
-                     │  ch.fzymgc.house      → svc:8123      │
-                     │  ch-native.fzymgc.house → svc:9000    │
+                     │  ch.fzymgc.house      → headless:8123 │
+                     │  ch-native.fzymgc.house → headless:9000│
                     └──────────────────────────────────────┘

External Access (Traefik)

-Traefik terminates TLS at the edge (existing *.fzymgc.house wildcard cert), -forwards plain protocol internally: +Traefik terminates TLS at the edge, forwards plain protocol internally to the +ClickHouse headless service cs-clickstack-clickhouse-clickhouse-headless:

-	Hostname	Traefik Route Type	Backend Port	Protocol	Client Example
-	`ch.fzymgc.house`	`IngressRoute`	8123	HTTP	`curl`, Tabix, DBeaver HTTP
-	`ch-native.fzymgc.house`	`IngressRouteTCP`	9000	Native TCP	`clickhouse-client --host ch-native.fzymgc.house --port 443 --secure`
+	Hostname	Traefik Route Type	Backend	Port	Client Example
+	----------	-------------------	---------	------	----------------
+	`ch.fzymgc.house`	`IngressRoute`	`cs-clickstack-clickhouse-clickhouse-headless`	8123	`curl`, Tabix, DBeaver HTTP
+	`ch-native.fzymgc.house`	`IngressRouteTCP`	`cs-clickstack-clickhouse-clickhouse-headless`	9000	`clickhouse-client --host ch-native.fzymgc.house --port 443 --secure`

No new DNS entries needed — both hostnames are covered by the existing -*.fzymgc.house wildcard. No new cert-manager certificates needed. +*.fzymgc.house wildcard. + +TLS certificate: A new cert-manager Certificate resource is needed in the +clickstack namespace (secretName: ch-tls, DNS names: ch.fzymgc.house + +ch-native.fzymgc.house, issuer: cloudflare-acme-issuer ClusterIssuer). +Wildcard certs are namespace-scoped — the existing one lives in traefik only. +The IngressRoute and IngressRouteTCP both reference ch-tls.

ClickHouse Users

Two dedicated users provisioned via a one-shot PostSync Job:

User	Grants	Used by
`mcp_readonly`	`SELECT ON .`	`clickhouse-mcp-ro`
`mcp_readwrite`	`SELECT, INSERT, ALTER, CREATE ON .` (no DROP/TRUNCATE)	`clickhouse-mcp-rw`

Passwords stored in Vault at fzymgc-house/cluster/clickstack:

mcp_readonly_password
mcp_readwrite_password

The provisioning Job is an ArgoCD PostSync hook in the clickstack namespace (ensures ClickHouse exists before user creation).

MCP Server Deployments

Image: ghcr.io/clickhouse/mcp-clickhouse:0.4 (multi-arch)

New ArgoCD Application: clickhouse-mcp → namespace clickhouse-mcp

Two Deployment+Service pairs, identical except for user and write flag:

Setting	`clickhouse-mcp-ro`	`clickhouse-mcp-rw`
`CLICKHOUSE_USER`	`mcp_readonly`	`mcp_readwrite`
`CLICKHOUSE_ALLOW_WRITE_ACCESS`	`false`	`true`
`CLICKHOUSE_ALLOW_DROP`	`false`	`false`

Shared settings (both instances):

CLICKHOUSE_HOST: clickhouse.clickstack.svc.cluster.local
CLICKHOUSE_PORT: 8123
CLICKHOUSE_SECURE: false (cluster-internal, plain HTTP)
CLICKHOUSE_MCP_SERVER_TRANSPORT: http
CLICKHOUSE_MCP_BIND_HOST: 0.0.0.0
CLICKHOUSE_MCP_BIND_PORT: 8000
CLICKHOUSE_MCP_AUTH_TOKEN: sourced from clickhouse-mcp-auth ExternalSecret

ExternalSecrets in clickhouse-mcp namespace:
clickhouse-mcp-creds → sources mcp_readonly_password + mcp_readwrite_password from fzymgc-house/cluster/clickstack
clickhouse-mcp-auth → sources clickhouse_mcp_auth_token from fzymgc-house/cluster/agentgateway

NetworkPolicy: Allow ingress from agentgateway namespace on port 8000.

App config path: argocd/app-configs/clickhouse-mcp/ (kustomize) Cluster app path: argocd/cluster-app/templates/clickhouse-mcp.yaml

Agentgateway Integration

New file: argocd/app-configs/agentgateway/mcp-clickhouse.yaml

For each of ro and rw:

AgentgatewayBackend → cluster-local Service (clickhouse-mcp-{ro,rw}.clickhouse-mcp.svc.cluster.local:8000)
HTTPRoute at /mcp/clickhouse-ro and /mcp/clickhouse-rw on the mcp-gw listener
AgentgatewayPolicy apiKeyAuthentication — VK gating, mode: Strict
AgentgatewayPolicy backend.auth.secretRef — injects Authorization: Bearer <token> upstream (same token for both instances)

Modified files:

argocd/app-configs/agentgateway/kustomization.yaml — add mcp-clickhouse.yaml
argocd/app-configs/agentgateway/secrets.yaml:
- New ExternalSecret agentgateway-mcp-clickhouse → templates clickhouse_mcp_auth_token as Authorization: Bearer <token>
- agentgateway-vkeys — add clickhouse-ro and clickhouse-rw entries

Vault Changes

fzymgc-house/cluster/clickstack — two new properties:

vault kv patch fzymgc-house/cluster/clickstack \
  mcp_readonly_password="$(openssl rand -base64 24)" \
  mcp_readwrite_password="$(openssl rand -base64 24)"

fzymgc-house/cluster/agentgateway — three new properties:

vault kv patch fzymgc-house/cluster/agentgateway \
  clickhouse_mcp_auth_token="$(openssl rand -base64 32)" \
  vk_clickhouse_ro="vk-ro-$(openssl rand -hex 16)" \
  vk_clickhouse_rw="vk-rw-$(openssl rand -hex 16)"

MCP Client Configuration

{
  "mcp-clickhouse-ro": {
    "type": "http",
    "url": "https://mcp-gw.fzymgc.house/mcp/clickhouse-ro",
    "headers": { "Authorization": "Bearer <vk_clickhouse_ro>" }
  },
  "mcp-clickhouse-rw": {
    "type": "http",
    "url": "https://mcp-gw.fzymgc.house/mcp/clickhouse-rw",
    "headers": { "Authorization": "Bearer <vk_clickhouse_rw>" }
  }
}

Files Changed

New files

docs/engineering/specs/2026-06-09-clickhouse-mcp-agentgateway-design.md
argocd/app-configs/clickhouse-mcp/namespace.yaml
argocd/app-configs/clickhouse-mcp/deployment.yaml
argocd/app-configs/clickhouse-mcp/service.yaml
argocd/app-configs/clickhouse-mcp/external-secret.yaml
argocd/app-configs/clickhouse-mcp/networkpolicy.yaml
argocd/app-configs/clickhouse-mcp/kustomization.yaml
argocd/cluster-app/templates/clickhouse-mcp.yaml
argocd/app-configs/agentgateway/mcp-clickhouse.yaml
argocd/app-configs/clickstack/ingressroute-ch-http.yaml
argocd/app-configs/clickstack/ingressroute-ch-native.yaml +- argocd/app-configs/clickstack/certificate-ch.yaml
argocd/app-configs/clickstack/user-provisioning-job.yaml (PostSync hook)

Modified files

argocd/app-configs/agentgateway/kustomization.yaml
argocd/app-configs/agentgateway/secrets.yaml
argocd/app-configs/clickstack/kustomization.yaml +- argocd/app-configs/velero/backup-schedule.yaml — add clickhouse-mcp to excludedNamespaces (stateless, Git-recreatable)

ClickStack runbook: docs/operations/clickstack.md
Agentgateway ADR: docs/adr/hl-jd4-agentgateway.md (and superseding hl-m3c)
ClickHouse MCP server: https://github.com/ClickHouse/mcp-clickhouse

ClickHouse MCP Server + Agentgateway Integration