free-database-mcp-server

A reference for connecting any MCP client to a free cloud database. Fifteen engines, one endpoint shape, four tools per connection — with every engine's version and dialect, every client's config file and its exact key names, and a troubleshooting section built from the mistakes those key names cause. For a task-oriented walkthrough, the companion repo mcp-database-server-free is organised by job.

Jump to: engines · access model · tools · client setup · troubleshooting · picking an engine · examples

Engines

Port is the port that engine's protocol conventionally uses — it tells you which dialect and client tooling apply, not that a socket is listening. Each engine has a page at https://freebase.cloud/free-<slug>-cloud-instance (slugs: postgresql, mysql, mongodb, redis, sqlite, cassandra, dynamodb, clickhouse, elasticsearch, neo4j, mariadb, influxdb, prometheus, timescaledb, cockroachdb), plus a Claude guide at https://freebase.cloud/how-to-connect-claude-to-<slug> — for example the Elasticsearch instance page.

Related MCP server: mcp-database

How access works

Two distinct paths. Confusing them is the source of most setup trouble.

Native wire protocol — three engines. PostgreSQL, Redis and MongoDB accept real drivers over their real protocols: psql/libpq/Prisma/SQLAlchemy/pgx, redis-cli/ioredis/redis-py/Lettuce over RESP2, mongosh/Mongoose/the native driver over OP_MSG. Nothing is proxied or reshaped.

postgresql://freebase@HOST:5432/DBNAME    redis://HOST:6379    mongodb://HOST:27017/DBNAME

HTTP and MCP — all fifteen. The other twelve are reached through the hosted HTTP query API and through MCP. They speak their own dialects — CQL to Cassandra, Cypher to Neo4j, Flux to InfluxDB — but the transport is HTTP, not a raw socket. If you are wiring up an AI assistant this is the path you want regardless of engine, because it is identical for all of them:

https://freebase.cloud/api/mcp/YOUR_TOKEN

The token sits in the URL path, so no Authorization header appears anywhere in this document. The consequence: the URL is the credential. Don't commit it, don't paste it into a shared config, and rotate it from Settings → MCP if you do either. Transport is Streamable HTTP, which uses server-sent events internally for streamed responses — not the same thing as the deprecated HTTP+SSE transport with its separate /sse endpoint and POST /messages. Clients offering both: choose streamable.

The four tools

Four tools per connection, prefixed with the connection name you chose, not the engine name. A connection called db gives you:

Two engines add helpers: PostgreSQL gets pg_dump, pg_restore and pg_tables; SQLite gets sqlite_master and sqlite_version.

Use annotate_table. Highest-return five minutes in this document. A model that can list your tables still has to guess whether status holds 'active' or 1, whether amount_cents is cents or dollars, and whether deleted_at IS NULL is how you filter. One paragraph per table, written once, persists on the connection and applies to every conversation in every client using that token.

Quickstart

Sign up on the freebase.cloud dashboard (no card), create a session, pick an engine, then Settings → MCP → New Token → select the connection → copy the URL. Confirm it works before configuring any client — four tool names printed means anything still broken is configuration:

export FREEBASE_MCP_URL="https://freebase.cloud/api/mcp/YOUR_TOKEN"
python3 examples/list_tools.py

Client setup

Claude Desktop, Claude web, Cowork

UI only. Settings (⌘, / Ctrl+,) → Connectors (Customize → Connectors in newer builds) → Add custom connector → paste the URL → Add. Enable per conversation with the + button in the composer. Available on Free, Pro, Max, Team and Enterprise; Free accounts get one custom connector. claude_desktop_config.json has no representation for a remote HTTP MCP server — a post telling you to add one there predates streamable HTTP. The engine-specific version of these steps lives at how to connect Claude to PostgreSQL and its siblings for the other slugs.

Claude Code

claude mcp add --transport http db https://freebase.cloud/api/mcp/YOUR_TOKEN
#   --scope project  writes .mcp.json (commit it, minus the token) | --scope user = all projects

{ "mcpServers": { "db": { "type": "http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

streamable-http is accepted as an alias for http.

ChatGPT

Settings → Apps → Advanced settings → enable developer mode → Apps → Create → paste the endpoint → Auth None → Scan Tools → Create. Also check Settings → Connectors; OpenAI's two docs pages disagree about where this lives. Developer mode is documented for Pro, Plus, Business, Enterprise and Edu; full write access is currently rolling out to Business, Enterprise and Edu workspaces, so on some plans you get read-only tool access today.

OpenAI Responses API

{
  "model": "gpt-5.6",
  "tools": [{
    "type": "mcp",
    "server_label": "db",
    "server_description": "Free cloud database — query and store structured data.",
    "server_url": "https://freebase.cloud/api/mcp/YOUR_TOKEN",
    "require_approval": "never"
  }],
  "input": "List the tables in my database."
}

Cursor, Windsurf, VS Code, Zed

// ~/.cursor/mcp.json  or  .cursor/mcp.json     — NO "type" key
{ "mcpServers": { "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

// ~/.codeium/windsurf/mcp_config.json          — the key is serverUrl
{ "mcpServers": { "db": { "serverUrl": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

// .vscode/mcp.json                             — top-level key is "servers"
{
  "inputs": [{ "type": "promptString", "id": "fb-token", "description": "freebase.cloud MCP token", "password": true }],
  "servers": { "db": { "type": "http", "url": "https://freebase.cloud/api/mcp/${input:fb-token}" } }
}

// Zed settings.json                            — "context_servers", not "mcpServers"
{ "context_servers": { "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

Windsurf is now documented as "Devin Desktop" on docs.devin.ai; Enterprise users must enable MCP in settings first. In VS Code, Command Palette → MCP: Add Server builds the file, and the inputs block keeps the token out of it so the config stays committable.

Cline and Roo Code

Same transport, different spelling, no fallback between them.

// Cline — camelCase
{ "mcpServers": { "db": { "type": "streamableHttp", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN", "disabled": false, "autoApprove": [] } } }

// Roo Code, .roo/mcp.json — kebab-case
{ "mcpServers": { "db": { "type": "streamable-http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

Gemini CLI

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

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

In settings.json the key is httpUrl. Plain url means SSE — a misconfiguration that produces a server which appears to connect and then never returns a tool. The consumer Gemini app does not support custom MCP servers; that is Gemini Enterprise only.

Warp and n8n

Warp: Settings → AI → Manage MCP servers → "Streamable HTTP or SSE Server (URL)". Its paste box takes the server object alone, with no mcpServers wrapper:

{ "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } }

n8n: MCP Client Tool node (1.104.0+). Server Transport → HTTP Streamable, Endpoint → your URL, Authentication → None. The published docs page still shows only the old "SSE Endpoint" field; a current build of the node has the transport dropdown.

LangChain and LlamaIndex

from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({"db": {"transport": "http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN"}})
tools = await client.get_tools()

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
tools = await McpToolSpec(client=BasicMCPClient("https://freebase.cloud/api/mcp/YOUR_TOKEN")).to_tool_list_async()

mcp-remote (fallback only)

For a stdio-only client. Requires Node; its own README calls it experimental, so prefer native HTTP support wherever a client has it.

{ "mcpServers": { "db": { "command": "npx", "args": ["-y", "mcp-remote", "https://freebase.cloud/api/mcp/YOUR_TOKEN", "--transport", "http-only"] } } }

Troubleshooting configuration

Picking an engine

General-purpose relational → PostgreSQL (also the only engine with dump/restore helpers over MCP). An existing MySQL schema, PHP or WordPress → MySQL, or MariaDB for sequences, system-versioned tables and dynamic columns. Flexible documents and Mongoose → MongoDB. Cache, sessions, counters, rate limits, anything with a TTL → Redis. Small and schema-light → SQLite. Analytics over many rows → ClickHouse. Full-text search and ranking → Elasticsearch. Connected data, recommendations, agent memory → Neo4j. Metrics from devices → InfluxDB; from exporters and client libraries → Prometheus; next to relational tables → TimescaleDB. Wide-column at scale or learning CQL → Cassandra. Single-table design against AWS SDK code → DynamoDB. Distributed SQL, serializable by default → CockroachDB.

Examples

examples/list_tools.py prints every tool with its input schema — run it first. dialects.json holds write and read statements for all 15 engines, and examples/clients/ has ready-to-copy config files for ten clients.

node examples/roundtrip.mjs postgresql         # end-to-end write + read
node examples/roundtrip.mjs redis --keep       # leave the data behind

roundtrip.mjs writes bookmark records, reads them back and reports whether what came out matches what went in. Run it against two engines to see how much — and how little — changes between them.

Limits

The free tier is intended for development, prototyping and small production workloads. Engines run at the versions in the table above with their real feature sets: transactions on PostgreSQL, the aggregation pipeline on MongoDB, MergeTree on ClickHouse, Cypher and APOC on Neo4j, the aggregations framework on Elasticsearch. No SLA, uptime figure, backup guarantee or storage number is claimed here, because none is verified — the dashboard shows current quotas. Treat anything you cannot afford to lose as needing its own backup. For production scale, dedicated resources and a support relationship, the vendors' own managed offerings remain the right answer.

Links

freebase.cloud · MCP specification (revision 2026-07-28) · transport reference

Affiliation. freebase.cloud is an independent service and is not affiliated with Anthropic, OpenAI, Google, Microsoft, Anysphere, Codeium, Zed Industries, Warp, n8n, Oracle, MongoDB, Inc., Redis Ltd., Elasticsearch B.V., Neo4j, Inc., InfluxData, ClickHouse, Inc., the Apache Software Foundation, AWS, Timescale, Inc., Cockroach Labs or the PostgreSQL Global Development Group.