# Agent Mongo

> Read-only MongoDB CLI. Use when exploring databases, collections, schemas, or indexes, querying documents (find, get by id, count, sample, distinct, aggregate), checking database or collection statistics, or managing MongoDB connections and credentials — including identity-provider login (MONGODB-OIDC, workforce/workload identity federation, SSO).

- Skill: `shhac/agent-mongo` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add shhac/agent-mongo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shhac/agent-mongo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: shhac (https://skillmd.com/u/shhac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shhac/agent-mongo

---


# 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:

```bash
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:

```bash
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

```bash
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

```bash
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": {"has_more": ..., "total_items": ...}}` line — `has_more` means more documents match beyond the limit, `total_items` is the full matching count.

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

```bash
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

```bash
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`:

```bash
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

```bash
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 > `AGENT_MONGO_CONNECTION` env > config default > error listing available connections.

## Credential management

```bash
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:

```bash
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:

```bash
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.

```bash
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>`:

```bash
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

```bash
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:

```bash
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