MongoDB exploration with agent-mongo

agent-mongo is a read-only CLI binary on $PATH. Default output is NDJSON — one JSON record per line on stdout. List commands emit one record per item, then @-prefixed metadata lines ({"@meta": ...} for context, {"@pagination": ...} for paging). Errors go to stderr as one JSON line {"error": "...", "fixable_by": "agent"|"human"|"retry", "hint": "..."} with a non-zero exit.

fixable_by tells you who resolves the error: agent — fix your input and retry; human — needs the user (auth, a GUI dialog); retry — transient, run it again.

Quick start (connections)

Set up a connection:

agent-mongo connection add local "mongodb://localhost:27017/myapp" --default
agent-mongo connection test

For authenticated connections, store credentials separately — prefer --form (native OS dialog; the secret never enters agent context) over --username/--password flags:

agent-mongo credential add acme --form
agent-mongo connection add prod "mongodb+srv://cluster.example.net/myapp" --credential acme --default

A user:pass embedded in the URI is automatically extracted into a stored credential named after the connection alias (don't combine with --credential — that's an error). If a credential with that alias already exists holding different values, the add is refused; follow the error's hint (rotate via credential add --form, or reference the existing credential with --credential). connection list always redacts passwords in connection strings.

Some deployments authenticate against an identity provider instead (MONGODB-OIDC) — see [references/auth.md](references/auth.md) to set one up.

If any command fails with fixable_by: human naming credential login, stop and ask the person to run it. No retry fixes it and no agent can complete it: the login is deliberately human-only. This is the one auth failure that is not a bug to work around.

Exploring a database

agent-mongo database list                                # all databases with sizes
agent-mongo collection list myapp                        # all collections in myapp
agent-mongo collection schema myapp users                # infer schema from samples
agent-mongo collection schema myapp users --depth 2      # limit nesting depth
agent-mongo collection schema myapp events --limit 50    # paginate large schemas
agent-mongo collection schema myapp events --limit 50 --skip 50  # next page
agent-mongo collection indexes myapp users               # index key patterns (verbatim specs)
agent-mongo collection stats myapp orders                # document count, sizes
agent-mongo database stats myapp                         # database-level statistics

Querying documents

agent-mongo query find myapp users --filter '{"age":{"$gte":21}}' --limit 10
agent-mongo query find myapp orders --sort '{"createdAt":-1}' --projection '{"status":1,"total":1}'
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e      # by _id (auto-detects ObjectId)
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e --projection '{"name":1,"email":1}'
agent-mongo query count myapp orders --filter '{"status":"pending"}'
agent-mongo query sample myapp users --size 10                    # random documents
agent-mongo query sample myapp users --size 10 --filter '{"status":"active"}'  # filtered sample
agent-mongo query distinct myapp orders status                    # unique values

query find emits one record per document, then a {"@pagination": {"hasmore": ..., "totalitems": ...}} line — hasmore means more documents match beyond the limit, totalitems is the full matching count.

All JSON arguments (--filter, --sort, --projection, --pipeline) accept MongoDB Extended JSON for BSON types:

agent-mongo query find myapp events --filter '{"createdAt":{"$gt":{"$date":"2026-01-01T00:00:00Z"}}}'
agent-mongo query find myapp users --filter '{"_id":{"$oid":"665a1b2c3d4e5f6a7b8c9d0e"}}'

Aggregation

agent-mongo query aggregate myapp orders '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp orders --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp events '[{"$match":{"type":"purchase"}},{"$group":{"_id":"$userId","total":{"$sum":"$amount"}}}]'

Pipeline can be passed as a positional argument, via --pipeline flag, or piped via stdin.

Write stages ($out, $merge) are rejected — the CLI is strictly read-only.

Output format

Default is NDJSON (-f jsonl). Switch with -f/--format:

agent-mongo database list -f json     # pretty {"data": [...], ...meta} envelope for lists
agent-mongo query count myapp users -f yaml

-f json gives a single pretty envelope ({"data": [...]} for lists, a bare pretty object for single results) — easier to eyeball than NDJSON when you're reading output yourself.

Connection management

agent-mongo connection list                              # saved connections + defaults
agent-mongo connection add staging "mongodb://..." --credential acme
agent-mongo connection update prod --credential new-cred
agent-mongo connection set-default staging
agent-mongo connection remove old-conn
agent-mongo connection test prod                         # verify connectivity (positional alias)
agent-mongo connection test -c prod                      # also works with -c flag

Connection resolution: -c flag > AGENTMONGOCONNECTION env > config default > error listing available connections.

Credential management

agent-mongo credential add acme --form                   # preferred interactive; see secure entry below
printf '%s' "$PW" | agent-mongo credential add acme --username deploy   # non-interactive machine path
agent-mongo credential list                              # passwords always redacted
agent-mongo credential remove acme --force               # even if connections reference it

Credentials are stored separately from connections, in the OS secret store when available (macOS Keychain, Linux Secret Service, Windows Credential Manager) with plaintext-config fallback. credential list shows the storage source per credential. Plaintext entries are auto-upgraded to the keychain on first use (reported via a stderr {"notice": ...} line — not an error). When you rotate a password, just re-add the credential — all connections referencing it pick up the new auth automatically.

Secure credential entry — never paste a secret into --password

If a user pastes a MongoDB password (or any secret) into chat, do not put it into --password. A literal secret on the command line would land in your context window, transcripts, shell history, ps//proc, and any downstream telemetry. Two safe paths supply the secret without ever putting it on argv:

1. --form — preferred interactive path. A native OS dialog (macOS osascript, Linux zenity/kdialog, Windows Win32) pops up and the user types the secret straight into the OS. The agent only sees a redacted JSON receipt. When the agent is driving the CLI on the user's machine, instruct the user to run the --form command themselves so the secret stays out of the LLM:

agent-mongo credential add acme --form                              # both fields prompted
agent-mongo credential add acme --username deploy --form            # only password prompted

2. Piped stdin — non-interactive machine path. For scripts, CI, or a headless host where no GUI is available, pipe the password on stdin. It is read off the stream, never placed on the command line. --username is not a secret and stays a flag:

printf '%s' "$PW" | agent-mongo credential add acme --username deploy

Password resolution precedence: --password flag > piped stdin > --form dialog. Prefer --form or stdin; reserve --password for values that are already non-secret (test fixtures, throwaway local dbs) — never for a secret pasted into chat.

--form failure modes return a structured error with fixable_by:

• human — no GUI session available (SSH, headless host). Ask the user to run on their local machine, or use the piped-stdin path above.
• retry — user cancelled the dialog. Re-running the same command is the right next step.

Truncation

Any string field exceeding truncation.maxLength (default 200) gets truncated with … and a companion {field}Length key showing original length.

agent-mongo --full query find myapp posts                # expand all fields
agent-mongo --expand description query find myapp posts  # expand specific field

These are global flags — place them before or after the command.

Timeout

Default timeout is 30s (configurable via query.timeout). Applies to both connection and query phases. Override per-command with -t/--timeout <ms>:

agent-mongo --timeout 60000 query find myapp large_collection --filter '{"status":"active"}'
agent-mongo --timeout 120000 collection schema myapp events

On timeout (MongoDB code 50), the error hint suggests increasing the timeout or checking indexes.

Configuration

agent-mongo config list-keys                             # all keys with defaults/ranges
agent-mongo config set defaults.limit 50
agent-mongo config get query.timeout
agent-mongo config reset                                 # restore defaults

Key settings: defaults.limit (20), defaults.sampleSize (5), defaults.schemaSampleSize (100), query.timeout (30000ms), query.maxDocuments (100), truncation.maxLength (200).

MCP server

agent-mongo mcp runs the read-only data commands (database, collection, query, connection) as MCP tools over stdio (or Streamable HTTP with --http <addr>). Credential and config commands are not exposed. See agent-mongo mcp usage for registration, OAuth, and Tailscale details.

Safety

• Read-only: No write operations exist
• Aggregation: $out and $merge stages rejected
• Result cap: query.maxDocuments (default 100)
• Timeout: applies to both connections and queries (default 30s), override per-command with -t/--timeout <ms>

Per-command usage docs

Every command group has a usage subcommand with detailed, LLM-optimized docs:

agent-mongo usage                  # top-level overview
agent-mongo connection usage       # connection commands
agent-mongo credential usage       # credential management
agent-mongo database usage          # database commands
agent-mongo collection usage       # collection commands
agent-mongo query usage            # all query commands
agent-mongo config usage           # settings keys, defaults, validation
agent-mongo mcp usage              # MCP server transports and registration

Use agent-mongo <command> usage when you need deep detail on a specific domain before acting.

References

• [references/auth.md](references/auth.md): identity-provider (OIDC) credentials
• [references/commands.md](references/commands.md): full command map + all flags
• [references/output.md](references/output.md): NDJSON output shapes + field details