freebase.cloud

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- -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- — for example the Elasticsearch instance page.

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](https://freebase.cloud/free-sqlite-cloud-instance) 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

```json

{ "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" } } }

```json

// .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}" } } }

```json

// 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": [] } } }

```json

// 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 St