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 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 AI client calls the local MCP endpoint with its token. Mongo Studio checks that the connection allows the call (None, Read, Read and write), then the capability (Off, Ask, Allow). Ask shows a request in the app that you allow or deny. Allowed calls run with the connection's saved credentials and return at most 100 documents. Every call is listed in Recent activity, and every change is kept in the History.okAllowAskAllowno accessOffDenyresult · at most 100 documents per call1AI clientClaude Code, Cursor,Codex, VS Code…2MCP endpoint127.0.0.1:47321/mcpBearer token · local only3ConnectionNone · Read ·Read & write4CapabilityOff · Ask · Allow,per kind of call5Runs the callwith the savedcredentialsRequest in Mongo StudioThe call, its target and a dry-run countAllow once · Always allow · DenyRefusedThe client is told why,and asks you insteadMongoDByour serverRecent activity and History, in SettingsEvery call shows there; every change is kept, with its code
An MCP call from the agent to MongoDB and back, and where it can stop.
  1. The agent calls the endpoint at http://127.0.0.1:47321/mcp with its Authorization header. No token, a wrong token, or a request that doesn't come from this computer is turned away.
  2. 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.
  3. 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.
  4. 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.
  5. The result goes back, capped: a read returns at most 100 documents per call.

Set it up

  1. Open Settings (the gear at the top right, or Ctrl ,) and go to MCP server.
  2. 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.
  3. 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).
  4. 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.
  5. Review What clients can do; the defaults are listed under Permissions.
  6. 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

terminal
claude mcp add --transport http --scope user mongo-studio http://127.0.0.1:47321/mcp \
  --header "Authorization: Bearer <your token>"

Cursor

~/.cursor/mcp.json
{
  "mcpServers": {
    "mongo-studio": {
      "url": "http://127.0.0.1:47321/mcp",
      "headers": {
        "Authorization": "Bearer <your token>"
      }
    }
  }
}

Codex

~/.codex/config.toml
[mcp_servers.mongo-studio]
url = "http://127.0.0.1:47321/mcp"

[mcp_servers.mongo-studio.http_headers]
Authorization = "Bearer <your token>"

VS Code

MCP: Open User Configuration
{
  "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:

generic MCP server entry
{
  "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:

CapabilityDefaultNotes
List databases, collections and indexesAllow (always on)Names, counts and index definitions. Everything else needs it.
Read documentsAllowfind, aggregate, count and explain, capped at 100 documents per call; also dry runs of writes and the history.
Insert, update and delete documentsAskEach request shows what it changes and a dry-run count before it runs. Includes upserts.
Create and drop collections and indexesOff
Run console scriptsAskA script can do anything the connection's database user can. Read-only and dry-run scripts need only Read access.
See saved connectionsAllowName, folder, environment and host. Never passwords or full connection strings.
Create and edit saved connectionsAskPasswords for new connections are typed by you, in the app.
Delete saved connectionsOff
Save queries and scriptsAllowThey land in Saved scripts, marked with the client's name.
See relations and find related documentsAllowRelated documents are read like any other, on connections it may read.
Propose and test relationsAllowWhat a client creates is a draft until you save it.

Connections clients may use

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:

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:

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.

ToolCapabilityWhat it does
list_connectionsSee saved connectionsThe connections the client may use: id, name, folder, environment, hosts, replica set and access level.
list_databasesBrowseDatabases of a connection.
list_collectionsBrowseCollections of a database.
list_indexesBrowseIndex definitions of a collection.
sample_schemaBrowseField names and types, from a small sample.
findRead documentsA query with filter, sort, projection, skip and limit; takes hint, max_time_ms and allow_disk_use.
aggregateRead documentsA pipeline, with hint, max_time_ms and allow_disk_use; one that writes ($out, $merge) needs Write.
countRead documentsHow many documents match a filter, with hint and max_time_ms.
explainRead documentsThe query plan of a find or a pipeline, to check index use.
insert_documentsWriteInsert up to 1,000 documents. With dry_run, lists those that would clash with an _id or a unique index.
update_documentsWriteUpdate the documents a filter matches, with upsert. With dry_run, only counts them.
delete_documentsWriteDelete the documents a filter matches. With dry_run, only counts them.
upsert_documentsWriteInsert or update up to 1,000 documents matched by key fields; only_insert leaves existing ones alone.
create_collectionCollections and indexesCreate a collection.
drop_collectionCollections and indexesDrop a collection.
create_indexCollections and indexesCreate an index.
drop_indexCollections and indexesDrop an index.
run_scriptScriptsRun a console script on a database, with read_only or dry_run if you like (see Scripts).
run_script_on_connectionsScriptsRun the same script on several connections, approved once, with a result per connection.
create_connectionEdit connectionsSave a new connection, without a password: you add it in the app. Can set its environment.
update_connectionEdit connectionsRename a connection, change its connection string or environment. Never takes one out of Production.
delete_connectionDelete connectionsDelete a saved connection.
save_scriptSave scriptsSave a query or script to Saved scripts, marked with the client's name.
list_relationsRelationsYour saved relations and drafts.
get_relationRelationsOne relation in full.
find_relatedRelations + ReadJoin through a relation: per document, a count, sums and the related documents.
test_relationRelationsThe relation's check report, on samples.
suggest_relation_linksPropose relationsWhich fields link two collections, from samples. Returns no document values.
create_relationPropose relationsSave a relation as a draft for you to review.
update_relationPropose relationsChange a draft.
delete_relationPropose relationsDelete a draft a client created.
get_taskAlways availableFollow a call that went on in the background: its result, or its status and what it printed.
cancel_taskAlways availableWithdraw a request still waiting for you, or stop a running call. Changes made before stay.
get_historyRead documentsThe 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.

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.

Security

Things to ask

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.