MongoDB Connector

The MongoDB connector provides full access to MongoDB databases with 10 live tools spanning collection management, aggregation pipelines, index operations, and document CRUD.

Authentication

Provide a MongoDB connection string:

{
  "name": "Production MongoDB",
  "source_type": "mongodb",
  "config": {
    "connection_string": "mongodb+srv://agentcy:password@cluster0.abc123.mongodb.net/myapp",
    "database": "myapp",
    "read_only": true
  }
}

MongoDB Atlas

For Atlas clusters, use the mongodb+srv:// connection string from your cluster's connection dialog:

{
  "config": {
    "connection_string": "mongodb+srv://agentcy:password@cluster0.abc123.mongodb.net/?retryWrites=true&w=majority",
    "database": "myapp"
  }
}

Self-Hosted (Replica Set)

{
  "config": {
    "connection_string": "mongodb://agentcy:password@mongo1:27017,mongo2:27017,mongo3:27017/myapp?replicaSet=rs0&authSource=admin",
    "database": "myapp"
  }
}

TIP

Create a dedicated read-only user for Agentcy. In MongoDB, grant the read role on the target database.

Creating a Read-Only User

use admin
db.createUser({
  user: "agentcy",
  pwd: "secure-password",
  roles: [
    { role: "read", db: "myapp" }
  ]
})

Live Tools (10)

Tool	Description	Arguments
mongodb_list_collections	List all collections with document counts and sizes	database?
mongodb_find_one	Get a single document matching a filter with collection stats	collection, filter?
mongodb_find_documents	Query documents with filter, projection, sort, and limit	collection, filter?, projection?, sort?, limit?
mongodb_aggregate	Run an aggregation pipeline	collection, pipeline
mongodb_get_collection_stats	Get collection statistics including document count and size	collection
mongodb_list_indexes	List indexes on a collection	collection
mongodb_insert_document	Insert a single document	collection, document
mongodb_insert_many	Insert multiple documents	collection, documents
mongodb_update_documents	Update documents matching a filter	collection, filter, update, multi?
mongodb_delete_documents	Delete documents matching a filter	collection, filter, multi?

WARNING

The mongodb_insert_document, mongodb_insert_many, mongodb_update_documents, and mongodb_delete_documents tools are disabled when read_only is true (the default). Enable write access only when explicitly needed, and always with the approval flow enabled.

Example: Agent Using MongoDB Tools

User: "What collections are in the myapp database and what does the users collection look like?"

Agent: Let me explore the database.
→ Calls mongodb_list_collections()
→ Returns: users (145K docs, 89 MB), orders (2.1M docs, 1.2 GB),
   products (12K docs, 4 MB), sessions (890K docs, 320 MB)
→ Calls mongodb_find_one(collection: "users")
→ Reports inferred schema with field types, null rates, and sample documents

ETL Ingestion

Nodes Created

Node Label	Properties	Source
Database	name, type ("mongodb"), host, collections_count	Connection
Collection	name, database, document_count, avg_doc_size, total_size, capped	Collection stats
Index	name, collection, keys, unique, sparse, ttl	Index listing
MongoField	name, path, bson_type, null_percentage, distinct_count	Schema inference

Relationships Created

Relationship	From	To
CONTAINS	Database	Collection
HAS_INDEX	Collection	Index
HAS_FIELD	Collection	MongoField
REFERENCES	Collection	Collection (via DBRef or naming convention)

Graph Queries

-- Find collections without indexes (besides _id)
MATCH (c:Collection)
WHERE NOT (c)-[:HAS_INDEX]->(:Index {name: NOT "_id_"})
AND c.document_count > 10000
RETURN c.name, c.document_count

-- Map inter-collection references
MATCH (c1:Collection)-[:REFERENCES]->(c2:Collection)
RETURN c1.name, c2.name

-- Find the largest collections
MATCH (c:Collection)
RETURN c.name, c.document_count, c.total_size
ORDER BY c.total_size DESC
LIMIT 10

Configuration Reference

Field	Type	Default	Description
connection_string	string	required	MongoDB connection URI
database	string	required	Database to connect to
read_only	bool	true	Disable write tools (insert, update, delete)
max_query_docs	int	1000	Maximum documents returned by mongodb_find_documents
query_timeout_secs	int	30	Query execution timeout
schema_sample_size	int	100	Documents to sample for schema inference
sync_indexes	bool	true	Include indexes in ingestion
sync_schema	bool	true	Perform schema inference during ingestion
exclude_collections	string[]	[]	Collections to exclude from ingestion
tls	bool	auto	Enable TLS (auto-detected from connection string)
tls_ca_cert	string	--	CA certificate for TLS connections

Aggregation Pipeline Examples

The mongo_aggregate tool supports full MongoDB aggregation pipelines:

// Count orders by status
{
  "collection": "orders",
  "pipeline": [
    { "$group": { "_id": "$status", "count": { "$sum": 1 } } },
    { "$sort": { "count": -1 } }
  ]
}

// Find top customers by total spend
{
  "collection": "orders",
  "pipeline": [
    { "$match": { "created_at": { "$gte": "2025-01-01" } } },
    { "$group": {
      "_id": "$customer_id",
      "total_spent": { "$sum": "$total" },
      "order_count": { "$sum": 1 }
    }},
    { "$sort": { "total_spent": -1 } },
    { "$limit": 10 }
  ]
}

Troubleshooting

Error	Cause	Fix
Authentication failed	Invalid credentials or auth source	Verify username/password and authSource parameter
Connection timeout	Server unreachable or IP not allowlisted	Check network rules; for Atlas, add your IP to the allowlist
Not authorized on db	User lacks permissions on the target database	Grant the read role on the database
Topology closed	Connection pool exhausted or server shutdown	Check server health and connection limits
BSONError	Invalid query filter or pipeline syntax	Verify JSON syntax matches MongoDB query format