ClickHouse

View saved version →

---
name: clickhouse-best-practices
description: MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.
license: Apache-2.0
metadata:
  author: ClickHouse Inc
  version: "0.4.0"
---

# ClickHouse Best Practices

Comprehensive guidance for ClickHouse covering schema design, query optimization, data ingestion, and AI agent connectivity. Contains 31 rules across 4 main categories (schema, query, insert, agent), prioritized by impact.

> **Official docs:** [ClickHouse Best Practices](https://clickhouse.com/docs/best-practices)

## IMPORTANT: How to Apply This Skill

**Before answering ClickHouse questions, follow this priority order:**

1. **Check for applicable rules** in the `rules/` directory
2. **If rules exist:** Apply them and cite them in your response using "Per `rule-name`..."
3. **If no rule exists:** Use the LLM's ClickHouse knowledge or search documentation
4. **If uncertain:** Use web search for current best practices
5. **Always cite your source:** rule name, "general ClickHouse guidance", or URL

**Why rules take priority:** ClickHouse has specific behaviors (columnar storage, sparse indexes, merge tree mechanics) where general database intuition can be misleading. The rules encode validated, ClickHouse-specific guidance.

---

## Agent Connectivity & Query Workflow

Before querying ClickHouse, agents must establish a connection and follow the discovery workflow:

1. `rules/agent-connect-mcp.md` - Connection setup (MCP + CLI), credential discovery, output format selection
2. `rules/agent-discovery-schema.md` - **CRITICAL**: 7-step schema discovery workflow
3. `rules/agent-query-safety.md` - **CRITICAL**: LIMIT, timeouts, progressive exploration

**Every agent session should follow this sequence:**

1. **Connect** — establish connection via MCP or CLI (see `agent-connect-mcp`)
2. **Discover** — databases → tables → columns + comments → sort keys → skip indexes → sample → EXPLAIN
3. **Plan** — use sort key and skip index knowledge to write efficient WHERE clauses
4. **Execute** — run queries with LIMIT and timeouts
5. **Recover** — on timeout/memory errors, narrow filters and retry (see `agent-query-safety`)

### Subagent architecture notes

If your system dispatches ClickHouse tasks to specialized subagents:
- **Schema discovery + query execution**: any model — the steps are procedural
- **EXPLAIN analysis + query optimization**: benefits from mid-tier reasoning
- **Schema design review against all 28 rules**: benefits from mid-tier reasoning

---

## Review Procedures

### For Schema Reviews (CREATE TABLE, ALTER TABLE)

**Read these rule files in order:**

1. `rules/schema-pk-plan-before-creation.md` - ORDER BY is immutable
2. `rules/schema-pk-cardinality-order.md` - Column ordering in keys
3. `rules/schema-pk-prioritize-filters.md` - Filter column inclusion
4. `rules/schema-types-native-types.md` - Proper type selection
5. `rules/schema-types-minimize-bitwidth.md` - Numeric type sizing
6. `rules/schema-types-lowcardinality.md` - LowCardinality usage
7. `rules/schema-types-avoid-nullable.md` - Nullable vs DEFAULT
8. `rules/schema-partition-low-cardinality.md` - Partition count limits
9. `rules/schema-partition-lifecycle.md` - Partitioning purpose

**Check for:**
- [ ] PRIMARY KEY / ORDER BY column order (low-to-high cardinality)
- [ ] Data types match actual data ranges
- [ ] LowCardinality applied to appropriate string columns
- [ ] Partition key cardinality bounded (100-1,000 values)
- [ ] ReplacingMergeTree has version column if used

### For Query Reviews (SELECT, JOIN, aggregations)

**Read these rule files:**

1. `rules/query-join-choose-algorithm.md` - Algorithm selection
2. `rules/query-join-filter-before.md` - Pre-join filtering
3. `rules/query-join-use-any.md` - ANY vs regular JOIN
4. `rules/query-index-skipping-indices.md` - Secondary index usage
5. `rules/schema-pk-filter-on-orderby.md` - Filter alignment with ORDER BY

**Check for:**
- [ ] Filters use ORDER BY prefix columns
- [ ] JOINs filter tables before joining (not after)
- [ ] Correct JOIN algorithm for table sizes
- [ ] Skipping indices for non-ORDER BY filter columns

### For Insert Strategy Reviews (data ingestion, updates, deletes)

**Read these rule files:**

1. `rules/insert-batch-size.md` - Batch sizing requirements
2. `rules/insert-mutation-avoid-update.md` - UPDATE alternatives
3. `rules/insert-mutation-avoid-delete.md` - DELETE alternatives
4. `rules/insert-async-small-batches.md` - Async insert usage
5. `rules/insert-optimize-avoid-final.md` - OPTIMIZE TABLE risks

**Check for:**
- [ ] Batch size 10K-100K rows per INSERT
- [ ] No ALTER TABLE UPDATE for frequent changes
- [ ] ReplacingMergeTree or CollapsingMergeTree for update patterns
- [ ] Async inserts enabled for high-frequency small batches

---

## Output Format

Structure your response as follows:

```
## Rules Checked
- `rule-name-1` - Compliant / Violation found
- `rule-name-2` - Compliant / Violation found
...

## Findings

### Violations
- **`rule-name`**: Description of the issue
  - Current: [what the code does]
  - Required: [what it should do]
  - Fix: [specific correction]

### Compliant
- `rule-name`: Brief note on why it's correct

## Recommendations
[Prioritized list of changes, citing rules]
```

---

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rule Count |
|----------|----------|--------|--------|------------|
| 1 | Primary Key Selection | CRITICAL | `schema-pk-` | 4 |
| 2 | Data Type Selection | CRITICAL | `schema-types-` | 5 |
| 3 | JOIN Optimization | CRITICAL | `query-join-` | 5 |
| 4 | Insert Batching | CRITICAL | `insert-batch-` | 1 |
| 5 | Mutation Avoidance | CRITICAL | `insert-mutation-` | 2 |
| 6 | Partitioning Strategy | HIGH | `schema-partition-` | 4 |
| 7 | Skipping Indices | HIGH | `query-index-` | 1 |
| 8 | Materialized Views | HIGH | `query-mv-` | 2 |
| 9 | Async Inserts | HIGH | `insert-async-` | 2 |
| 10 | OPTIMIZE Avoidance | HIGH | `insert-optimize-` | 1 |
| 11 | JSON Usage | MEDIUM | `schema-json-` | 1 |
| 12 | Agent Schema Discovery | CRITICAL | `agent-discovery-` | 1 |
| 13 | Agent Query Safety | CRITICAL | `agent-query-` | 1 |
| 14 | Agent Connectivity + Formats | HIGH | `agent-connect-` | 1 |

---

## Quick Reference

### Schema Design - Primary Key (CRITICAL)

- `schema-pk-plan-before-creation` - Plan ORDER BY before table creation (immutable)
- `schema-pk-cardinality-order` - Order columns low-to-high cardinality
- `schema-pk-prioritize-filters` - Include frequently filtered columns
- `schema-pk-filter-on-orderby` - Query filters must use ORDER BY prefix

### Schema Design - Data Types (CRITICAL)

- `schema-types-native-types` - Use native types, not String for everything
- `schema-types-minimize-bitwidth` - Use smallest numeric type that fits
- `schema-types-lowcardinality` - LowCardinality for <10K unique strings
- `schema-types-enum` - Enum for finite value sets with validation
- `schema-types-avoid-nullable` - Avoid Nullable; use DEFAULT instead

### Schema Design - Partitioning (HIGH)

- `schema-partition-low-cardinality` - Keep partition count 100-1,000
- `schema-partition-lifecycle` - Use partitioning for data lifecycle, not queries
- `schema-partition-query-tradeoffs` - Understand partition pruning trade-offs
- `schema-partition-start-without` - Consider starting without partitioning

### Schema Design - JSON (MEDIUM)

- `schema-json-when-to-use` - JSON for dynamic schemas; typed columns for known

### Query Optimization - JOINs (CRITICAL)

- `query-join-choose-algorithm` - Select algorithm based on table sizes
- `query-join-use-any` - ANY JOIN when only one match needed
- `query-join-filter-before` - Filter tables before joining
- `query-join-consider-alternatives` - Dictionaries/denormalization vs JOIN
- `query-join-null-handling` - join_use_nulls=0 for default values

### Query Optimization - Indices (HIGH)

- `query-index-skipping-indices` - Skipping indices for non-ORDER BY filters

### Query Optimization - Materialized Views (HIGH)

- `query-mv-incremental` - Incremental MVs for real-time aggregations
- `query-mv-refreshable` - Refreshable MVs for complex joins

### Insert Strategy - Batching (CRITICAL)

- `insert-batch-size` - Batch 10K-100K rows per INSERT

### Insert Strategy - Async (HIGH)

- `insert-async-small-batches` - Async inserts for high-frequency small batches
- `insert-format-native` - Native format for best performance

### Insert Strategy - Mutations (CRITICAL)

- `insert-mutation-avoid-update` - ReplacingMergeTree instead of ALTER UPDATE
- `insert-mutation-avoid-delete` - Lightweight DELETE or DROP PARTITION

### Insert Strategy - Optimization (HIGH)

- `insert-optimize-avoid-final` - Let background merges work

### Agent Integration - Discovery (CRITICAL)

- `agent-discovery-schema` - Always discover schema before querying

### Agent Integration - Safety (CRITICAL)

- `agent-query-safety` - LIMIT, timeouts, progressive exploration

### Agent Integration - Connectivity + Formats (HIGH)

- `agent-connect-mcp` - MCP + CLI setup, credential discovery, output format selection

---

## When to Apply

This skill activates when you encounter:

- AI agent connecting to ClickHouse (MCP, CLI, HTTP)
- Agent workflow design for ClickHouse
- Schema discovery or exploration requests

- `CREATE TABLE` statements
- `ALTER TABLE` modifications
- `ORDER BY` or `PRIMARY KEY` discussions
- Data type selection questions
- Slow query troubleshooting
- JOIN optimization requests
- Data ingestion pipeline design
- Update/delete strategy questions
- ReplacingMergeTree or other specialized engine usage
- Partitioning strategy decisions

---

## Rule File Structure

Each rule file in `rules/` contains:

- **YAML frontmatter**: title, impact level, tags
- **Brief explanation**: Why this rule matters
- **Incorrect example**: Anti-pattern with explanation
- **Correct example**: Best practice with explanation
- **Additional context**: Trade-offs, when to apply, references

---

## Full Compiled Document

For the complete guide with all rules expanded inline: `AGENTS.md`

Use `AGENTS.md` when you need to check multiple rules quickly without reading individual files.

Referenced files: 36

View saved version →

---
name: clickhouse-js-node-coding
description: >
  Write idiomatic application code with the ClickHouse Node.js client
  (`@clickhouse/client`). Use this skill whenever a user is *building* against
  the Node.js client — configuring the client, pinging, inserting rows in JSON
  or raw formats, selecting and parsing results, binding query parameters,
  managing sessions and temporary tables, working with data types or
  customizing JSON parsing. Do NOT use for browser/Web client code.
---

# ClickHouse Node.js Client — Coding

Reference: https://clickhouse.com/docs/integrations/javascript

> **⚠️ Node.js runtime only.** This skill covers the `@clickhouse/client`
> package running in a **Node.js runtime** exclusively — including **Next.js
> Node runtime** API routes, React Server Components, Server Actions, and
> standard Node.js processes. Do **not** apply this skill to browser client
> components, Web Workers, **Next.js Edge runtime**, Cloudflare Workers, or
> any usage of `@clickhouse/client-web`. For browser/edge environments, the
> correct package is `@clickhouse/client-web`.

---

## How to Use This Skill

1. **Match the user's intent** to a row in the Task Index below and read the
   corresponding reference file before writing code. After reading it, scan any
   **Answer checklist** in that reference and make sure the final answer covers
   each relevant item; those checklists capture details users usually need but
   are easy to omit in short answers.
2. **Always import from `@clickhouse/client`** (never `@clickhouse/client-web`)
   and create a client with `createClient({ url })` or rely on
   supported defaults when appropriate. Close it with `await client.close()`
   preferably when it's no longer needed or during graceful shutdown for global resources.
3. **Prefer `JSONEachRow` for typical row inserts/selects** unless the user
   has already chosen another format or is streaming raw bytes (CSV / TSV /
   Parquet — see `examples/node/performance/`).
   **Note on `clickhouse_settings`:** settings passed to `createClient` are
   defaults for every request; they can be overridden per-call by passing
   `clickhouse_settings` directly to `insert()`, `query()`, or `command()`.
   Always mention this when the user configures settings at the client level.
4. **Always use `query_params` for user-supplied values** — never template-
   literal-interpolate them into SQL. See `reference/query-parameters.md`.
   **When answering a parameter-binding question, your response must
   explicitly name template-literal interpolation as a "SQL injection
   risk"** — even when the user only asked about syntax and did not raise
   security. The literal phrase "SQL injection" needs to appear; this is
   the most common mistake from PostgreSQL/MySQL users and the security
   framing is part of the correct answer, not an optional aside.
5. **Pick the right method for the job:**
   - `client.insert()` — write rows.
   - `client.query()` + `resultSet.json()` / `.text()` / `.stream()` — read
     rows that return data.
   - `client.command()` — DDL and other statements that don't return rows
     (`CREATE`, `DROP`, `TRUNCATE`, `ALTER`, `SET` in a session, etc.).
   - `client.exec()` — when you need the raw response stream of an arbitrary
     statement (rare in coding scenarios).
   - `client.ping()` — health check; returns `{ success, error? }`, never
     throws on connection failure.
6. **Note version constraints** when relevant. Examples:
   - `pathname` config option: client `>= 1.0.0`.
   - `BigInt` values in `query_params`: client `>= 1.15.0`.
   - `TupleParam` and JS `Map` in `query_params`: client `>= 1.9.0`.
   - Configurable `json.parse` / `json.stringify`: client `>= 1.14.0`.
   - `Time` / `Time64` data types: ClickHouse server `>= 25.6`.
   - `QBit` data type: ClickHouse server `>= 25.10` (GA on `26.x`).
   - `Dynamic` / `Variant` / new `JSON` types: ClickHouse server `>= 24.1` /
     `24.5` / `24.8` (no longer experimental since `25.3`).

---

## Task Index

Identify the user's task and read the matching reference file.

| Task                                                     | Triggers / symptoms                                                                                                                                                                                                             | Reference file                      |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Configure / connect the client**                       | Building a `createClient` call, URL parameters, `clickhouse_settings`, default format, custom HTTP headers                                                                                                                      | `reference/client-configuration.md` |
| **Compress requests / responses**                        | `compression`, gzip vs `zstd`, `{ codec }` option shape, Node version requirements, web limitations                                                                                                                             | `reference/compression.md`          |
| **Ping the server**                                      | Health checks, readiness probes, "is ClickHouse up?"                                                                                                                                                                            | `reference/ping.md`                 |
| **Choose an insert format**                              | "Which format should I use to insert?", JSON vs raw, `JSONEachRow` vs `JSON` vs `JSONObjectEachRow`                                                                                                                             | `reference/insert-formats.md`       |
| **Insert into a subset of columns / different database** | `insert({ columns })`, excluding columns, ephemeral columns, cross-DB inserts                                                                                                                                                   | `reference/insert-columns.md`       |
| **Insert values, expressions, dates, decimals**          | `INSERT … VALUES` with SQL functions, `Date`/`DateTime` from JS, `Decimal` precision, `INSERT … SELECT`; inserting a UUID into a `UInt128` column is tricky — use when the user is writing code that stores a UUID as `UInt128` | `reference/insert-values.md`        |
| **Async inserts (server-side batching)**                 | `async_insert=1`, fire-and-forget vs wait-for-ack                                                                                                                                                                               | `reference/async-insert.md`         |
| **Select and parse results**                             | `JSONEachRow` reads, `JSON` with metadata, picking a select format                                                                                                                                                              | `reference/select-formats.md`       |
| **Parameterize queries**                                 | Binding values, special characters / escaping, "SQL injection?", `{name: Type}` syntax                                                                                                                                          | `reference/query-parameters.md`     |
| **Sessions & temporary tables**                          | `session_id`, `CREATE TEMPORARY TABLE`, per-session `SET` commands                                                                                                                                                              | `reference/sessions.md`             |
| **Modern data types**                                    | `Dynamic`, `Variant`, `JSON` (object), `Time`, `Time64`, `QBit` (vector search)                                                                                                                                                 | `reference/data-types.md`           |
| **Custom JSON parse/stringify**                          | Plug in `JSONBig` / `safe-stable-stringify` / a `BigInt`-aware serializer                                                                                                                                                       | `reference/custom-json.md`          |

---

## Conventions used in answers

- Always show `import { createClient } from '@clickhouse/client'` (Node, never
  Web).
- Always `await client.close()` at the end of self-contained snippets; in
  long-running services, close on graceful shutdown.
- For inserts, prefer `format: 'JSONEachRow'` and `values: [...]` unless the
  user's scenario requires otherwise.
- For selects, prefer `await (await client.query({...})).json<RowType>()` for
  small / medium result sets; for bigger results suggest streaming.
- When showing parameter binding, use ClickHouse's native `{name: Type}`
  syntax — never `$1`, `?`, or `:name`.
- For DDL inside a cluster or behind a load balancer, set
  `clickhouse_settings: { wait_end_of_query: 1 }` on the `command()` call so
  the server only acknowledges after the change is applied. See
  https://clickhouse.com/docs/en/interfaces/http/#response-buffering.

---

## Out of scope

This skill covers day-to-day coding against `@clickhouse/client` (Node).
The following topics are intentionally **not** covered here:

- **Errors, hangs, type mismatches, proxy pathname surprises, log silence,
  socket hang-ups, `ECONNRESET`** → use the
  `clickhouse-js-node-troubleshooting` skill.
- **Streaming, Parquet, file streams, server-side bulk moves, progress
  streaming, async-insert throughput tuning** — see
  [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance).
- **TLS, RBAC / read-only users, deeper SQL-injection guidance** — see
  [`examples/node/security/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/security).
- **`CREATE TABLE` patterns, deployment-shaped connection strings,
  replication / sharding choices** — see
  [`examples/node/schema-and-deployments/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/schema-and-deployments).
- **Browser, Web Worker, Next.js Edge, Cloudflare Workers** — use
  `@clickhouse/client-web` and see
  [`examples/web/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/web).

---

## Still Stuck?

- [`examples/node/coding/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/coding) — the runnable corpus this skill is built on.
- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)
- [ClickHouse supported formats](https://clickhouse.com/docs/interfaces/formats)
- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)

Referenced files: 13

View saved version →

---
name: clickhouse-js-node-troubleshooting
description: >
  Troubleshoot and resolve common issues with the ClickHouse Node.js client
  (@clickhouse/client). Use this skill whenever a user reports errors, unexpected
  behavior, or configuration questions involving the Node.js client specifically —
  including socket hang-up errors, Keep-Alive problems, stream handling issues, data
  type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running
  query timeouts. Trigger even when the user hasn't precisely named the issue; vague
  symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js
  context are strong signals to use this skill. Do NOT use for browser/Web client issues.
---

# ClickHouse Node.js Client Troubleshooting

Reference: https://clickhouse.com/docs/integrations/javascript

> **⚠️ Node.js runtime only.** This skill covers the `@clickhouse/client` package running in a **Node.js runtime** exclusively — including **Next.js Node runtime** API routes, React Server Components, Server Actions, and standard Node.js processes. Do **not** apply this skill to browser client components, Web Workers, **Next.js Edge runtime**, Cloudflare Workers, or any usage of `@clickhouse/client-web`. For browser/edge environments, the correct package is `@clickhouse/client-web`.

---

## How to Use This Skill

1. **Identify the issue** — match symptoms to the Issue Index below and read the corresponding reference file.
2. **Lead with the diagnosis** — explain what's likely causing the issue before giving the fix.
3. **Note version constraints** — flag if a fix requires a minimum client version and check it against what the user provided.
4. **Ask only what's missing** — if the fix is version-dependent and you don't know their version, ask; otherwise help immediately.

---

## Issue Index

Identify the user's issue from the list below and read the corresponding reference file for detailed troubleshooting steps.

| Issue                                      | Symptoms                                                                                                                                                                     | Reference file                     |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **Socket Hang-Up / ECONNRESET**            | `socket hang up`, `ECONNRESET`, intermittent connection drops, long-running queries timing out                                                                               | `reference/socket-hangup.md`       |
| **Data Type Mismatches**                   | Large integers returned as strings, decimal precision loss, Date/DateTime insertion failures, `CANNOT_PARSE_INPUT_ASSERTION_FAILED` inserting a UUID into a `UInt128` column | `reference/data-types.md`          |
| **Read-Only User Errors**                  | Errors when using response compression with `readonly=1` users                                                                                                               | `reference/readonly-users.md`      |
| **Proxy / Pathname URL Confusion**         | Wrong database selected, requests failing behind a proxy with a path prefix                                                                                                  | `reference/proxy-pathname.md`      |
| **TLS / Certificate Errors**               | TLS handshake failures, certificate verification issues, mutual TLS setup                                                                                                    | `reference/tls.md`                 |
| **Compression Not Working**                | GZIP compression not activating for requests or responses                                                                                                                    | `reference/compression.md`         |
| **Logging Not Showing Anything**           | No log output, need custom logger integration                                                                                                                                | `reference/logging.md`             |
| **Query Parameters Not Interpolated**      | Parameterized queries not working, SQL injection concerns                                                                                                                    | `reference/query-params.md`        |
| **FORMAT Clause / `SHOW POLICIES` Errors** | Syntax error from a duplicate `FORMAT`, or `SHOW [ROW] POLICIES` failing even with a format provided                                                                         | `reference/query-format-clause.md` |

---

## Still Stuck?

- [JS client source + full examples](https://github.com/ClickHouse/clickhouse-js/tree/main/examples)
- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)
- [ClickHouse supported formats](https://clickhouse.com/docs/interfaces/formats)

Referenced files: 9

View saved version →

---
name: setup
description: Guides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble connecting to ClickHouse.
license: Apache-2.0
metadata:
  author: ClickHouse
---

# ClickHouse Plugin Setup

This plugin includes the [ClickHouse Cloud Remote MCP server](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp) at `https://mcp.clickhouse.cloud/mcp`. It provides secure, read-only access to your ClickHouse Cloud clusters.

## Setup Steps

1. **Install the plugin**: If the plugin is not installed yet, add the marketplace and install the plugin:

   ```bash
   codex plugin marketplace add ClickHouse/clickhouse-codex-plugin
   codex plugin add clickhouse@clickhouse-codex-plugin
   ```

2. **Authenticate the MCP server**: Installing the plugin makes the ClickHouse MCP server available to Codex, but it does not create ClickHouse OAuth credentials. Run:

   ```bash
   codex mcp login clickhouse
   ```

   This opens the ClickHouse MCP OAuth flow. Sign in with a ClickHouse account that has access to the organizations, services, databases, and tables you want Codex to inspect. You must also have [MCP enabled on your ClickHouse service](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp).

3. **Verify the MCP server is connected**: Check that the ClickHouse MCP server appears in your available MCP servers:

   ```bash
   codex mcp list
   ```

4. **Start a fresh Codex thread**: If you installed or authenticated while Codex Desktop was already open, start a new thread so the skills, MCP configuration, and credentials are loaded. If tools still do not appear, restart Codex Desktop.

5. **Test table access**: Ask:

   ```text
   Using ClickHouse, what tables do I have access to?
   ```

   or:

   ```text
   List my ClickHouse databases and tables.
   ```

## Troubleshooting

- **Server not appearing**: Run `codex mcp list`, then start a new Codex thread so the plugin's skills and MCP configuration are loaded. If it still does not appear, restart Codex Desktop.
- **Authentication errors**: Re-authenticate with `codex mcp login clickhouse`.
- **Connection timeouts**: Verify your network can reach `https://mcp.clickhouse.cloud`. The MCP server is a remote HTTP endpoint and requires internet access.

## Keeping queries fast

The MCP server runs queries against your live ClickHouse Cloud service. To keep interactions responsive and avoid long-running scans:

- Use `LIMIT` clauses to bound result sets.
- Prefer querying materialized views or pre-aggregated tables over raw scans of large tables.
- If a query is slow, break it into smaller, faster queries.

## What the MCP Server Provides

Once connected, the ClickHouse MCP server provides these tools:

### Organization & Service Management
- **get_organizations** — list all accessible ClickHouse Cloud organizations
- **get_organization_details** — details of a single organization
- **get_services_list** — list all services in an organization
- **get_service_details** — details of a single service

### Database Exploration
- **list_databases** — list all databases in a service
- **list_tables** — list tables in a database (supports `like`/`notLike` filtering)
- **run_select_query** — execute read-only SELECT queries

### ClickPipes
- **list_clickpipes** — list all ClickPipes for a service
- **get_clickpipe** — details of a specific ClickPipe

### Backups
- **list_service_backups** — list all backups for a service
- **get_service_backup_details** — details of a specific backup
- **get_service_backup_configuration** — backup schedule and retention settings

### Billing
- **get_organization_cost** — billing and usage cost data (max 31-day window)

All tools are read-only. See the [ClickHouse MCP docs](https://clickhouse.com/docs/use-cases/AI/MCP/remote_mcp) for details.

## Bundled Skills

Beyond MCP access, this plugin also bundles ClickHouse skills that activate automatically when relevant — no setup needed:

- **clickhouse-best-practices** — schema design, query optimization, and insert strategy rules
- **clickhouse-js-node-coding** — writing applications with the ClickHouse JavaScript (Node.js) client
- **clickhouse-js-node-troubleshooting** — troubleshooting the ClickHouse JavaScript (Node.js) client

Referenced files: 1