MCP server
Let AI agents on your computer browse, query and change your MongoDB databases through Mongo Studio, with the limits you choose: per kind of call, per connection, and with your approval where it matters.
What it is
The Model Context Protocol (MCP) is how AI coding agents talk to tools. Mongo Studio runs an MCP server inside the app, so an agent such as Claude Code, Cursor, Codex, VS Code or Windsurf can work with the MongoDB connections you saved, without you pasting connection strings or passwords into it.
- It's off until you turn it on, and it only runs while Mongo Studio is open.
- It's local. It listens on
127.0.0.1, and each request must carry a token only your computer knows. - You set the limits. Each kind of call is Off, Ask or Allow, and each connection is None, Read or Read & write.
- You see everything. Every call, allowed or not, is listed in Settings, and every change is kept in a history you can export.
It is a different thing from the built-in Assistant: the Assistant stays read-only and reads only the connections you allow in Assistant settings, whatever the MCP permissions say.
How a call flows
Every tool call an agent makes goes through the same checks, in this order. A refusal tells the agent why, and the server's instructions tell it not to retry but to ask you.
- The agent calls the endpoint at
http://127.0.0.1:47321/mcpwith itsAuthorizationheader. No token, a wrong token, or a request that doesn't come from this computer is turned away. - The connection's access decides what's possible. A connection set to None is invisible to the agent; Read allows looking; only Read & write lets writes through, whatever the capabilities say.
- The capability decides what happens. Off refuses, Allow runs, Ask stops and asks you in the app. On a connection marked Production, every change asks, whatever the capability says.
- The call runs on Mongo Studio's own connection to that server, opened with the saved credentials (and SSH tunnel), whether or not you have it open in the app. The agent never sees them.
- The result goes back, capped: a read returns at most 100 documents per call.
Set it up
- Open Settings (the gear at the top right, or Ctrl ,) and go to MCP server.
- Turn on Run the MCP server. It shows Listening on 127.0.0.1:47321. The port can be changed there if something else uses it.
- Under Connect a client, pick your agent and press Add to …: Mongo Studio writes the entry, token included, into that client's settings. Or copy the snippet and add it yourself (below).
- Under Connections clients may use, give the connections the agent needs Read, or Read & write for the ones it may change. They all start at None.
- Review What clients can do; the defaults are listed under Permissions.
- Restart your agent, or reload its MCP servers, and ask it something about your data.
Connect your client
Add to … does this for you. To do it by hand, copy the token from Settings (the eye shows it) and use the snippet for your client. Any client that speaks MCP over HTTP works with the generic JSON.
Claude Code
claude mcp add --transport http --scope user mongo-studio http://127.0.0.1:47321/mcp \
--header "Authorization: Bearer <your token>"Cursor
{
"mcpServers": {
"mongo-studio": {
"url": "http://127.0.0.1:47321/mcp",
"headers": {
"Authorization": "Bearer <your token>"
}
}
}
}Codex
[mcp_servers.mongo-studio]
url = "http://127.0.0.1:47321/mcp"
[mcp_servers.mongo-studio.http_headers]
Authorization = "Bearer <your token>"VS Code
{
"servers": {
"mongo-studio": {
"type": "http",
"url": "http://127.0.0.1:47321/mcp",
"headers": {
"Authorization": "Bearer <your token>"
}
}
}
}Windsurf and others
Windsurf reads ~/.codeium/windsurf/mcp_config.json; Add to Windsurf writes it. For any other client:
{
"type": "http",
"url": "http://127.0.0.1:47321/mcp",
"headers": {
"Authorization": "Bearer <your token>"
}
}Permissions
Two independent settings decide what an agent may do. A call needs both.
What clients can do
Each kind of call is Off (refused), Ask (you approve each one in the app) or Allow (runs). The defaults:
| Capability | Default | Notes |
|---|---|---|
| List databases, collections and indexes | Allow (always on) | Names, counts and index definitions. Everything else needs it. |
| Read documents | Allow | find, aggregate, count and explain, capped at 100 documents per call; also dry runs of writes and the history. |
| Insert, update and delete documents | Ask | Each request shows what it changes and a dry-run count before it runs. Includes upserts. |
| Create and drop collections and indexes | Off | |
| Run console scripts | Ask | A script can do anything the connection's database user can. Read-only and dry-run scripts need only Read access. |
| See saved connections | Allow | Name, folder, environment and host. Never passwords or full connection strings. |
| Create and edit saved connections | Ask | Passwords for new connections are typed by you, in the app. |
| Delete saved connections | Off | |
| Save queries and scripts | Allow | They land in Saved scripts, marked with the client's name. |
| See relations and find related documents | Allow | Related documents are read like any other, on connections it may read. |
| Propose and test relations | Allow | What a client creates is a draft until you save it. |
Connections clients may use
- None: the agent doesn't see the connection at all. Every saved connection starts here.
- Read: browsing and reading, and scripts run with
read_onlyordry_run. Connections an agent creates start at Read. - Read & write: writes, schema changes and scripts can reach it, if their capability allows.
The Always allowed list shows what you allowed permanently from a request, per connection, and lets you take it back.
Approving a call
When a call is set to Ask, a card appears at the bottom right of Mongo Studio:
- It names the client, what it wants to do and where: the connection, database and collection.
- A write shows what it changes and a dry-run count of the documents it would touch, before anything runs.
- Allow once runs this call. Always allow here stops asking for this kind of call on this connection. Deny refuses it.
- On a production connection the card says so, and doesn't offer Always allow.
- A request stays up to five minutes. Several requests queue, oldest first, and the status bar counts them. Mongo Studio plays a chime and comes to the front when one arrives (both can be turned off).
Long calls
Many agents give up on a call after about a minute, while a call can wait longer for your approval, or a script or an aggregation can simply take longer. So a call that hasn't finished after about 40 seconds answers right away with a task_id and goes on in the background. The answer tells the agent what is going on:
- Still getting ready: connecting to the server, or counting what the call would change. Nothing ran yet; a slow start usually means the server is hard to reach.
- Waiting for your approval: the request card is in Mongo Studio, and the agent should tell you to look at it.
- Still running: with the lines a script printed so far.
The agent follows it with get_task, which waits for the result, or stops it with cancel_task. It is told not to repeat the call, which would ask twice or write twice. Disconnecting a client or turning the server off stops its calls.
Tools
What an agent sees in its tool list. A tool whose capability is Off is left out of the list entirely.
| Tool | Capability | What it does |
|---|---|---|
list_connections | See saved connections | The connections the client may use: id, name, folder, environment, hosts, replica set and access level. |
list_databases | Browse | Databases of a connection. |
list_collections | Browse | Collections of a database. |
list_indexes | Browse | Index definitions of a collection. |
sample_schema | Browse | Field names and types, from a small sample. |
find | Read documents | A query with filter, sort, projection, skip and limit; takes hint, max_time_ms and allow_disk_use. |
aggregate | Read documents | A pipeline, with hint, max_time_ms and allow_disk_use; one that writes ($out, $merge) needs Write. |
count | Read documents | How many documents match a filter, with hint and max_time_ms. |
explain | Read documents | The query plan of a find or a pipeline, to check index use. |
insert_documents | Write | Insert up to 1,000 documents. With dry_run, lists those that would clash with an _id or a unique index. |
update_documents | Write | Update the documents a filter matches, with upsert. With dry_run, only counts them. |
delete_documents | Write | Delete the documents a filter matches. With dry_run, only counts them. |
upsert_documents | Write | Insert or update up to 1,000 documents matched by key fields; only_insert leaves existing ones alone. |
create_collection | Collections and indexes | Create a collection. |
drop_collection | Collections and indexes | Drop a collection. |
create_index | Collections and indexes | Create an index. |
drop_index | Collections and indexes | Drop an index. |
run_script | Scripts | Run a console script on a database, with read_only or dry_run if you like (see Scripts). |
run_script_on_connections | Scripts | Run the same script on several connections, approved once, with a result per connection. |
create_connection | Edit connections | Save a new connection, without a password: you add it in the app. Can set its environment. |
update_connection | Edit connections | Rename a connection, change its connection string or environment. Never takes one out of Production. |
delete_connection | Delete connections | Delete a saved connection. |
save_script | Save scripts | Save a query or script to Saved scripts, marked with the client's name. |
list_relations | Relations | Your saved relations and drafts. |
get_relation | Relations | One relation in full. |
find_related | Relations + Read | Join through a relation: per document, a count, sums and the related documents. |
test_relation | Relations | The relation's check report, on samples. |
suggest_relation_links | Propose relations | Which fields link two collections, from samples. Returns no document values. |
create_relation | Propose relations | Save a relation as a draft for you to review. |
update_relation | Propose relations | Change a draft. |
delete_relation | Propose relations | Delete a draft a client created. |
get_task | Always available | Follow a call that went on in the background: its result, or its status and what it printed. |
cancel_task | Always available | Withdraw a request still waiting for you, or stop a running call. Changes made before stay. |
get_history | Read documents | The history of changes, as Markdown or JSON, for the connections the client may read. |
The relation tools are explained in Relations › Relations over MCP.
Scripts
run_script runs JavaScript with the same built-in engine as Mongo Studio's console: most of mongosh's API, with await on every call. It has db.orders and db.getCollection(name), chained cursors (find(...).sort(...).limit(...).toArray(), forEach, for await),aggregate, countDocuments, distinct, inserts, updates, deletes,replaceOne, findOneAndUpdate, bulkWrite, createIndex,db.runCommand(), print and printjson.
- Options are never ignored. Every call takes mongosh's options (
upsert,arrayFilters,hint,maxTimeMS…); one the engine doesn't support is an error, not a silent no-op. - Types are kept.
new Date(),ObjectId(),NumberLong(),UUID()and regexes are stored as their BSON types. - timeout_ms is a hard limit. Past it the script stops, the query it waits on too, and the agent gets what it printed so far, to resume from there.
- read_only refuses every write, so a report can run on a connection shared as Read.
- dry_run makes no write: each one is counted ("12 documents would change") and reported instead. Reads later in the script don't see those writes, so treat it as an estimate.
- A script that changed data reports what it changed: inserted, modified, upserted, deleted.
run_script_on_connections runs one script on several connections, one after the other: the same fix on every tenant's cluster, say. You approve it once for all of them, and the agent gets each connection's result and output. A failure on one doesn't stop the others unless it asks for stop_on_error.
Production connections
In a connection's form, Environment marks it Development, Testing, Staging or Production. It shows as a tag next to its name in the sidebar, PROD in red, and agents see it in list_connections, so they can tell production from QA.
On a Production connection, every change an agent makes waits for you: writes, schema changes, scripts that may write, edits to the connection. That holds even where the capability is set to Allow, or you answered Always allow before, and the card doesn't offer Always allow. An agent can mark a connection Production, but only you can take it out, in the app. The check is Always ask before changes on production in Settings › MCP server, on by default.
History
Mongo Studio keeps a history of what agents changed, on your computer: every write, schema change, connection edit and script that ran, with its code, when, on which connection and environment, who approved it, how long it took, and what it changed or why it failed. Reads and refused calls aren't kept. It holds the last 5,000 entries.
- Export… in Settings › MCP server saves it as Markdown, one section per call with its code, ready to attach to a ticket or a pull request, or as JSON.
- Agents can read it back with
get_history, for the connections they may read, to write the change log themselves. - Clear… deletes it, and Keep a history of changes turns it off.
Security
- The server binds to
127.0.0.1only and checks theHostandOriginof every request, so a web page can't reach it through your browser. - Every request needs the bearer token. A request without it, or with another, is refused before anything else.
- It runs only while the app is open and the switch is on. Turning it off disconnects every client; Disconnect next to a client drops just that one.
- Reads are capped at 100 documents per call, and writes can be held for your approval with a dry run.
- Changes on production connections always wait for you, and an agent can't lift that.
- The history stays on your computer, in the app's data folder; it contains the code and filters agents ran, so clear it if that matters.
Things to ask
- "Which collections in shop have no index on the fields their queries filter by?"
- "Count the orders from last week by status, on the Production EU connection."
- "Find users created today without an email and show me five of them."
- "Write an aggregation that totals revenue per month and save it to my scripts."
- "Mark the orders in this list as shipped" (a write: you approve it, after seeing the dry-run count).
- "Build last month's credit report on the production connection" (a read-only script, on a connection shared as Read).
- "Run this fix on the four regional clusters, dry run first."
- "Write up what you changed today for the ticket" (from the history).
Troubleshooting
"Port 47321 is already in use"
Another program, or another copy of Mongo Studio, has the port. Pick another port in Settings, then update the URL in your client (Add to … again does it).
The agent doesn't list Mongo Studio's tools
Check that the switch is on and shows Listening, then restart the agent or reload its MCP servers. In Claude Code, claude mcp list shows whether it's connected. A wrong token shows as an authorization error.
A call is refused
Either the connection's access is too low (a write on a Read connection) or the capability is Off. Recent activity shows which call and why. For a report on a Read connection, the agent can run its script with read_only.
The agent says the call is waiting for you
Look for the request card in Mongo Studio. The agent follows the call with get_task; after five minutes without an answer, the request is refused.
"Lost the connection to …"
The server stopped answering mid-call: a VPN that dropped, a network change, an SSH server that closed the tunnel. Mongo Studio reconnects on the next call and retries reads once by itself. A write that lost its connection isn't retried, since it may have been applied: check before running it again.