Free Mongodb

MCP MongoDB Transport License

The thing that keeps breaking

You point a model at some source — an inbox, a scraper, a batch of PDFs — and ask it to pull out structured records. Run one gives you {title, host, published}. Run two decides host should be an array because this episode had two of them. Run three adds sponsors[], because it noticed sponsors exist. Nothing is wrong with any of those three shapes. They're all reasonable readings of the same messy input.

If the sink is a relational table, that's three migrations and a stalled agent. If the sink is a JSON file on disk, you have a JSON file on disk, which is not a database and will not be one at 40k records.

A document store absorbs this. Insert whatever shape you have, add indexes when the access patterns settle, add a $jsonSchema validator when you actually know what "valid" means. This repo wires MongoDB up to an MCP client so a model can do that itself — and the resulting data is still readable by mongosh, Mongoose, PyMongo and anything else that speaks the MongoDB wire protocol, because it's a real MongoDB 7.0.4 server on the other end.

What's in here

examples/
  seed-catalogue.mjs      Node.js — insert a podcast catalogue over mongodb://
  aggregate-shows.mjs     Node.js — the aggregation pipeline the model would write
  mcp-call.sh             bash + curl — raw JSON-RPC against the MCP endpoint
mcp.json                  drop-in config for Claude Code / project scope

Getting a connection

The MongoDB engine page hands out free MongoDB 7 instances with both a mongodb:// URI and an MCP endpoint pointing at the same data. No credit card, no cluster tier selection.

1. Sign up and create a session with the MongoDB engine.
2. Name the connection. This repo assumes you called it catalog — the MCP tool names are derived from that name, so pick something you'll recognise in a tool list.
3. Settings → MCP → New Token, select the connection, copy the URL. It looks like https://freebase.cloud/api/mcp/YOUR_TOKEN.

The token sits in the URL path. There is no Authorization header to configure anywhere, which is why this works in clients that don't let you set headers.

Claude Code

claude mcp add --transport http catalog https://freebase.cloud/api/mcp/YOUR_TOKEN

Add --scope project to write .mcp.json into the repo instead of your user config. The committed mcp.json here shows the shape:

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

The "type" field is not optional in Claude Code — a bare url entry is a hard startup error. "streamable-http" is accepted as an alias for "http".

Claude Desktop, Claude web, Cowork

UI only: Settings → Connectors → Add custom connector, paste the URL, Add. Then enable it per conversation with the + button in the composer. Note that claude_desktop_config.json has no support for remote HTTP servers — if you find a tutorial telling you to add a url key there, it's out of date. Free tier accounts can have one custom connector at a time. The dialog is walked through step by step in the Claude setup guide.

Everything else

Client	Where	Key that matters
Cursor	.cursor/mcp.json	plain url, no type
VS Code / Copilot Chat	.vscode/mcp.json	top-level servers, not mcpServers
Windsurf	~/.codeium/windsurf/mcp_config.json	serverUrl
Zed	settings.json	context_servers
Cline	its MCP settings	"type": "streamableHttp" (camelCase)
Roo Code	.roo/mcp.json	"type": "streamable-http" (kebab-case)
Gemini CLI	settings.json	httpUrl — url means SSE and will fail
ChatGPT	Settings → Apps → developer mode	Auth: None, then Scan Tools

One caveat on the ChatGPT row: developer mode covers the paid and workspace plans, and full write access is still being rolled out to Business, Enterprise and Edu. Reading is the part you can rely on today.

The tools you get

Four, prefixed with the connection name you chose in the dashboard:

Tool	Arguments	Notes
catalog_query	query	A MongoDB JSON query, not SQL
catalog_store	table, rows[], mode	mode is append (default) or replace
catalog_list_tables	—	Collections with document counts, fields, annotations
catalog_annotate_table	table, description, format	Persisted; read back on reconnect

catalog_annotate_table is the one people skip and then miss. A collection called episodes with a field named dur tells the model nothing. An annotation saying "one row per published episode; dur is runtime in seconds, not minutes; guests is absent on solo episodes" survives across sessions and stops the model guessing. Do it once per collection, right after the first insert.

Worked example: a podcast catalogue

examples/seed-catalogue.mjs inserts three shows and a handful of episodes over the native driver, against whatever MONGODB_URI points at — a free instance is plenty for it. The documents are deliberately uneven — some episodes have guests, some have sponsors, one has a transcript.segments[] array — which is what real extraction output looks like.

Once seeded, this is the sort of thing that works from a chat window:

Which show has the highest average episode runtime, and how many episodes does each show have with at least one guest?

The model calls catalog_list_tables, sees episodes, and writes an aggregation. The pipeline in examples/aggregate-shows.mjs is the same one, runnable locally so you can check the arithmetic:

[
  { $match: { published: true } },
  { $group: {
      _id: "$showId",
      episodes: { $sum: 1 },
      avgRuntime: { $avg: "$durationSeconds" },
      withGuests: { $sum: { $cond: [{ $gt: [{ $size: { $ifNull: ["$guests", []] } }, 0] }, 1, 0] } }
  } },
  { $lookup: { from: "shows", localField: "_id", foreignField: "_id", as: "show" } },
  { $unwind: "$show" },
  { $sort: { avgRuntime: -1 } }
]

$ifNull around guests is the whole point of the exercise: the field genuinely doesn't exist on every document, and $size throws on a missing field rather than returning zero. Flexible schemas move the work into the query, they don't delete it.

The wire protocol is not a simulation

MCP is one door into the same instance. The other is mongodb://HOST:27017/DBNAME on port 27017, speaking OP_MSG. That means:

mongosh "mongodb://HOST:27017/media"

import mongoose from "mongoose";
await mongoose.connect(process.env.MONGODB_URI);

Mongoose middleware, virtuals and population work. mongodump and mongorestore work, because they're wire-protocol clients like everything else. Compound, text, wildcard and 2dsphere indexes are creatable and the query planner uses them. Multi-document transactions work inside a session.

This matters more than it sounds. A lot of "AI database" tooling gives the model an API and gives you nothing — you can't inspect what it wrote with your normal tools, and you can't get the data out without writing an exporter. Here the model writes documents and you read them with the shell you already know.

Adding structure back, later

The moment the shape stabilises, pin it down. Schema validation is per-collection and opt-in:

db.createCollection("episodes", {
  validator: { $jsonSchema: {
    bsonType: "object",
    required: ["showId", "title", "durationSeconds"],
    properties: {
      showId:          { bsonType: "objectId" },
      title:           { bsonType: "string", minLength: 1 },
      durationSeconds: { bsonType: "int", minimum: 0 },
      guests:          { bsonType: "array", items: { bsonType: "string" } }
    }
  } },
  validationLevel: "moderate"
});

validationLevel: "moderate" applies the rules to inserts and to updates of already-valid documents, and leaves the historical mess alone — which is usually what you want when you're retrofitting. Writes that violate the schema fail through the MCP endpoint exactly as they fail through the driver, and the model will see the error text and can correct itself.

Time-series collections are also available via db.createCollection() with the timeseries option, if the thing you're accumulating is metrics rather than records.

Limits, stated plainly

• The free tier is meant for development, prototyping and small production workloads. Size your expectations accordingly; there are no published SLAs, uptime figures or backup guarantees, and this README isn't going to invent any.
• MCP tool calls are request/response. Change streams and tailable cursors are a driver concern — use the mongodb:// URI for those.
• Give an agent catalog_store and it can write. If that's not what you want, keep the write tool out of the conversation, or point the connector at a session that only holds data you're willing to lose.
• Aggregations that scan the whole collection will be slow here for exactly the same reasons they'd be slow anywhere. Index first, then blame the network.

FAQ

Is this a MongoDB-compatible layer or MongoDB? MongoDB 7.0.4, reached over OP_MSG. Drivers don't know the difference because there isn't one to know.

Do I need to run any server from this repo? No. There is nothing to npm install and host — the service runs the MCP server; this repo is the configuration, the examples and the explanation.

Can two collections have different shapes for the same concept? Yes, and they will, and that's the trade. Annotate both.

What if I want the model to read but never write? Only expose the connection to conversations where writes are acceptable. There's no per-tool ACL in the client-side config for most clients — treat token distribution as the access control boundary.

See also

• Free MongoDB cloud instance
• Connecting Claude to MongoDB
• MongoDB 7.0 aggregation reference
• MCP transport specification
• freebase.cloud

---

MIT licensed. freebase.cloud is an independent service and is not affiliated with MongoDB, Inc., Anthropic, OpenAI, Google, or Microsoft.