# Connect ClickHouse to your AI client

> Connect ClickHouse to Bonnard through a read-only user and an IP allowlist, the first step to querying it from Claude, ChatGPT or another AI client.

Updated: 2026-10-12

To chart ClickHouse data in Claude, ChatGPT or another AI client, connect it here, then create an app on it.
Bonnard reads ClickHouse through a read-only user, so your apps query only what you grant.

[Video: Connecting ClickHouse: the Data page, the ClickHouse form, Test & connect, the tenancy choice, and Connection saved]

## Requirements

- The Admin role in your Bonnard workspace.
- A ClickHouse user that can create users and grant privileges.
- A ClickHouse server whose HTTP interface is reachable from the internet.

## 1. Create a read-only user

Bonnard connects as this user. Agents can query only the tables it can read.

```sql
-- A user that can log in, with no privileges yet
CREATE USER mcp_reader IDENTIFIED BY '<password>';

-- Run this line once for each database apps should query
GRANT SELECT ON <database>.* TO mcp_reader;
```

Replace `<password>` and `<database>` with your own. The grant covers tables you add to the database later.

## 2. Allow Bonnard's IP addresses

If your database limits who can connect, allow Bonnard's IP addresses on port `8443` (HTTPS) or `8123` (HTTP). The
connect form lists them under **Allow our IP addresses**. Bonnard cannot reach databases on a private network. On
ClickHouse Cloud, add them to the IP access list in the service's settings.

## 3. Add the connection

1. In the console at `app.bonnard.ai`, select **Data**, then **ClickHouse**.
   [Image: The Data page with ClickHouse under Databases]
2. Enter a **Connection name** and the user's details from the table below.
   [Image: The ClickHouse connection form]
3. Select **Test & connect**. Bonnard logs in as the user and reads the tables it can see.

Table: ClickHouse connection fields

| Field | Enter |
| --- | --- |
| **Connection name** | A name for this database in Bonnard, such as `Production`. |
| **Protocol** | Keep `https`. Choose `http` only for a self-managed server without TLS. |
| **Host** | The server's public hostname, such as `abc.eu-west-1.aws.clickhouse.cloud`, without `https://` or a port. |
| **Port** | `8443`, or `8123` with `http`. Changing **Protocol** does not change it. |
| **Database** | The database to read. If each tenant (the customer a caller belongs to) has its own database, enter one of them. |
| **User** and **Password** | The read-only user from step 1, such as `mcp_reader`, in place of `default`. |
| **CA certificate (PEM)** | Leave it empty for ClickHouse Cloud. For a self-managed server with a private CA, paste its bundle. |

## 4. Choose the tenancy

Choose how callers see the data, then select **Save & continue**.

Table: Tenancy options

| Option | Use it when |
| --- | --- |
| **No tenancy** | Every caller should see the same data. |
| **Database per tenant** | Each tenant's tables sit in their own database, named by a pattern such as `customer_{tenant}`. |

[Image: The tenancy step for ClickHouse]

**Connection saved** shows the number of tables discovered.

[Image: Connection saved, with the tables discovered]

## Troubleshooting

- `Host resolves to a private or reserved address.` Use the public hostname. Bonnard cannot reach private networks.
- The test times out. Check that Bonnard's IP addresses are allowed (step 2).
- `Connected, but introspect failed: <message>` The user cannot read the table list. Fix what the message names.
- A table is missing. Grant `SELECT` on it, then select **Re-introspect** on the database's **Tables** tab.
- The test fails with a TLS or socket error. Check that **Protocol** and **Port** match: `https` with `8443`, `http`
  with `8123`. The native ports, `9000` and `9440`, do not work.
- Any other error is ClickHouse's own message. Check the field it names, then select **Test & connect** again.

## Charts in your AI client

[Create an app](https://bonnard.ai/docs/apps/create-an-app.md) on this database, so AI clients such as Claude and ChatGPT can query it and draw charts.