Gemini Cli Database

Gemini CLI Key ClickHouse License

httpUrl versus url

Gemini CLI's settings.json uses two different keys for two different transports, and they look close enough that people reach for the wrong one constantly. This is the number one misconfiguration for remote MCP servers in Gemini CLI:

Key in mcpServers	Transport it selects	Status
httpUrl	Streamable HTTP	The current MCP transport. Use this.
url	HTTP + SSE	The older two-endpoint transport, deprecated in the spec
command	stdio	Local process

The freebase.cloud endpoint serves streamable HTTP, so the key is httpUrl. Putting the endpoint under url gives you a server that Gemini will try to open as an SSE stream, fail on, and report as disconnected with an error that points at the network rather than at the config. If you have been handed a snippet that uses url for a remote HTTP server, it is either targeting a different client or it predates the transport change.

{
  "mcpServers": {
    "sky": {
      "httpUrl": "https://freebase.cloud/api/mcp/YOUR_TOKEN",
      "timeout": 5000
    }
  }
}

Install

The CLI writes that entry for you, correctly, if you use the subcommand:

gemini mcp add --transport http sky https://freebase.cloud/api/mcp/YOUR_TOKEN

--transport http is what maps to httpUrl. Then:

gemini mcp list

to confirm the server is registered, and inside an interactive session:

/mcp

which lists connected servers and the tools each one offers. /mcp is the fastest health check you have — it either shows four tools under sky, or it shows nothing and you have a config problem.

Getting the endpoint

Create a free account at freebase.cloud — no card. Make a session, choose an engine, then Settings → MCP → New Token, select the connection, and copy the URL. The token is a path segment, which is why there is no headers block and no env block in the config above. Guard the URL accordingly.

Where settings live

Scope	Path	Notes
User	~/.gemini/settings.json	Applies to every directory you run gemini in
Project	.gemini/settings.json	Checked in alongside the code, if you want the team to inherit it

gemini mcp add defaults to the project scope; pass the scope flag if you want it user-wide. A project file that contains a real token should be gitignored — Gemini CLI does not have VS Code's prompt-for-secret mechanism, so the value sits in the file as written.

The four tools

Named after the connection, so with sky you get:

sky_list_tables      what exists in the database
sky_query            read, in the engine's own query language
sky_store            write
sky_annotate_table   attach a description the model reads before planning a query

Gemini CLI asks before each tool call by default. If you are iterating, allowing the read tools for the session and leaving sky_store prompting is a reasonable split.

sky_annotate_table is worth using early. On a ClickHouse table it is the difference between the model treating a LowCardinality(String) column as free text and knowing it holds six station codes.

ClickHouse walkthrough

examples/meteor_events.clickhouse.sql builds a meteor-detection event store on ClickHouse 24.1.5 — radio stations logging reflections off ionised trails, which is a genuinely columnar workload: high insert volume, narrow rows, always aggregated by time.

It uses MergeTree with a sensible sort key, a SummingMergeTree rollup fed by a materialized view, LowCardinality for the station column, and analytical SQL that is specifically ClickHouse rather than portable ANSI — toStartOfHour, quantile, groupArray, WITH FILL to close gaps in a time series.

Statements go through sky_query and sky_store, or through the helper in examples/probe-mcp.sh:

./examples/probe-mcp.sh --sql "SELECT count() FROM meteor_events"

Then, in a Gemini session:

Using the sky tools, show me the hourly count of meteor events per station for the last two days, and flag any hour where one station saw more than double the median of the others.

The reason this is worth doing over MCP rather than over a REPL is that the model can iterate: inspect the schema, run a first aggregate, notice the gaps, and re-run with WITH FILL. That loop is the actual value, not the single query.

Not the consumer Gemini app

Worth stating plainly, because it comes up constantly: the consumer Gemini app does not support custom MCP servers. Neither the web app nor the mobile app will let you point at your own endpoint. Custom MCP connections in Google's hosted products are a Gemini Enterprise capability.

What you can use today, with the config above, is the Gemini CLI. That covers local development, scripted runs and CI, which is where a database connection is most useful anyway — but if you were hoping to add this to the chat app on your phone, that is not available.

Engines behind the same endpoint

The MCP config never changes; only the language inside sky_query does.

PostgreSQL 16.2 · MySQL 8.0.36 · MariaDB 11.3.2 · SQLite 3.45.1 · CockroachDB 23.2.4 · TimescaleDB 2.14.2 · MongoDB 7.0.4 · Redis 7.2.3 · Cassandra 4.1.4 (CQL) · DynamoDB · ClickHouse 24.1.5 · Elasticsearch 8.12.0 (query DSL) · Neo4j 5.17.0 (Cypher) · InfluxDB 2.7.4 (Flux) · Prometheus 2.50.1 (PromQL).

PostgreSQL, Redis and MongoDB also accept ordinary drivers on their native ports. ClickHouse and the rest are reached over HTTP and MCP.

Diagnosing a dead server

Ask /mcp first — it distinguishes "not registered" from "registered and failing", and those have completely different fixes.

If the server is not listed at all, the settings file is not being read: check you are running gemini from the directory containing .gemini/settings.json, or move the entry to ~/.gemini/settings.json, and validate the file with python3 -m json.tool.

If it is listed but shows no tools, run ./examples/probe-mcp.sh. That performs the handshake with plain curl, entirely outside the CLI. Four tools from the script and none in Gemini means the key is wrong — check for url where you meant httpUrl. No tools from the script either means the token is revoked, or it is valid but has no connection bound to it; both are fixed on the token screen.

If tools appear and calls hang, raise timeout. The default in the snippet above is 5000 ms, which is fine for list_tables and tight for a first query against a cold table.

If everything works in one directory and not another, you have two settings files and the project-scoped one is winning.

Free tier, honestly

Development, prototyping and small production workloads on the free tier. No published SLA, no uptime guarantee, no managed backup product. Export anything you would miss. The MCP channel is for the agent — your application should use a real client.

Repo contents

examples/
  settings.json                  the mcpServers block, with httpUrl
  probe-mcp.sh                   curl-based handshake, tool list, and --sql passthrough
  meteor_events.clickhouse.sql   MergeTree schema, rollup view, analytical queries
  README.md

Links

• Free ClickHouse cloud instance
• Connecting Claude to ClickHouse
• Engine list and sign-up
• Gemini CLI on GitHub
• MCP transports

---

freebase.cloud is an independent service and is not affiliated with Google LLC, ClickHouse, Inc., Anthropic, MongoDB, Inc., Redis Ltd., Neo4j, Inc. or the PostgreSQL Global Development Group.